Reverse Proxy on OpenShift

Updated September 28, 2026

This guide deploys the NetBird reverse proxy on OpenShift so an external client can reach a backend Service over the NetBird overlay. The proxy obtains and renews its own TLS certificates with ACME, runs under the stock restricted-v2 security context constraint, and needs no custom SCC, privileged mode, host networking, or elevated capabilities.

It uses the rootless proxy image built on Red Hat Universal Base Image (UBI) 9 and published for Linux AMD64 and ARM64. The image runs as a non-root user and keeps its writable directories group-writable so OpenShift can assign an arbitrary UID. The manifest in Step 2 pins the image tag; pin a version or digest for reproducible deployments and see NetBird releases for new versions.

By the end of this guide, the namespace contains:

How it works

The proxy is an ordinary NetBird reverse proxy instance: it registers with your management server over gRPC, receives the service mappings for its cluster domain, requests a certificate from Let's Encrypt for each service hostname, terminates TLS, and forwards traffic through the NetBird overlay to a routing peer that reaches the backend Service.

Only the proxy is reachable from the Internet. The backend Service stays ClusterIP and is reached through the routing peer only.

The public TCP entrypoint must forward TCP 443 to the proxy without terminating TLS, so the proxy can answer the Let's Encrypt tls-alpn-01 challenge and present the issued certificate itself. OpenShift offers two ways to do that. Decide which one applies to your cluster before you start, because it determines your DNS records and your ongoing work:

Prerequisites

Before you start, make sure you have:

• An OpenShift login with permission to create Deployments, Services, Secrets, PersistentVolumeClaims and, for the Route fallback, Routes in the target namespace. No additional SCC is needed.
• A default StorageClass that can provision a 1 GiB PVC.
• A proxy access token from your NetBird management server. This is not a client setup key or a personal access token:
  • NetBird Cloud - create an account-scoped token in the dashboard under Reverse Proxy > Clusters > Setup Self-Hosted Cluster, or through the API. See Bring Your Own Proxy. The management address is https://api.netbird.io.
  • Self-hosted - create a management-wide token with netbird-server admin token create (combined container) or netbird-mgmt admin token create (multi-container). See Enable Reverse Proxy. The management address is your management server's public URL. Because this proxy runs outside the management host's Docker network, the management server's Traefik must also route the ProxyService gRPC path and have its idle timeout disabled. Follow Prepare the management server for cross-host proxies first. This Traefik requirement applies to the management server, not to the proxy deployed here.
• Public DNS names you control, and inbound TCP 443 connectivity from the Internet to the proxy.
• Outbound access from the cluster to your NetBird management server, the configured signal and relay services, Let's Encrypt, and pkgs.netbird.io, from which the proxy downloads its geolocation database at startup.
• A NetBird routing peer that can reach the backend Service. Step 4 uses the rootless UBI client from the OpenShift installation guide deployed in the same cluster.

The guide uses three values. Replace the examples with your own:

Export them for the commands in this guide, then create the namespace:

export NB_PROXY_DOMAIN=proxy.example.com
export NB_PROXY_MANAGEMENT_ADDRESS=https://netbird.example.com:443
export SERVICE_HOSTNAME=nginx.proxy.example.com
export NAMESPACE=netbird-proxy

oc create namespace "$NAMESPACE" --dry-run=client -o yaml | oc apply -f -

Step 1: Create the configuration Secret

The Deployment reads its token, cluster domain, and management address from a Secret named netbird-proxy-config. Create it with your proxy access token:

export NB_PROXY_TOKEN=nbx_replace_with_your_proxy_token

oc create secret generic netbird-proxy-config -n "$NAMESPACE" \
  --from-literal=proxy-token="$NB_PROXY_TOKEN" \
  --from-literal=proxy-domain="$NB_PROXY_DOMAIN" \
  --from-literal=management-address="$NB_PROXY_MANAGEMENT_ADDRESS" \
  --dry-run=client -o yaml | oc apply -f -

The command is safe to re-run to change a value. The proxy picks up changes only after a restart: oc rollout restart deployment/netbird-proxy -n "$NAMESPACE".

Step 2: Deploy the proxy

Self-issued ACME certificates and their account keys live on a single writable volume. The Deployment therefore runs one replica with the Recreate strategy, uses filesystem locking for the certificate cache, and mounts a PersistentVolumeClaim at /certs so the ACME account and issued certificates survive pod replacement.

