Deploy on GKE

Overview

Deploy the Access Broker on an existing GKE cluster with the britive-broker Helm chart. You build the broker image once from the onboarding repository, push it to Artifact Registry, and install the chart with your tenant subdomain and a broker pool token. The chart runs the broker as a non-root user on a read-only root filesystem and can grant it the RBAC needed for Kubernetes just-in-time checkouts in the same cluster.

What you’ll accomplish:

Build the Broker 3.x image and push it to Artifact Registry
Install the broker with Helm, with the token in a Kubernetes Secret
Confirm the broker is active in its pool

Before You Begin

A Britive tenant with administrator access
Tenant subdomain — mycompany for https://mycompany.britive-app.com
Broker pool token — System Administration → Brokers and Broker Pools → create or open a pool → Tokens
Broker tarball — System Administration → Brokers and Broker Pools → Download Brokers → Any other Linux → the tar.gz for amd64 and arm64. There is no public download URL.
helm 3.12+, kubectl and the gcloud CLI configured for the cluster; Docker with buildx
The node service account allowed to pull from Artifact Registry (roles/artifactregistry.reader; the default compute service account has it)
Outbound HTTPS (443) from the pods to <tenant>.britive-app.com — private clusters need Cloud NAT

Broker 2.x (the Java JAR) is deprecated and not supported by the chart. Download the 3.x tarball.

Deploy

Clone the onboarding repo

git clone https://github.com/britive/onboarding.git
cd onboarding/access-broker

Add the broker tarball

Place the downloaded files next to the Dockerfile. They are gitignored.

cp ~/Downloads/britive-broker-3.0.2-linux-amd64.tar.gz image/
cp ~/Downloads/britive-broker-3.0.2-linux-arm64.tar.gz image/

Create the Artifact Registry repository

gcloud artifacts repositories create britive --repository-format=docker --location=us
gcloud auth configure-docker us-docker.pkg.dev

Build and push the image

cd image
REGISTRY=us-docker.pkg.dev/<project>/britive WITH_KUBECTL=true ./build-and-push.sh
cd ..

The script builds for both architectures and pushes the tag 3.0.2-r1. WITH_KUBECTL=true is needed for Kubernetes checkouts; add WITH_PYWINRM=true or WITH_DB_CLIENTS=true for Windows or database targets.

Create the token Secret

kubectl create namespace britive
kubectl -n britive create secret generic britive-broker-token \
  --from-literal=BRITIVE_BROKER_AUTH_TOKEN=<broker-pool-token>

For production, let External Secrets Operator or the Secrets Store CSI driver (Secret Manager provider) create this Secret from Secret Manager instead; the chart only needs its name and key.

Set the chart values

cp kubernetes/values.example.yaml kubernetes/values.yaml

kubernetes/values.yaml

image:
  repository: us-docker.pkg.dev/<project>/britive/britive-broker
  tag: 3.0.2-r1

britive:
  tenantSubdomain: mycompany
  existingSecret:
    name: britive-broker-token
    key: BRITIVE_BROKER_AUTH_TOKEN

Install the chart

helm upgrade --install britive-broker kubernetes/charts/britive-broker \
  -n britive -f kubernetes/values.yaml

The chart refuses to render without image.repository, britive.tenantSubdomain and a token source.

Verify

Check the pod is running

kubectl -n britive get pods -l app.kubernetes.io/name=britive-broker
# Expected: STATUS = Running

Tail the logs

kubectl -n britive logs -l app.kubernetes.io/name=britive-broker -f

Expect Britive broker starting version=3.0.2 and, after the first few seconds, no Broker bootstrap failed lines.

Confirm registration

In the Britive console, go to System Administration → Brokers and Broker Pools → your pool → Brokers. The broker is listed as active under the pod name.

Kubernetes Checkouts in This Cluster

Checkout scripts that create a RoleBinding at checkout and delete it at check-in run with the pod’s service account. Let the chart create the RBAC, scoped to the namespaces that should be reachable:

kubernetes/values.yaml

rbac:
  create: true
  namespaces: [dev, staging]

The broker can only bind Roles that already exist in those namespaces and whose rules the chart’s ClusterRole covers — Kubernetes prevents a service account from granting more than it holds. Script examples are in access-broker-examples/k8s.

Scripts That Call Google Cloud

Bind the pod to a Google service account with Workload Identity and annotate the Kubernetes service account. Grant the Google service account only what the scripts do, for example roles/secretmanager.secretAccessor on specific secrets.

kubernetes/values.yaml

serviceAccount:
  annotations:
    iam.gke.io/gcp-service-account: britive-broker@<project>.iam.gserviceaccount.com

gcloud iam service-accounts add-iam-policy-binding britive-broker@<project>.iam.gserviceaccount.com \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:<project>.svc.id.goog[britive/britive-broker]"

Operations

Task	How
Rotate the token	Update the Secret, then `kubectl -n britive rollout restart deployment/britive-broker`. Delete the old token in the console once the new pod shows active
Upgrade the broker	Download the new tarball, `BROKER_VERSION=3.x.y ./build-and-push.sh`, then `helm upgrade … --set image.tag=3.x.y-r1`. The rolling update briefly runs two brokers in the pool; that is supported
Restrict resource types	Put a `broker-config.yml` in the chart’s `config:` value; the chart mounts it and restarts the pods when it changes
Uninstall	`helm -n britive uninstall britive-broker`, then deactivate the token

Troubleshoot

Symptom	Cause	Fix
`ImagePullBackOff`	Node service account cannot read the repository	Grant `roles/artifactregistry.reader` on the repository to the node service account
Helm: `image.repository is required` (or `tenantSubdomain`, token)	Required value missing from `values.yaml`	Set it; the chart refuses to render without the three
`Broker bootstrap failed … 401` / `403`	Wrong or deactivated token	Create a new token, update the Secret, restart the deployment
`Broker bootstrap failed … i/o timeout`	No egress on 443	Private cluster without Cloud NAT, or an egress firewall rule; set `extraEnv` with `HTTPS_PROXY` / `NO_PROXY` behind a proxy
Checkout script: `forbidden: user "system:serviceaccount:britive:britive-broker" cannot …`	RBAC not enabled or namespace not listed	Set `rbac.create: true` and add the namespace to `rbac.namespaces`

Next Steps

Onboard a broker-based integration
Source: britive/onboarding — access-broker/kubernetes (chart, values.example.yaml, EKS and AKS registry notes)

Last updated on October 8, 2026

Deploy on AKS Upgrade Broker 2.x to 3.x