Skip to content
Install

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.

ReachResult
Private linkAn HTTPS URL behind Orchard sign-in. Only people with access to the project can open it.
Public linkAn HTTPS URL open to anyone.
Public portRaw TCP or UDP on an external address.
InternalA cluster-internal address with no URL.

UDP ports support only Public port and Internal.

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.

  1. Open the app.
  2. Go to Network.
  3. In Ports, select Add port.
  4. In Port, enter the port your process listens on inside the container.
  5. Select TCP or UDP.
  6. Select Add port.

Publish a raw port to reach a game server or another non-HTTP service from outside the cluster.

  • 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.

  1. Open the app.
  2. Go to Network.
  3. In Ports, turn on Public for the port.
  4. 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.

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:

StateMeaning
LiveThe load balancer assigned the address. The port accepts connections.
Waiting for an addressThe load balancer has not assigned an address yet. A cloud load balancer can take minutes.
An error with a reasonThe 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.

ReasonCause and fix
Port N is already in use on the serverOn 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 assignedMetalLB 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 createdThe 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 YThe 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 minutesNothing 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.

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.

Traffic reaches your app through at least one proxy, so the socket peer is the proxy. Client details arrive in headers.

HeaderSet byContains
X-Real-IPThe ingressThe peer of the inbound TCP connection
X-Forwarded-ForThe ingress, appended for each hopThe client chain, left to right
X-Forwarded-ProtoThe ingresshttps or http, as the client saw it
X-Forwarded-HostThe proxyThe 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.

Managed databases are reachable inside the cluster by default. To publish one, refer to Public access.