Kubernetes Deployment

This guide deploys a full Bridge cluster on Kubernetes. It uses the same orchestrator / proxy / session roles as the AWS deployment, but the orchestrator creates workers as Kubernetes pods instead of ECS tasks. It works on managed Kubernetes (EKS, GKE, AKS) and on self-managed clusters.

Overview

You’ll create resources in a dedicated bridge namespace:

• A PostgreSQL database (a pod for testing, or point at a managed database for production).
• A ConfigMap holding the Bridge configuration.
• A Secret holding the encryption key and other secrets.
• The orchestrator Deployment, with a ServiceAccount and permission to manage pods.
• A Service that exposes the proxy pods to users.

The orchestrator creates the proxy and session pods itself - you don’t define them as static Deployments.

Architecture

This diagram follows the Helm chart and the downloadable bridge-cluster-k8s.yaml manifest. Kubernetes provides the scheduling, Service routing, and RBAC; Bridge’s orchestrator owns the proxy and session worker lifecycle.

    flowchart LR
  Clients["Approved clients<br/>(browser + native tools)"]
  Britive["Britive platform<br/>(optional broker connection)"]
  Targets["Target networks<br/>(services, nodes, databases, devices)"]

  subgraph Cluster["Kubernetes cluster"]
    subgraph Namespace["bridge namespace"]
      ProxySvc["bridge-proxy Service<br/>LoadBalancer / NodePort / L4 edge"]
      K8sApi["Kubernetes API<br/>pods create/watch/delete"]

      subgraph Control["Control plane resources"]
        Config["ConfigMap<br/>Bridge config"]
        Secrets["Secret<br/>cluster token + encryption key"]
        RBAC["ServiceAccount + RoleBinding"]
      end

      Orchestrator["Orchestrator pod<br/>migrations + reconciler<br/>optional co-located broker"]
      ProxyPods["Proxy pods<br/>spawned by orchestrator"]
      SessionPods["Session pods<br/>spawned by orchestrator"]
      Postgres[("PostgreSQL<br/>managed DB or bundled pod")]
      Recordings[("Shared recordings volume<br/>RWX PVC / EFS / Azure Files / NFS")]
    end
  end

  Clients -->|"HTTPS / native protocols"| ProxySvc
  ProxySvc -->|"ready proxy endpoints"| ProxyPods
  ProxyPods -->|"session control + relay"| SessionPods
  SessionPods -->|"protocol connection"| Targets

  Orchestrator -->|"uses RBAC"| K8sApi
  K8sApi -->|"creates / retires"| ProxyPods
  K8sApi -->|"creates / retires"| SessionPods

  Config --> Orchestrator
  Secrets --> Orchestrator
  RBAC --> Orchestrator

  Orchestrator --> Postgres
  ProxyPods --> Postgres
  SessionPods --> Postgres
  ProxyPods --> Recordings
  SessionPods --> Recordings
  Orchestrator --> Recordings

  Orchestrator <-->|"outbound TLS when broker is enabled"| Britive
  

You can deploy with Helm, or use the downloadable Kubernetes manifest below if you want to inspect and tune each resource by hand. The only external runtime artifact you need is the public britive/bridge container image.

Install with Helm

If you use Helm or Rancher (whose Apps catalog is Helm-based), install the Bridge chart from Docker Hub as an OCI chart:

export BRIDGE_CLUSTER_TOKEN="$(openssl rand -hex 32)"
export BRIDGE_ENCRYPTION_KEY_B64="$(openssl rand -base64 32)"
export BRIDGE_HOST_KEY_SEED="$(openssl rand -hex 16)"

helm install bridge oci://registry-1.docker.io/britive/bridge-chart \
  --version 2.0.0 \
  -n bridge --create-namespace \
  --set recordings.pvc.storageClassName="<ReadWriteMany-capable class>" \
  --set secrets.clusterToken="$BRIDGE_CLUSTER_TOKEN" \
  --set secrets.encryptionKeyB64="$BRIDGE_ENCRYPTION_KEY_B64" \
  --set secrets.hostKeySeed="$BRIDGE_HOST_KEY_SEED" \
  --set config.auth.britive.tenant="your-tenant"

--set recordings.mode=hostPath --set orchestrator.replicas=1

To enable the co-located broker and automatic online license retrieval, also set the broker-pool token:

helm upgrade --install bridge oci://registry-1.docker.io/britive/bridge-chart \
  --version 2.0.0 \
  -n bridge --create-namespace \
  --reuse-values \
  --set secrets.brokerAuthToken="<broker-pool-token>"

Configure runtime worker pods

The orchestrator creates session and proxy pods at runtime, so their pod settings come from worker.*, not from a Helm Deployment template.

Show every value before you build a production values file:

helm show values oci://registry-1.docker.io/britive/bridge-chart --version 2.0.0

Worker pods are scoped to the Helm release and carry an owner reference to its ConfigMap. helm uninstall therefore removes them. A Helm upgrade leaves running workers in place. The orchestrator replaces them when their image changes or when they reach the configured session limits and lifespans. A configuration-only change reaches a warm Kubernetes worker at its next normal cycle.

