Upgrade to Bridge v3

Overview

This guide upgrades an existing Bridge v2 deployment to Bridge v3.0.0. Kubernetes deployments that use Helm also move to chart 3.0.0. Keep the existing PostgreSQL database, recordings, and encryption key.

If you run Bridge v1, complete Upgrade to Bridge v2 first.

Before you begin

Prepare and test the upgrade outside production. Collect:

• The current image tag or digest, deployment manifests or template, effective configuration, and broker profile scripts.
• Restorable backups of PostgreSQL and the recordings volume. A database backup alone does not contain the recording files.
• Secure copies of deployment secrets, especially the existing encryption key and SSH host-key seed. Preserve both values through the upgrade.
• An inventory of target hosts, ports, certificates, SSH host keys, and the username forms used by checkouts.
• A test checkout for each protocol and connection method you use, plus an admin or auditor checkout for recording review.
• A maintenance window and a way to pause new Britive access grants while you validate the deployment.

Check available database connections, recording storage, and worker capacity. Measure checkout, checkin, connection startup, and interactive responsiveness before the upgrade so you can compare afterward.

Prepare target trust

v3 verifies target identity before forwarding credentials. Changing the Bridge image without preparing targets can cause previously working connections to fail.

For the listed databases, put a private CA certificate in the checkout’s target_ca_cert, or make it available in the session worker’s trust store. A database certificate addressed by IP needs an appropriate IP subject alternative name. Changing a checkout to use a DNS name may also change the target portion of native connection usernames.

For RDP, provide approved private CA certificates through BRIDGE_EXTRA_CA_CERTS, or the AWS template’s ExtraCaCertsPem parameter. RDP name matching uses the certificate’s common name or DNS-type alternative names. For an IP target, include that exact address in one of those fields; an IP-type alternative name alone is insufficient.

Do not use a key or CA retrieved from an unverified connection as proof of target identity. Review existing certificate-verification exceptions rather than carrying them forward automatically. Older exceptions on plaintext checkouts do not automatically become active when TLS is required.

Review authentication and integrations

Update broker checkout management

The bundled broker now manages checkouts through a private loopback API, using its own local credential file. Public cluster-header credentials no longer grant user or administrator access.

Update downloaded checkout and checkin scripts to use the bundled broker-bridge-api.sh helper. Remove old public BRIDGE_API_URL, --cluster-token, and --admin-token overrides. The defaults are:

Bridge creates the credential file. Do not copy a cluster token into it, publish port 8081, or route this API through a load balancer. These settings belong on the standalone container or orchestrator that runs the colocated broker.

Review checkout payloads as well. Supply target trust settings and, for native Bridge-managed authentication, a separate bridge_auth_password with native_auth: bridge_credentials. Keep the vaulted target credential separate from the password a user presents to Bridge. Test directory authentication and credential passthrough wherever you use them.

Check browser and administrative access

• Configure Britive OAuth or LDAP for web login. The development administrator shortcut is removed.
• Give reviewers their own admin or auditor checkout. Legacy auditor bearer tokens no longer grant recording access.
• Replace monitoring that uses cluster credentials with read-only service tokens.
• Update automation that creates further checkouts from a temporary admin checkout. Use the platform broker or an independently authorized permanent administrator.

Existing browser logins and pending OAuth sign-ins are invalidated by the upgrade. Users must sign in again.

Single-directory LDAP configuration remains supported. Adopting multiple directories is optional. If you do, configure TLS on each named connection and preserve the exact username form issued by the checkout, such as a UPN or a domain-qualified name.

Prepare the deployment

Keep public TLS separate from cluster TLS

Keep a trusted HTTPS certificate on the public browser endpoint and retain the registered OAuth callback URL. Native clients that verify Bridge’s certificate also need a certificate matching the public Bridge hostname. The generated development certificate is not a substitute.

Cluster peer authentication uses separate identities that Bridge initializes in PostgreSQL. You do not need to distribute the public website’s private key to configure peer authentication.

For clustered deployments:

• Supply the same BRIDGE_CLUSTER_TOKEN, generated from at least 32 random bytes, to all roles. Keep an existing sufficiently random value; replace short or weak values.
• Permit internal TCP 9443 from orchestrators to proxies. Keep it private.
• Point proxy and session-worker health probes at HTTP port 9091. Their authenticated APIs cannot serve ordinary load-balancer probes.
• Restrict worker API and control listeners to the required cluster peers. Do not publish them to users.

Keep native listener transports appropriate to each protocol. Replacing SSH, RDP, or database TCP listeners with a generic TLS-terminating listener can break protocol negotiation.

Review Kubernetes and Helm values

Chart 3.0.0 requires Kubernetes 1.33 or later. Review saved values against the new chart instead of relying on reused values alone.

