Port Exposure Model for Catalog Services

This page explains what kinds of network access OSC catalog services can expose, and what to do if your service's networking requirements do not fit.

The single-port rule

Every service instance on OSC communicates with the outside world through exactly one HTTP endpoint. The platform ingress controller terminates TLS on port 443 and proxies HTTPS traffic to your container. The port your container listens on is injected as the PORT environment variable at startup, and the ingress routes traffic to that port automatically.

This means your service only needs to read PORT and bind to it. No firewall rules, load balancer configuration, or port mapping is required on your part.

What the platform does not support for creator submissions

Four categories of service are not supported in the public catalog today:

Additional TCP ports. The platform allocates one HTTP ingress path per service instance. A service that needs a second TCP port for client connections (separate control and data planes, SMTP, raw IMAP/POP3, custom game-client protocols) cannot be served by the catalog ingress model.

Any UDP port exposed to the public internet. The cluster infrastructure does not expose UDP to the internet through the standard service path. Services that depend on UDP for their core function (media relay servers, most VPN protocols, DNS resolvers, gaming servers that use UDP for state) are not a fit for the catalog.

Dynamic or ephemeral relay port ranges. Some protocols allocate relay ports at runtime from a range rather than a fixed address (TURN relay allocations, FTP passive mode, SIP/RTP media streams, game servers that use per-session ports). These cannot be supported with a fixed-port ingress model.

Self-managed TLS on port 443. Port 443 is held by the shared platform ingress controllers. A service that needs to terminate TLS itself, or that binds directly to 443, will conflict with the ingress and cannot run in the catalog.

Why these limits exist

Port allocation on the cluster's load balancer is a shared, finite resource. The Elastx infrastructure caps one Octavia load balancer at 20 listeners (ADR-0032). Granting per-service port allocations to creator submissions would exhaust that budget quickly and create instability for all other services on the platform. The single-HTTP-port model is what makes it practical to run hundreds of catalog services on shared infrastructure.

If your service does not fit

There are two paths forward.

The first option is to run your service off-platform, hosted on infrastructure you control. OSC can still be useful to you if parts of your stack (databases, object storage, task queues) fit the catalog model and your service connects to them as dependencies.

The second option is to file a ticket with the supply team explaining your use case. The CTO reviews these on a case-by-case basis to determine whether the service warrants operator-managed exposure. This is not a standard pathway and should not be assumed to be available, but it exists for genuinely compelling cases.

Historical exceptions

Three services on OSC expose non-HTTP ports today: srperens-uturn (UDP 3478 for STUN/TURN relay), eyevinn-docker-wrtc-sfu (WebRTC SFU ports), and eyevinn-strom (streaming-specific ports). These are operator-managed placements on a dedicated, specially-tainted node in the cluster. They predate the port budget constraints that apply today and are not a template for new services. Creator submissions are evaluated against the current model described on this page.

For the STUN/TURN specifics of uTURN, see WebRTC uTURN Networking.