Deploy on ECS Fargate

Overview

Run the Access Broker as a Fargate task — no Kubernetes cluster and no hosts to manage. Two CloudFormation stacks do the work: one creates the ECR repository, the other the cluster, task definition, service, egress-only security group, IAM roles, log group and the Secrets Manager secret that holds the pool token. There is no deployment script to read through; what the stack creates is what the template says. This is the recommended option for AWS environments without an existing Kubernetes cluster.

What you’ll accomplish:

Build the Broker 3.x image and push it to ECR
Deploy the broker as an auto-restarting Fargate task with the token in Secrets Manager
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.
AWS CLI v2 authenticated to the target account; Docker with buildx
A VPC with subnets that reach the internet on 443: private subnets behind a NAT gateway (recommended), or public subnets

Broker 2.x (the Java JAR) is deprecated and not supported by these templates. Download the 3.x tarball. Never commit params.json — it holds the pool token; the repository ignores it.

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 ECR repository

aws cloudformation deploy \
  --stack-name britive-broker-ecr \
  --template-file aws-ecs-fargate/ecr-repo.yaml

Build and push the image

cd image
REGISTRY=$(aws sts get-caller-identity --query Account --output text).dkr.ecr.$(aws configure get region).amazonaws.com \
WITH_AWS_CLI=true \
./build-and-push.sh
cd ..
# prints ImageUri=<account>.dkr.ecr.<region>.amazonaws.com/britive-broker:3.0.2-r1

Add WITH_KUBECTL=true for EKS checkouts, WITH_PYWINRM=true for Windows targets or WITH_DB_CLIENTS=true for databases.

Fill in the parameters

cp aws-ecs-fargate/params.example.json aws-ecs-fargate/params.json

Set at least these values; the others have working defaults:

aws-ecs-fargate/params.json

[
  { "ParameterKey": "VpcId",                 "ParameterValue": "vpc-xxxxxxxx" },
  { "ParameterKey": "SubnetIds",             "ParameterValue": "subnet-aaaa,subnet-bbbb" },
  { "ParameterKey": "AssignPublicIp",        "ParameterValue": "DISABLED" },
  { "ParameterKey": "ImageUri",              "ParameterValue": "<account>.dkr.ecr.<region>.amazonaws.com/britive-broker:3.0.2-r1" },
  { "ParameterKey": "CpuArchitecture",       "ParameterValue": "ARM64" },
  { "ParameterKey": "BrokerTenantSubdomain", "ParameterValue": "mycompany" },
  { "ParameterKey": "BrokerAuthToken",       "ParameterValue": "<broker-pool-token>" }
]

AssignPublicIp is ENABLED only for public subnets without a NAT gateway. CpuArchitecture must match the image; the script builds both.

Deploy the service

aws cloudformation deploy \
  --stack-name britive-broker \
  --template-file aws-ecs-fargate/ecs-fargate.yaml \
  --parameter-overrides file://aws-ecs-fargate/params.json \
  --capabilities CAPABILITY_NAMED_IAM

The token goes into Secrets Manager and is injected at task start; it never appears on the task definition. A new image that fails its health check is rolled back automatically.

Verify

Check the service is running

aws ecs describe-services --cluster britive-broker-cluster --services britive-broker-service \
  --query 'services[0].{running:runningCount,desired:desiredCount,deployments:deployments[*].rolloutState}'

Tail the logs

aws logs tail /ecs/britive-broker --since 10m --follow

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, named after the task’s hostname (the container ID). To name brokers predictably, bake a BRITIVE_BROKER_NAME_GENERATOR script into the image that prints a name.

Day-2 Operations

Rotate the pool token

Create a new token on the pool, update only that parameter, then force a new deployment so the task picks the secret up:

aws cloudformation deploy \
  --stack-name britive-broker \
  --template-file aws-ecs-fargate/ecs-fargate.yaml \
  --parameter-overrides BrokerAuthToken=<new-token> \
  --capabilities CAPABILITY_NAMED_IAM

aws ecs update-service --cluster britive-broker-cluster --service britive-broker-service --force-new-deployment

aws cloudformation deploy keeps every parameter you do not pass. Delete the old token in the console once the new task shows active.

Upgrade the broker

Download the new tarball, rebuild with BROKER_VERSION=3.x.y ./build-and-push.sh, then deploy with --parameter-overrides ImageUri=<new-image-uri>. During the rollout both tasks are registered with the pool for a minute or two; that is expected.

Scripts that call AWS

Set EnableAwsBrokerScripts=true to grant the task role EC2/RDS discovery, SSM sessions and Secrets Manager read/write scoped to secrets named <StackNamePrefix>/*. Store what your scripts need under that prefix:

aws secretsmanager create-secret --name britive-broker/targets/db-master \
  --secret-string '{"username":"admin","password":"…"}'

For EKS checkouts, build the image with WITH_KUBECTL=true WITH_AWS_CLI=true, pass the cluster ARN in EksClusterArns, and create an EKS access entry for the task role (TaskRoleArn output).

Troubleshoot

Symptom	Cause	Fix
Task stops immediately, no application log	Image architecture ≠ `CpuArchitecture`	Rebuild for the right platform or change the parameter
`Broker bootstrap failed … i/o timeout`	No route to the internet	Private subnets need a NAT gateway; or `AssignPublicIp=ENABLED` on public subnets
`Broker bootstrap failed … 401` / `403`	Wrong or deactivated token	Create a new token, update `BrokerAuthToken`, force a new deployment
`ResourceInitializationError: unable to pull secrets`	Execution role cannot read the secret	The stack grants it; check Secrets Manager resource policies and SCPs in the account
Script fails with `AccessDenied` calling AWS	`EnableAwsBrokerScripts` is false, or the secret is outside the prefix	Enable it; name secrets `<StackNamePrefix>/…`
Broker shows in the console under a random name	Hostname is the container ID	Bake a `BRITIVE_BROKER_NAME_GENERATOR` script into the image

Clean Up

aws cloudformation delete-stack --stack-name britive-broker
aws cloudformation wait stack-delete-complete --stack-name britive-broker
aws cloudformation delete-stack --stack-name britive-broker-ecr   # after deleting the images in the repository

The pool token secret is deleted with the stack (30-day recovery window); deactivate the token in the console as well.

Next Steps

Onboard a broker-based integration — Linux, Windows, databases, network devices
Source: britive/onboarding — access-broker/aws-ecs-fargate (templates, full parameter reference)

Last updated on October 8, 2026

Deploy on EKS