Save the following as netbird-proxy.yaml. It needs no edits; every environment-specific value comes from the Secret, and the namespace comes from the oc apply command.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: netbird-proxy-certs
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: netbird-proxy
  labels:
    app.kubernetes.io/name: netbird-proxy
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app.kubernetes.io/name: netbird-proxy
  template:
    metadata:
      labels:
        app.kubernetes.io/name: netbird-proxy
    spec:
      automountServiceAccountToken: false
      securityContext:
        runAsNonRoot: true
        seccompProfile:
          type: RuntimeDefault
      containers:
        - name: proxy
          image: ghcr.io/netbirdio/reverse-proxy:0.80.0-ubi
          imagePullPolicy: IfNotPresent
          env:
            - name: NB_PROXY_TOKEN
              valueFrom:
                secretKeyRef:
                  name: netbird-proxy-config
                  key: proxy-token
            - name: NB_PROXY_DOMAIN
              valueFrom:
                secretKeyRef:
                  name: netbird-proxy-config
                  key: proxy-domain
            - name: NB_PROXY_MANAGEMENT_ADDRESS
              valueFrom:
                secretKeyRef:
                  name: netbird-proxy-config
                  key: management-address
            - name: NB_PROXY_ADDRESS
              value: :8443
            - name: NB_PROXY_HEALTH_ADDRESS
              value: :8080
            - name: NB_PROXY_ACME_CERTIFICATES
              value: "true"
            - name: NB_PROXY_ACME_CHALLENGE_TYPE
              value: tls-alpn-01
            - name: NB_PROXY_CERTIFICATE_DIRECTORY
              value: /certs
            - name: NB_PROXY_CERT_LOCK_METHOD
              value: flock
            - name: NB_PROXY_SUPPORTS_CUSTOM_PORTS
              value: "false"
          ports:
            - name: https
              containerPort: 8443
            - name: health
              containerPort: 8080
          securityContext:
            allowPrivilegeEscalation: false
            capabilities:
              drop:
                - ALL
          startupProbe:
            httpGet:
              path: /healthz/startup
              port: health
            periodSeconds: 5
            timeoutSeconds: 3
            failureThreshold: 60
          readinessProbe:
            httpGet:
              path: /healthz/ready
              port: health
            periodSeconds: 10
            timeoutSeconds: 3
          livenessProbe:
            httpGet:
              path: /healthz/live
              port: health
            periodSeconds: 10
            timeoutSeconds: 3
          resources:
            requests:
              cpu: 100m
              memory: 256Mi
          volumeMounts:
            - name: certificates
              mountPath: /certs
      volumes:
        - name: certificates
          persistentVolumeClaim:
            claimName: netbird-proxy-certs
---
apiVersion: v1
kind: Service
metadata:
  name: netbird-proxy
  labels:
    app.kubernetes.io/name: netbird-proxy
spec:
  type: ClusterIP
  selector:
    app.kubernetes.io/name: netbird-proxy
  ports:
    - name: https
      port: 443
      targetPort: https

Apply it and wait for the rollout:

oc apply -n "$NAMESPACE" -f netbird-proxy.yaml
oc rollout status deployment/netbird-proxy -n "$NAMESPACE" --timeout=5m

The Service is ClusterIP on purpose. Step 3 either switches it to LoadBalancer or leaves it internal and puts Routes in front of it.

Checkpoint. The startup probe passes only after the proxy has connected to management and completed its initial mapping sync, so a finished rollout confirms the token and management address are correct. Check the PVC and the logs:

oc get pvc netbird-proxy-certs -n "$NAMESPACE"
oc logs deployment/netbird-proxy -n "$NAMESPACE" --tail=50

The PVC is Bound, the logs contain Initial mapping sync complete, and the cluster appears in the dashboard under Reverse Proxy > Clusters with an Online badge. If the rollout times out, see Troubleshooting.

Configuration explained

For the full list of variables, see the environment variable reference.

Step 3: Expose the proxy

Pick the option you chose in How it works. In both cases, public TCP 443 must reach the proxy's port 8443 for the initial certificate issuance as well as every renewal.

Preferred exposure: a TCP LoadBalancer

If your cluster has a LoadBalancer provider, change the Service type. No Route is needed in this mode:

oc patch service netbird-proxy -n "$NAMESPACE" -p '{"spec":{"type":"LoadBalancer"}}'
oc get service netbird-proxy -n "$NAMESPACE"

A working provider allocates an externally reachable address in the EXTERNAL-IP column and forwards TCP 443 to the proxy as plain TCP. A cloud network load balancer or MetalLB with public routing both qualify. MetalLB alone does not make a private address reachable from the Internet.

Point the cluster domain at the provisioned address with an A/AAAA record for an IP, or a CNAME for a load balancer hostname. Then point the service hostnames at the cluster domain with a wildcard CNAME:

Publish an AAAA record only if the IPv6 path also works end to end. The NetBird proxy routes by the hostname in the TLS handshake and handles every configured service hostname itself, so new services need no further OpenShift changes.

