Exposing Spaces externally

You can expose Spaces externally using of three options:

Option	When to use
LoadBalancer Service	Simplest setup, recommended for most deployments
Gateway API	Organization already using Gateway API, or need shared gateway across services
Ingress	Organization already using Ingress, or need shared load balancer across services

LoadBalancer Service

Upbound recommends a LoadBalancer Service to expose spaces-router.

important

Use a Network Load Balancer (L4), not an Application Load Balancer (L7). Spaces uses long-lived connections for watch traffic that L7 load balancers may timeout.

Configuration

externalTLS:
  host: proxy.example.com  # Externally routable hostname for TLS certificates

router:
  proxy:
    service:
      type: LoadBalancer
      annotations:
        # AWS NLB (see Cloud-Specific Annotations for other clouds)
        service.beta.kubernetes.io/aws-load-balancer-type: external
        service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
        service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip

See Cloud-Specific Annotations for GCP and Azure.

Get the LoadBalancer address

After installation:

kubectl get svc -n upbound-system spaces-router \
  -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'

Create or update a DNS record pointing your externalTLS.host to this address.

Ingress

Use Ingress if you need to share a load balancer across multiple services or have specific networking requirements.

Requirements

• TLS passthrough support in your Ingress controller
• Network Load Balancer (L4) strongly recommended for long-lived connections

Configure your Ingress controller's Service with NLB annotations.

Configuration

ingress:
  provision: true
  host: proxy.example.com
  ingressClassName: "<your-ingress-class>"
  # Annotations to add to the Ingress resource
  annotations: {}
  # Pod labels of the Ingress controller - used for network policy
  podLabels: {}
  # Namespace labels of the Ingress controller - used for network policy
  namespaceLabels: {}

Traefik (with nginx provider)

Traefik can use the kubernetesIngressNGINX provider to handle nginx-style Ingress resources with TLS passthrough.

ingress:
  provision: true
  host: proxy.example.com
  ingressClassName: nginx
  annotations:
    nginx.ingress.kubernetes.io/ssl-passthrough: "true"
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
  podLabels:
    app.kubernetes.io/name: traefik
  namespaceLabels:
    kubernetes.io/metadata.name: traefik

Gateway API

Spaces supports the Gateway API. Use this option if your organization is already using Gateway API or needs a shared gateway across multiple services.

Requirements

• A Gateway API controller (for example, Envoy Gateway, Cilium, or Traefik)
• Gateway API CRDs installed in your cluster
• TLS passthrough support
• Network Load Balancer (L4) strongly recommended

Cloud-specific annotations

Network Load Balancers (L4) are strongly recommended. Spaces uses long-lived watch connections (hours or days) for kubectl and ArgoCD. L7 load balancers may timeout these connections. Use these annotations on the LoadBalancer Service (spaces-router, Ingress controller, or Gateway).

Cloud	Annotations
AWS	service.beta.kubernetes.io/aws-load-balancer-type: external service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip
GCP	cloud.google.com/l4-rbs: enabled
Azure	None required (L4 by default)