The default security contexts are compatible with the restricted Pod Security Standard only when recordings.mode=pvc. Kubernetes forbids hostPath volumes under both baseline and restricted, and Bridge needs a root init container to make its host path writable.

kubectl delete pods -n <namespace> -l 'app=bridge,bridge.role,!app.kubernetes.io/instance'

For production, point datastore.* at a managed PostgreSQL database, configure shared ReadWriteMany storage for recordings, pin a tested Bridge image tag, and front the proxy Service with an Ingress or cloud load balancer that terminates TLS. In Rancher, add the same OCI chart URL to Apps and set the equivalent values in the install form.

The rest of this guide walks the raw-manifest path, which is useful when you want to read or hand-tune every Kubernetes resource.

Before You Begin

You need:

• A working Kubernetes cluster and kubectl configured to reach it (kubectl get nodes should list your nodes).
• The starting manifest, downloaded here: bridge-cluster-k8s.yaml. You’ll customize it below.
• For production: a way to provide shared storage for recordings that every pod can read and write (a ReadWriteMany volume such as EFS, Azure Files, or NFS), and ideally a managed PostgreSQL database.

Deploy with the Manifest

docker pull britive/bridge:latest
docker tag britive/bridge:latest myregistry.example.com/bridge:latest
docker push myregistry.example.com/bridge:latest

echo "ENCRYPTION_KEY_B64: $(openssl rand -base64 32)"   # encrypts stored credentials
echo "CLUSTER_TOKEN:      $(openssl rand -hex 32)"        # secures internal cluster calls
echo "HOST_KEY_SEED:      $(openssl rand -hex 16)"        # stable SSH fingerprint across workers

apiVersion: v1
kind: Secret
metadata:
  name: bridge-secrets
  namespace: bridge
stringData:
  BRIDGE_DATASTORE_HOST: "bridge-postgres"
  BRIDGE_DATASTORE_PORT: "5432"
  BRIDGE_DATASTORE_USER: "bridge"
  BRIDGE_DATASTORE_PASSWORD: "bridge"
  BRIDGE_DATASTORE_NAME: "bridge"
  BRIDGE_DATASTORE_SSLMODE: "disable"
  BRIDGE_ENCRYPTION_KEY_B64: "<ENCRYPTION_KEY_B64 from Step 2>"
  BRIDGE_CLUSTER_TOKEN: "<CLUSTER_TOKEN from Step 2>"
  BRIDGE_HOST_KEY_SEED: "<HOST_KEY_SEED from Step 2>"

apiVersion: v1
kind: ConfigMap
metadata:
  name: bridge-config
  namespace: bridge
data:
  config.yaml: |
    cluster:
      session:
        max_concurrent_sessions: 1
        session_limit: 1          # one session, then the worker is replaced
        lifespan: "0s"            # no time-based replacement
      proxy:
        lifespan: "0s"            # "0s" = don't cycle proxies; e.g. "36h" in prod
        drain_deadline: "30s"
        max_cycle_concurrency: 1
      orchestrator:
        warm_session_workers: 3   # keep 3 session pods ready
        proxy_workers: 1          # keep 1 proxy pod running
        reconcile: "5s"           # how often to check and top up
        provisioner:
          platform: "k8s"
          path: "/opt/bridge/drivers/k8s/driver"
          k8s:
            image: "britive/bridge:latest"
            namespace: "bridge"
    server:
      listen: "8080"
      tls:
        enabled: false            # terminate TLS at an Ingress/load balancer
      recording:
        output_dir: /data/recordings
      auth:
        types: ["britive"]
        britive:
          tenant: "your-tenant"   # subdomain only, e.g. "acme" — see /reference/finding-your-tenant
    ssh:
      native:  { enabled: true, listen: "2222" }
      browser: { enabled: true }
      idle_timeout: "30m"

kubectl apply -f bridge-cluster-k8s.yaml

Verify

kubectl logs -f -n bridge deployment/bridge-orchestrator

kubectl get pods -n bridge -L bridge.role

kubectl get svc -n bridge bridge-proxy

kubectl port-forward -n bridge svc/bridge-proxy 8080:8888
# then open http://localhost:8080/

Production Notes

• TLS: Put an Ingress or cloud load balancer with a real certificate in front of the proxy Service, and keep tls.enabled: false in the config so TLS is terminated at the edge.
• Database: Use a managed PostgreSQL service instead of the in-cluster PostgreSQL pod, and point the Secret’s BRIDGE_DATASTORE_* values at it (set BRIDGE_DATASTORE_SSLMODE to require).
• Recordings: Use a ReadWriteMany persistent volume so recordings survive pod replacement and are readable cluster-wide. The volume must be writable by uid 102 and gid 103. For EFS, use an access point that owns the root directory as 102:103; the EFS CSI driver does not apply fsGroup ownership.
• Resources: Add CPU/memory requests and limits to the pods, sized for your session load (session pods do the heavy work).
• Image pulls: Pin a tested Bridge image tag for production. If your cluster cannot pull from Docker Hub, mirror that same tag into a private registry and update both image references in the manifest.

Troubleshoot

Next Steps

• Configure authentication
• Install and manage your license.
• Review protocols, recording, operations for the Admin console, upgrades, and backups.