Skip to content
Integrations
Infrastructure
Access Broker Deployment
Deploy on AKS

Deploy on AKS

Overview

Deploy the Access Broker on an existing AKS cluster with the britive-broker Helm chart. You build the broker image once from the onboarding repository, push it to Azure Container Registry (ACR), 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 ACR
  • 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 Azure CLI (az) configured for the cluster; Docker with buildx

  • An ACR registry attached to the cluster, so nodes pull without an image pull secret:

    az aks update -n <cluster> -g <resource-group> --attach-acr <registry>

  • Outbound HTTPS (443) from the pods to <tenant>.britive-app.com

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/

Build and push the image 

az acr login --name <registry>
cd image
REGISTRY=<registry>.azurecr.io 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 the Secrets Store CSI driver (Azure Key Vault provider) or External Secrets Operator create this Secret from Key Vault 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: <registry>.azurecr.io/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 Azure

Give the pod a managed identity with Microsoft Entra Workload ID: annotate the service account with the identity’s client ID and label the pods. Scope the identity’s role assignments to what the scripts do, for example Key Vault Secrets User on one vault.

kubernetes/values.yaml
serviceAccount:
  annotations:
    azure.workload.identity/client-id: <client-id>
podLabels:
  azure.workload.identity/use: "true"

Operations

TaskHow
Rotate the tokenUpdate 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 brokerDownload 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 typesPut a broker-config.yml in the chart’s config: value; the chart mounts it and restarts the pods when it changes
Uninstallhelm -n britive uninstall britive-broker, then deactivate the token

Troubleshoot

SymptomCauseFix
ImagePullBackOffCluster not attached to the registryaz aks update -n <cluster> -g <resource-group> --attach-acr <registry>
Helm: image.repository is required (or tenantSubdomain, token)Required value missing from values.yamlSet it; the chart refuses to render without the three
Broker bootstrap failed … 401 / 403Wrong or deactivated tokenCreate a new token, update the Secret, restart the deployment
Broker bootstrap failed … i/o timeoutNo egress on 443Allow outbound HTTPS to *.britive-app.com in the cluster’s NSG or Azure Firewall; 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 listedSet rbac.create: true and add the namespace to rbac.namespaces

Next Steps

Last updated on
Deploy on EKSDeploy on GKE