Checkpoint. EXTERNAL-IP shows an address instead of <pending>, and dig "$SERVICE_HOSTNAME" resolves to it.

Fallback without a LoadBalancer: TLS-passthrough Routes

If the cluster has no LoadBalancer provider, use the existing public OpenShift ingress router instead. Leave the netbird-proxy Service as ClusterIP. If you already switched it to LoadBalancer and EXTERNAL-IP stayed <pending>, switch it back:

oc patch service netbird-proxy -n "$NAMESPACE" -p '{"spec":{"type":"ClusterIP"}}'

The OpenShift router picks a backend by matching the Route's hostname against the SNI in the TLS handshake, not by Service name. Every service hostname NetBird knows about therefore needs its own Route with TLS passthrough, pointing at the proxy Service. It is one Route per hostname, not one Kubernetes Service per hostname.

Create the Route for the example service hostname:

oc create route passthrough nginx-proxy -n "$NAMESPACE" \
  --hostname="$SERVICE_HOSTNAME" \
  --service=netbird-proxy \
  --port=https

The equivalent manifest, applied with oc apply -n "$NAMESPACE" -f:

apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: nginx-proxy
spec:
  host: nginx.proxy.example.com
  to:
    kind: Service
    name: netbird-proxy
  port:
    targetPort: https
  tls:
    termination: passthrough

Then configure DNS. The cluster domain points at the public OpenShift ingress endpoint, and the service hostnames point at the cluster domain:

DNS gets the connection to the router. The Route's hostname match gets it from the router to the NetBird proxy. A CNAME does not change the hostname sent in the TLS handshake, so the Route must match the service hostname exactly. A Route for the bare cluster domain or for a parent domain does not match nginx.proxy.example.com.

Checkpoint. The router admitted the Route:

oc get route nginx-proxy -n "$NAMESPACE" \
  -o jsonpath='{range .status.ingress[*].conditions[*]}{.type}={.status}: {.message}{"\n"}{end}'

The output shows Admitted=True, and dig "$SERVICE_HOSTNAME" resolves to the router's public endpoint.

Adding more services

Each service you add in NetBird later, including services on a custom domain, needs its own Route before its certificate can be issued. Create it with a unique name, keeping --service=netbird-proxy --port=https:

oc create route passthrough app-proxy -n "$NAMESPACE" \
  --hostname=app.proxy.example.com \
  --service=netbird-proxy \
  --port=https

If a Route for the hostname already exists, update it rather than creating a duplicate.

Step 4: Connect a backend

The backend proves end-to-end connectivity. It should be reachable only through the proxy and the NetBird overlay, never directly from the Internet.

Deploy a test backend

Deploy an unprivileged nginx listening on port 8080, fronted by a ClusterIP Service named nginx-server that maps HTTP port 80 to the container's port 8080. Save it as nginx-server.yaml and apply it with oc apply -n "$NAMESPACE" -f nginx-server.yaml. Keep this Service internal; the public entrypoint targets the NetBird proxy, not nginx.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-server
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx-server
  template:
    metadata:
      labels:
        app: nginx-server
    spec:
      automountServiceAccountToken: false
      securityContext:
        runAsNonRoot: true
        seccompProfile:
          type: RuntimeDefault
      containers:
        - name: nginx
          image: docker.io/nginxinc/nginx-unprivileged:stable-alpine
          ports:
            - name: http
              containerPort: 8080
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop: [ALL]
          readinessProbe:
            httpGet:
              path: /
              port: http
          resources:
            requests:
              cpu: 10m
              memory: 16Mi
            limits:
              memory: 64Mi
          volumeMounts:
            - name: tmp
              mountPath: /tmp
      volumes:
        - name: tmp
          emptyDir: {}
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-server
spec:
  type: ClusterIP
  selector:
    app: nginx-server
  ports:
    - name: http
      port: 80
      targetPort: http

Add the backend to NetBird

The proxy reaches the backend through a routing peer, so the backend has to exist as a network resource first:

1. Deploy a routing peer in the cluster. Follow OpenShift Installation to run the rootless UBI client, preferably with a persistent peer identity so the routing peer assignment survives restarts.

2. Create a network and a domain resource with the address nginx-server.netbird-proxy.svc.cluster.local (replace netbird-proxy if you changed NAMESPACE), and assign the UBI client as its routing peer. Any pod in the cluster can resolve and reach this Service. See Networks.

3. Add an access policy that lets the proxy's embedded peer reach the resource. The proxy joins your NetBird network as a peer when it receives its first service mapping. See Access Control.

4. Create the reverse proxy service under Reverse Proxy > Services > Add Service. See the Reverse Proxy quick start for the full dialog.

   Field	Value
   Subdomain	nginx
   Base domain	Your cluster domain, proxy.example.com
   Mode	HTTP
   Target	The nginx-server Domain resource
   Protocol	HTTP
   Port	80
   Authentication	As needed. See Authentication.

