Configure app networking
Networking decides who can reach an app and how. Each port gets a reach, from a public HTTPS URL to an address that only other apps in the same environment can use, so you expose exactly what you mean to. Behind every port, a Kubernetes Service balances traffic across the app’s replicas. You manage ports on the app’s Network tab.
Reach sets who can connect to a port. You choose it when you create an app.
| Reach | Result |
|---|---|
| Private link | An HTTPS URL behind Orchard sign-in. Only people with access to the project can open it. |
| Public link | An HTTPS URL open to anyone. |
| Public port | Raw TCP or UDP on an external address. |
| Internal | A cluster-internal address with no URL. |
UDP ports support only Public port and Internal.
Connect apps inside the cluster
Section titled “Connect apps inside the cluster”To call another app in the same environment, use its internal address. Network > Ports shows the address below each port, in this form:
<service>.<namespace>.svc.cluster.local:<port>Inside the same namespace, the short form <service>:<port> also resolves.
Use the internal address for traffic between apps. A request to a public URL leaves the cluster, depends on public DNS, and passes through the ingress.
Tenant namespaces deny incoming traffic by default. Apps in the same namespace can reach each other. Each environment has its own namespace, so apps in different environments cannot use internal addresses to reach each other.
Add a port
Section titled “Add a port”- Open the app.
- Go to Network.
- In Ports, select Add port.
- In Port, enter the port your process listens on inside the container.
- Select TCP or UDP.
- Select Add port.
orchard service create --deployment <id> --port 8080To use UDP, add --protocol UDP.
Publish a TCP or UDP port
Section titled “Publish a TCP or UDP port”Publish a raw port to reach a game server or another non-HTTP service from outside the cluster.
Prerequisites
Section titled “Prerequisites”- A layer 4 (L4) load balancer in the cluster.
- A public IP address. To set one for your organization, go to Organization settings > Database defaults > Public database IP. Otherwise, the organization inherits the instance default. If neither exists, publishing fails with an error. A superadmin sets the instance default as described in Set a default public IP.
This feature is not available in Cloudflare Tunnel mode, because tunnels carry HTTP only.
- Open the app.
- Go to Network.
- In Ports, turn on Public for the port.
- Select Make public.
The public address replaces the internal address on the row. Until the load balancer assigns the address, the row shows Waiting for an address. If the load balancer reports an error, the row shows the reason instead. For the causes, refer to Troubleshoot a public address.
orchard service port public enable <service-id> <port-id> --deployment <id>Troubleshoot a public address
Section titled “Troubleshoot a public address”A public port or a public database is reachable only after the cluster’s load balancer assigns it an address. Orchard reads the state from Kubernetes and shows one of these states:
| State | Meaning |
|---|---|
| Live | The load balancer assigned the address. The port accepts connections. |
| Waiting for an address | The load balancer has not assigned an address yet. A cloud load balancer can take minutes. |
| An error with a reason | The load balancer reported a problem. The address does not accept connections. |
If Orchard cannot read the state from Kubernetes, the row shows the address without Live.
| Reason | Cause and fix |
|---|---|
| Port N is already in use on the server | On k3s, the built-in load balancer (ServiceLB) listens on the port on every node, and another LoadBalancer Service or a pod with a host port already holds that port. Turn Public off and on to get a new port, or remove the other Service. |
| No address could be allocated or No address could be assigned | MetalLB or Cilium has no free address in its pool, or the public IP is not in a pool. Add the organization’s public IP to an address pool, or free an address. |
| The load balancer could not be created | The cloud provider rejected the request. The reason includes the provider’s message, for example a quota limit. Fix the cause in the cloud account. Orchard picks up the address when the provider assigns it. |
| The load balancer assigned X instead of Y | The load balancer ignores the requested IP address. Set the organization’s public IP to the assigned address, or configure the load balancer to honor spec.loadBalancerIP. |
| No load balancer assigned an address after 5 minutes | Nothing in the cluster handles LoadBalancer Services. Install a load balancer such as MetalLB, or use k3s with ServiceLB. |
To read the full history, run kubectl describe service <name> -n <namespace> and check Events.
Outbound traffic
Section titled “Outbound traffic”Apps can reach the public internet. The tenant network policy blocks traffic to private address ranges and to the link-local range that holds cloud metadata services. It also blocks the Kubernetes API, the control-plane database, and unpublished services in other namespaces.
Request headers
Section titled “Request headers”Traffic reaches your app through at least one proxy, so the socket peer is the proxy. Client details arrive in headers.
| Header | Set by | Contains |
|---|---|---|
X-Real-IP | The ingress | The peer of the inbound TCP connection |
X-Forwarded-For | The ingress, appended for each hop | The client chain, left to right |
X-Forwarded-Proto | The ingress | https or http, as the client saw it |
X-Forwarded-Host | The proxy | The hostname the client requested |
To get the client address, use X-Real-IP. The ingress sets it to the actual peer and overwrites any value from the client.
Clients can add entries to X-Forwarded-For. Trust only the entries your own proxies added. If your framework derives the client IP from this header, configure the number of proxy hops to trust.
A domain with protection adds a hop. The protection proxy forwards these headers and appends the peer it saw. It removes x-orchard-protection-bypass before the request reaches your app.
To build absolute URLs, use X-Forwarded-Proto and X-Forwarded-Host. Otherwise, a framework can generate links that point at a pod IP address.
Databases
Section titled “Databases”Managed databases are reachable inside the cluster by default. To publish one, refer to Public access.
Related resources
Section titled “Related resources”- Manage domains and HTTPS - Add a custom domain to an app and redirect domains.
- Reach apps over Tailscale - Give an app a private address on your tailnet.