Use kubectl through Bridge

In v3.0.2 and later, an HTTP proxy checkout can supply the Kubernetes API bearer token on the user’s behalf. The user’s kubeconfig contains a separate Bridge password. Bridge replaces the request’s Authorization header before it reaches the API server.

When recording is enabled, API requests produce HAR records. Upgraded streams record their handshake, byte counts, and duration. They do not record terminal contents or provide terminal replay. For a recorded browser terminal, use Kubernetes Exec.

This walkthrough submits the checkout through the API. bsh currently accepts BSH_TARGET_BEARER_TOKEN, but its HTTP payload omits the exact host and port required by Bridge v3.0.2. Use bsh for HTTP capture without token injection.

Before you begin

Enable the HTTP proxy on a licensed deployment.
Configure checkout API access with colocated broker authority or a checkout token that allows user HTTP grants. The broker needs curl for the API requests below.
Expose its listener through a verified HTTPS endpoint reachable by the client.
Obtain a Kubernetes API bearer token with the required RBAC permissions and a lifetime that covers the checkout. The broker supplies this token to Bridge.
Obtain the Kubernetes API server’s CA certificate if Bridge does not already trust its issuer.
Distribute the public Bridge MITM CA certificate to the client. If the proxy’s HTTPS endpoint uses a private CA, include that public CA certificate in the client’s trust bundle too. Keep all CA private keys on the server.

The examples use api.k8s.example.com:6443 for Kubernetes and bridge.example.com:8443 for the proxy’s HTTPS endpoint. Replace both addresses with your deployment’s values.

Configure access

Allow the Kubernetes API port

Add 6443 to the proxy’s allowed CONNECT ports. Preserve any other ports your deployment needs:

bridge.yaml

http_proxy:
  enabled: true
  listen: "8443"
  connect_ports: ["443", "6443"]

Apply the configuration to the serving replicas. If your API uses port 443, the default CONNECT allowlist already includes it.

Create the HTTP checkout

Have the broker submit this payload with a unique transaction ID, a future expiration, and the real credentials:

kubectl-checkout.json

{
	"transaction_id": "txn-kubectl-001",
	"protocol": "http",
	"username": "alice@example.com",
	"native_auth": "bridge_credentials",
	"bridge_auth_password": "<separate-Bridge-password>",
	"target_host": "api.k8s.example.com",
	"target_port": 6443,
	"target_password": "<Kubernetes-API-bearer-token>",
	"target_ca_cert": "<Kubernetes-API-CA-in-PEM-format>",
	"capture_hosts": ["api.k8s.example.com"],
	"record_session": true,
	"expires_at": 2000000000
}

Use the raw bearer token without the Bearer prefix. Encode PEM newlines as \n in JSON. Omit target_ca_cert if Bridge already trusts the API certificate. Keep target_tls_skip_verify false. Bridge rejects bearer checkouts that disable certificate verification.

The colocated broker inherits BRIDGE_BROKER_API_URL and BRIDGE_BROKER_API_TOKEN_FILE. For an external broker, configure checkout API access and set these values for curl. The protected file contains the raw checkout token:

export BRIDGE_BROKER_API_URL=https://bridge.example.com
export BRIDGE_BROKER_API_TOKEN_FILE=/run/secrets/bridge-checkout-token

curl does not resolve bsh secret references. If the API uses a private CA, set CURL_CA_BUNDLE to the trusted CA file on the broker. Send the JSON payload:

printf 'X-Bridge-Broker-Token: %s\n' "$(cat "$BRIDGE_BROKER_API_TOKEN_FILE")" |
	curl -q --fail-with-body --silent --show-error \
		--header @- --header 'Content-Type: application/json' \
		--data-binary @kubectl-checkout.json \
		"${BRIDGE_BROKER_API_URL%/}/api/transactions"

A successful request returns 201 Created. The token header is read from standard input, so the token is absent from curl’s command-line arguments.

Create a client kubeconfig

Create a separate file so this connection does not replace your existing contexts:

bridge-kubeconfig.yaml

apiVersion: v1
kind: Config
clusters:
  - name: bridge-kubernetes
    cluster:
      server: https://api.k8s.example.com:6443
      proxy-url: https://alice%40example.com:<URL-encoded-Bridge-password>@bridge.example.com:8443
      certificate-authority: /absolute/path/to/bridge-client-ca-bundle.pem
users:
  - name: bridge-user
    user:
      token: bridge-proxy-placeholder
contexts:
  - name: bridge-kubernetes
    context:
      cluster: bridge-kubernetes
      user: bridge-user
      namespace: default
current-context: bridge-kubernetes

URL-encode the username and Bridge password separately in proxy-url. The placeholder token prevents kubectl from prompting for target credentials. It has no authority at Kubernetes. Bridge replaces it with the checkout’s bearer token. Do not put the Kubernetes bearer token in this file.

The CA bundle trusts the certificates presented by Bridge to the client. The checkout’s target_ca_cert separately verifies Bridge’s connection to Kubernetes. Bearer injection requires interception even when record_session is false, so clients still need the Bridge MITM CA.

Protect the kubeconfig because its proxy URL contains the Bridge password:

chmod 600 bridge-kubeconfig.yaml

Verify

Run a read request allowed by the token’s Kubernetes RBAC policy:

kubectl --kubeconfig=bridge-kubeconfig.yaml get pods

You should see the pods visible to the target token in the configured namespace. Kubernetes RBAC still controls operations. Bridge’s host scope does not grant additional Kubernetes permissions.

Watch and follow-log requests deliver updates as they arrive. The proxy supports WebSocket and SPDY upgrades for streaming operations such as exec and port-forward. These streams have the recording limits described above.

Check in the transaction when access is no longer needed:

printf 'X-Bridge-Broker-Token: %s\n' "$(cat "$BRIDGE_BROKER_API_TOKEN_FILE")" |
	curl -q --fail-with-body --silent --show-error \
		--header @- --request DELETE \
		"${BRIDGE_BROKER_API_URL%/}/api/transactions/txn-kubectl-001"

Subsequent requests fail. Active connections also close when the checkout expires, is deleted, or is replaced.

Troubleshoot

Symptom	Check
Proxy authentication fails	Match the kubeconfig username and password to the checkout’s Bridge credentials. Check the checkout’s expiration.
CONNECT is refused	Allow the API port in `http_proxy.connect_ports`. Match the API host and port exactly to the checkout.
Client reports an untrusted certificate	Trust the Bridge MITM CA and, if private, the CA for the proxy’s HTTPS endpoint.
Bridge cannot verify the API certificate	Supply the target CA in `target_ca_cert` and use a hostname in the API certificate.
Kubernetes returns `Forbidden`	Check the target token’s RBAC grants. HTTP method blocking does not replace Kubernetes authorization.
No terminal replay is available	HTTP upgraded streams retain metadata only. Use a browser Kubernetes Exec checkout when terminal replay is required.

Next steps

See the HTTP bearer-token reference for destination restrictions and the payload reference for optional method and redaction settings.

Last updated on November 6, 2026

HTTP Proxy