The proxy requests a certificate for a service hostname only when management sends it the service mapping, so this last step is what triggers issuance. A DNS record or a Route alone does not register a service.

Checkpoint. The service under Reverse Proxy > Services moves from certificate_pending to active, and the proxy logs contain certificate for domain "nginx.proxy.example.com" ready.

Step 5: Verify end to end

From outside the cluster, check HTTPS without disabling certificate verification:

curl --head --show-error --connect-timeout 10 "https://$SERVICE_HOSTNAME/"

HTTPS must present a trusted certificate for the service hostname. An authentication redirect or denial is expected if you enabled authentication on the service; after authenticating in a browser, the nginx welcome page confirms the backend is reachable over the overlay.

Optionally, confirm the pod was admitted under restricted-v2 with an OpenShift-assigned UID:

oc get pods -n "$NAMESPACE" -l app.kubernetes.io/name=netbird-proxy \
  -o 'custom-columns=NAME:.metadata.name,SCC:.metadata.annotations.openshift\.io/scc,UID:.spec.containers[0].securityContext.runAsUser'

Operating the proxy

Upgrading

Change the image tag in netbird-proxy.yaml and re-apply it. Because the Deployment uses Recreate, the old pod stops before the new one starts, so expect a short interruption for every service on this cluster. The PVC keeps the issued certificates, so the new pod does not request new ones.

Running more than one replica

This configuration runs a single replica because the certificate cache is on a ReadWriteOnce volume. Do not raise replicas as-is. For high availability, run additional instances with the same cluster domain, each with its own certificate volume, or switch to a shared wildcard certificate as described in Using cert-manager instead of ACME. See Running Multiple Proxy Instances for the trade-offs.

Using cert-manager instead of ACME

If cert-manager already issues certificates in your cluster, you can mount its TLS Secret at /certs as a read-only volume, set NB_PROXY_ACME_CERTIFICATES=false, and drop the PVC and lock settings. The certificate must cover the cluster domain and *.{cluster domain} for the proxy to serve every service hostname. Choose one certificate-management mode for the Deployment rather than combining both. See TLS certificate configuration.

Using http-01 instead of tls-alpn-01

This guide uses tls-alpn-01 because it needs only TCP 443. Switch to http-01 only if your ACME CA or network policy requires it.

With http-01, Let's Encrypt validates each service hostname by connecting to it on public port 80. The proxy answers on a separate plain-HTTP listener set by NB_PROXY_ACME_ADDRESS. The UBI image sets it to :8081, because a non-root container under restricted-v2 cannot bind ports below 1024. Public port 80 must reach container port 8081. If only TCP 443 is exposed, as in the rest of this guide, every validation fails and services stay in certificate_pending.

1. In the Deployment, change the challenge type, set the challenge address explicitly, and expose the port:

   env:
     - name: NB_PROXY_ACME_CHALLENGE_TYPE
       value: http-01
     - name: NB_PROXY_ACME_ADDRESS
       value: :8081
   ports:
     - name: acme-http
       containerPort: 8081
   

   CopyCopied!

2. Add port 80 to the netbird-proxy Service, next to the existing https port:

   ports:
     - name: https
       port: 443
       targetPort: https
     - name: http
       port: 80
       targetPort: acme-http
   

   CopyCopied!

3. Re-apply the manifest and confirm the load balancer forwards both TCP 80 and TCP 443 from the Internet.

The challenge listener answers only ACME requests and redirects all other HTTP requests to HTTPS, so opening port 80 does not expose services over plain HTTP.

Removing the deployment

Delete the NetBird services that use this cluster in the dashboard first, then remove the OpenShift resources:

oc delete namespace "$NAMESPACE"

This also deletes the certificate PVC. If you plan to redeploy with the same hostnames soon, delete the Deployment, Service, and Routes instead and keep the PVC to avoid re-issuing certificates.

Troubleshooting

The rows follow the order in which things happen: pod start, management connection, public exposure, certificate issuance, and backend traffic.

Do not repeatedly delete the certificate PVC or restart the proxy to retry issuance before fixing DNS or public routing. Each attempt counts against Let's Encrypt rate limits.

Related pages

• OpenShift Installation - run the rootless UBI NetBird client on OpenShift, including as a routing peer
• Bring Your Own Proxy - account-scoped proxy tokens and clusters on NetBird Cloud
• Enable Reverse Proxy - management-wide proxy tokens and the full environment variable reference
• Running Multiple Proxy Instances - management server preparation for remote proxies and HA patterns
• Custom Domains - use your own domain for service hostnames
• Reverse Proxy Troubleshooting - diagnose backend connectivity problems