• The proxy Service defaults to private ClusterIP access, with plaintext web traffic on port 8080. Put a TLS terminator in front of it. A LoadBalancer or NodePort Service requires proxyService.acknowledgePlaintextWeb: true after you protect the web endpoint with external TLS.
• External PostgreSQL defaults to datastore.sslmode: verify-full. Verify the database hostname and CA chain. For a private CA, mount the CA file into every Bridge role and set datastore.sslrootcert to that path. Explicit environment overrides still apply. The bundled evaluation database continues to use plaintext locally.
• An existing Secret must contain BRIDGE_DATASTORE_PASSWORD, BRIDGE_CLUSTER_TOKEN, BRIDGE_ENCRYPTION_KEY_B64, and BRIDGE_HOST_KEY_SEED. Keep the existing encryption key and host-key seed.
• Preserve the current recordings claim. Multi-node clusters need shared ReadWriteMany storage, writable by UID 102 and GID 103. The orchestrator also needs recordings access for historical import.
• Advanced values under config.extraConfig now override generated configuration recursively. Inspect the rendered result for conflicting old overrides.
• Review the default session-worker ceiling of 64 and the resource allocation for the separate export worker. Set export.enabled: false if you do not need optional GIF or video conversion.

Set the release name and namespace to your existing installation. Render the chart with your reviewed values before the maintenance window:

export BRIDGE_RELEASE=bridge
export BRIDGE_NAMESPACE=bridge
umask 077
helm template "$BRIDGE_RELEASE" oci://registry-1.docker.io/britive/bridge-chart \
	--namespace "$BRIDGE_NAMESPACE" \
	--version 3.0.0 \
	--set image.tag=v3.0.0 \
	-f values-v3.yaml > bridge-v3-rendered.yaml

Treat the rendered file as sensitive if it contains Secrets. Check listener ports, health probes, certificate mounts, resource limits, and volume references before applying it.

Review AWS ECS and custom deployments

Prepare a change set against the template your stack actually uses. Older templates can differ in resource names, networking, and parameter names. Do not replace an existing stack’s template wholesale or accept unintended replacement of the database, recordings filesystem, access point, or load balancer.

Verify that all task definitions retain their datastore and secret settings, that orchestrators can read the recordings volume, and that worker probes use port 9091. Include the private proxy control connection on port 9443.

If GIF or video exports are required, provision a separate task or service using the v3 image with BRIDGE_ROLE=export. Give it the shared recordings mount, writable temporary storage, and explicit CPU and memory limits. The AWS template does not provision this worker automatically. Browser playback does not require optional media conversion.

Review telemetry collection

A broker token enables platform telemetry unless deployment configuration disables it. Telemetry sends session start and end events, plus cluster state at five-minute intervals and on state changes. It includes the current active-session count and per-protocol totals.

Set server.telemetry.review_base_url to Bridge’s public HTTPS origin, without a path. Session-end events include a review link that still requires Bridge login and an authorized reviewer checkout. Delivery also requires the corresponding telemetry ingestion support on your Britive tenant.

To opt out before the first v3 start, set:

server:
  telemetry:
    disabled: true

Keep disabled: false to collect and deliver telemetry. Collection is controlled by deployment configuration. Disabling it stops collection and delivery and deletes pending telemetry; re-enabling starts with new events. Local session audit and recordings remain in Bridge, and failed platform delivery does not block sessions.

For Helm, place the same application settings under config.extraConfig.server.telemetry in your values.

Perform the upgrade

docker compose stop bridge

helm upgrade "$BRIDGE_RELEASE" oci://registry-1.docker.io/britive/bridge-chart \
	--namespace "$BRIDGE_NAMESPACE" \
	--version 3.0.0 \
	--set image.tag=v3.0.0 \
	-f values-v3.yaml \
	--wait --timeout 10m

docker compose pull bridge
docker compose up -d bridge

Verify

Use your normal clients and at least one browser session. Confirm:

• Checkout, connection, checkin, and expiration work for every deployed protocol and authentication mode. Checked-in access ends, including established HTTP proxy tunnels.
• Trusted target certificates and SSH pins succeed. Incorrect pins, unrelated certificates, and plaintext-only database targets are refused.
• SSH typing, pastes, and activity remain available in recording review. Authorized live viewing and session controls work.
• Database activity is recorded for the operations your applications use, including prepared statements and bulk operations where applicable.
• Historical recordings still play, new recordings finalize, and Activity Search finds the expected actions.
• Browser logout revokes the login across replicas. Reviewers need their own authorized checkout after signing in again.
• Workers become ready, receive traffic, drain, and retire. PostgreSQL and recording storage remain writable.
• Optional media exports complete if you enabled an export worker. Telemetry reports successful delivery if your tenant supports it and collection is enabled.

Compare checkout, checkin, connection startup, and interactive latency with your baseline. Resume normal grants only after these checks pass.

Command filtering and sensitive-data redaction remain best effort. Use target-system permissions to enforce access. SSH input capture can retain typed credentials, so restrict recording access and review retention settings.

If an external system reads raw query-event files, update it to support correlated query start and end records alongside existing query events.

Troubleshoot

Roll back

Keep access grants paused. Stop all v3 Bridge roles before restoring the previous deployment and a matching pre-upgrade database backup. Restore the matching recordings snapshot when needed. Retain any newer recordings and audit data before a restore.

Changing the image or running helm rollback alone does not reverse database migrations or restore compatible authentication state.

If real user activity occurred on v3, restoring the old backup can lose its audit trail and revive stale checkout state. Preserve the newer database and recordings, reconcile grants, and plan a data-preserving recovery before reopening access.