Skip to content
Integrations
Infrastructure
Access Broker Deployment
Deploy on EKS

Deploy on EKS

Overview

Deploy the Access Broker on an existing EKS cluster with the britive-broker Helm chart. You build the broker image once from the onboarding repository, push it to Amazon ECR, 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 ECR
  • 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 AWS CLI configured for the cluster; Docker with buildx
  • Outbound HTTPS (443) from the pods to <tenant>.britive-app.com, through a NAT gateway or egress gateway
  • Node role (or pod identity) allowed to pull from ECR — managed node groups have AmazonEC2ContainerRegistryReadOnly by default

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

The script creates the ECR repository if it does not exist, builds for both architectures and pushes the tag 3.0.2-r1.

cd image
REGISTRY=<account>.dkr.ecr.<region>.amazonaws.com \
WITH_AWS_CLI=true WITH_KUBECTL=true \
./build-and-push.sh
cd ..

WITH_KUBECTL=true is needed for Kubernetes checkouts; WITH_AWS_CLI=true for scripts that read Secrets Manager or call aws eks update-kubeconfig. 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 create this Secret from AWS Secrets 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: <account>.dkr.ecr.<region>.amazonaws.com/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 AWS

Give the pod an IAM role with IRSA and annotate the service account. Scope the role to what the scripts do, for example secretsmanager:GetSecretValue on one secret prefix.

kubernetes/values.yaml
serviceAccount:
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::<account>:role/britive-broker

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
ImagePullBackOffNode role cannot pull from ECRAttach AmazonEC2ContainerRegistryReadOnly to the node group role
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; 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 ECS FargateDeploy on AKS