Every new EC2 launched in your ECS cluster — including spot replacements — installs the sensor on first boot and begins forwarding traffic to UAP automatically. No manual install per host, and no image rebuild when credentials rotate.
The sensor and bridge run as a single container. You do not deploy the bridge separately — it is bundled with the sensor, authenticates to UAP automatically, and forwards captured HTTP metadata.
Choose Your Path
| Path | How the sensor image is delivered | When to use |
|---|---|---|
| Path A — Registry | You push the image to ECR or a private registry (JFrog, Harbor, etc.). Each EC2 pulls it from your registry on first boot. | Your policy requires container images to be sourced from an approved internal registry |
| Path B — Bundle-baked | The image is baked into the AMI from the offline bundle. No registry access needed. | Air-gapped environments or no registry requirement |
Note on the bundle: Both paths require
ami-bake.tar.gz— it contains the sensor scripts, binaries, and systemd service used at AMI build time. For Path A, the image tar inside the bundle is discarded during the build; the image comes from your registry instead. For Path B, the image tar is baked directly into the AMI.
Path A — Registry (ECR or Private Registry)
Before You Start (Path A)
| What you need | Where to find it |
|---|---|
| UAP subdomain | e.g. your-tenant.cequence.ai — from your Cequence account team |
client_id and client_secret | UAP portal → Settings → Clients |
ami-bake.tar.gz | Provided by Cequence |
| AWS region and account ID | Region your ECS cluster runs in; account ID from the console top-right menu |
| S3 bucket | Any existing bucket to stage build files |
| Base AMI ID | Your current ECS-optimized AMI — Launch Template → Details → AMI ID |
| Registry details (ECR) | Your AWS account ID and region — no separate credentials needed |
| Registry details (JFrog / private) | Registry domain (e.g. yourco.jfrog.io), username, and password/API key with read access |
A-1 — Push the Sensor Image to Your Registry
Pull the image from Cequence and push it to your registry. This is what each EC2 will pull at first boot.
ECR:
# Create the repo (skip if it already exists)
aws ecr create-repository --repository-name cequence/sensor --region YOUR-REGION
# Authenticate, pull, retag, push
aws ecr get-login-password --region YOUR-REGION \
| docker login --username AWS --password-stdin \
YOUR-ACCOUNT-ID.dkr.ecr.YOUR-REGION.amazonaws.com
docker pull registry.gitlab.com/cequence/releases/dataplane/sensor:5.1.1
docker tag registry.gitlab.com/cequence/releases/dataplane/sensor:5.1.1 \
YOUR-ACCOUNT-ID.dkr.ecr.YOUR-REGION.amazonaws.com/cequence/sensor:5.1.1
docker push YOUR-ACCOUNT-ID.dkr.ecr.YOUR-REGION.amazonaws.com/cequence/sensor:5.1.1Private registry (JFrog, Harbor, Nexus, GitLab, etc.):
docker login YOUR-REGISTRY-DOMAIN -u YOUR-USER -p YOUR-PASSWORD-OR-TOKEN docker pull registry.gitlab.com/cequence/releases/dataplane/sensor:5.1.1 docker tag registry.gitlab.com/cequence/releases/dataplane/sensor:5.1.1 \ YOUR-REGISTRY-DOMAIN/cequence/sensor:5.1.1 docker push YOUR-REGISTRY-DOMAIN/cequence/sensor:5.1.1
A-2 — One-Time AWS Account Setup
Store UAP credentials in Parameter Store:
aws ssm put-parameter --name /cequence/uap-subdomain --type String \ --value 'your-tenant.cequence.ai' aws ssm put-parameter --name /cequence/client-id --type String \ --value 'paste-client-id' aws ssm put-parameter --name /cequence/client-secret --type SecureString \ --value 'paste-client-secret'
For private registry only — also store registry login credentials:
aws ssm put-parameter --name /cequence/registry-user --type String \ --value 'YOUR-USER' aws ssm put-parameter --name /cequence/registry-pass --type SecureString \ --value 'YOUR-PASSWORD-OR-TOKEN'
Attach IAM policy to your ECS EC2 instance role:
AWS Console: IAM → Roles → your ECS instance role → Add permissions → Create inline policy → JSON
{
"Version": "2012-10-17",
"Statement": [
{ "Sid": "ReadCequenceParams", "Effect": "Allow",
"Action": ["ssm:GetParameter", "ssm:GetParameters"],
"Resource": "arn:aws:ssm:*:*:parameter/cequence/*" },
{ "Sid": "DecryptCequenceSecret", "Effect": "Allow",
"Action": "kms:Decrypt", "Resource": "*",
"Condition": {"StringEquals": {"kms:ViaService": "ssm.YOUR-REGION.amazonaws.com"}} }
]
}Also attach the AWS managed policy AmazonSSMManagedInstanceCore to the same role (allows SSM Session Manager for troubleshooting).
ECR only — add ECR pull permission to the same role:
{ "Sid": "EcrAuth", "Effect": "Allow",
"Action": "ecr:GetAuthorizationToken", "Resource": "*" },
{ "Sid": "EcrPull", "Effect": "Allow",
"Action": ["ecr:BatchGetImage","ecr:GetDownloadUrlForLayer","ecr:BatchCheckLayerAvailability"],
"Resource": "arn:aws:ecr:YOUR-REGION:YOUR-ACCOUNT-ID:repository/cequence/sensor" }If your ECS tasks already pull from ECR, this permission is likely already present.
A-3 — Build the AMI
Upload build files to S3:
Why does Path A still need the bundle? The bundle contains the sensor binary, startup scripts, and config templates that need to be present on every EC2. The Image Builder component downloads the bundle, extracts these scripts, then deletes the image tar — the sensor container image comes from your registry instead. Think of it as: bundle provides the scripts, registry provides the image.
tar -xzf ami-bake.tar.gz # Bundle — provides sensor scripts and binaries (image tar inside will be discarded by the build step) aws s3 cp ami-bake/cequence-sensor-bundle-rhel-5.1.1.tar.gz \ s3://YOUR-BUCKET/cequence-sensor/cequence-sensor-bundle-rhel-5.1.1.tar.gz # Registry-specific firstboot scripts aws s3 cp ami-bake/imagebuilder-registry/registry-firstboot.sh \ s3://YOUR-BUCKET/cequence-sensor/registry/registry-firstboot.sh aws s3 cp ami-bake/imagebuilder-registry/setup-registry.sh \ s3://YOUR-BUCKET/cequence-sensor/registry/setup-registry.sh aws s3 cp ami-bake/imagebuilder-registry/cequence-firstboot.service \ s3://YOUR-BUCKET/cequence-sensor/registry/cequence-firstboot.service
Open the component YAML (ami-bake/imagebuilder-registry/cequence-sensor-registry-component.yaml), replace {{S3_BUCKET}} with your bucket name, then register it:
aws imagebuilder create-component \ --name CequenceSensorRegistry --semantic-version 1.0.0 --platform Linux \ --data file://ami-bake/imagebuilder-registry/cequence-sensor-registry-component.yaml \ --region YOUR-REGION
Add to your existing Image Builder pipeline (recommended):
- EC2 Image Builder → Image recipes → your ECS recipe → Create new version
- Build components → Add → select
CequenceSensorRegistry→ keep existing components → Create recipe version - EC2 Image Builder → Image pipelines → your pipeline → Actions → Run pipeline
- When done (~10–15 min), note the new AMI ID from Output resources
No existing pipeline? Use the helper script instead:
export AWS_REGION=YOUR-REGION export AWS_ACCOUNT_ID=YOUR-ACCOUNT-ID export S3_BUCKET=YOUR-BUCKET export BASE_AMI_ID=ami-xxxxxxxx # your current ECS Launch Template AMI bash ami-bake/imagebuilder-registry/setup.sh
A-4 — Launch a Test EC2 and Verify
Before updating the whole fleet, launch a single EC2 from the new AMI to confirm the sensor installs and connects correctly.
Launch from AWS Console: EC2 → Launch instances → AMI = new AMI ID from Step A-3 → same instance type and security groups as your ECS cluster → paste this user-data:
For ECR:
#!/bin/bash echo "ECS_CLUSTER=YOUR_CLUSTER_NAME" >> /etc/ecs/ecs.config cat > /etc/default/cequence-firstboot <<'EOF' REGISTRY_TYPE=ecr REGISTRY_IMAGE=YOUR-ACCOUNT-ID.dkr.ecr.YOUR-REGION.amazonaws.com/cequence/sensor:5.1.1 EOF
For private registry:
#!/bin/bash echo "ECS_CLUSTER=YOUR_CLUSTER_NAME" >> /etc/ecs/ecs.config cat > /etc/default/cequence-firstboot <<'EOF' REGISTRY_TYPE=private REGISTRY_IMAGE=YOUR-REGISTRY-DOMAIN/cequence/sensor:5.1.1 REGISTRY_DOMAIN=YOUR-REGISTRY-DOMAIN REGISTRY_USER_PARAM=/cequence/registry-user REGISTRY_PASS_PARAM=/cequence/registry-pass EOF
Required:
REGISTRY_IMAGEmust be set. If missing, first boot stops with an error and the sensor will not install.
Wait ~3 minutes for first boot to complete, then connect via SSM Session Manager (AWS Console → Systems Manager → Session Manager → Start session → select your instance) and run:
# 1. Firstboot completed sudo systemctl status cequence-firstboot.service # Expected: active (exited) # 2. Sensor running sudo docker ps | grep sensor # Expected: "sensor" container Up # 3. Forwarding to UAP sudo docker exec sensor tail /opt/cequence/sensor/log/connector.log # Look for: connected: true written: N errors: 0
Once all 3 checks pass, proceed to update the fleet.
A-5 — Update the Fleet (Launch Template + Instance Refresh)
- EC2 → Launch Templates → your ECS template → Actions → Modify template (Create new version) → set Image ID to the new AMI → Create template version
- Set as default: Actions → Set default version
Confirm your ASG uses
$Default— check under Auto Scaling Groups → Details → Launch template. If it shows a pinned version number, update it:aws autoscaling update-auto-scaling-group \ --auto-scaling-group-name YOUR-ASG-NAME \ --launch-template "LaunchTemplateId=YOUR-LT-ID,Version=\$Default"
- Auto Scaling Groups → Instance refresh → Start instance refresh
Path B — Bundle-baked (Offline)
Before You Start (Path B)
| What you need | Where to find it |
|---|---|
| UAP subdomain | e.g. your-tenant.cequence.ai — from your Cequence account team |
client_id and client_secret | UAP portal → Settings → Clients |
ami-bake.tar.gz | Provided by Cequence — sensor image + scripts bundled together |
| AWS region and account ID | Region your ECS cluster runs in; account ID from the console top-right menu |
| S3 bucket | Any existing bucket to stage build files |
| Base AMI ID | Your current ECS-optimized AMI — Launch Template → Details → AMI ID |
B-1 — One-Time AWS Account Setup
Store UAP credentials in Parameter Store:
aws ssm put-parameter --name /cequence/uap-subdomain --type String \ --value 'your-tenant.cequence.ai' aws ssm put-parameter --name /cequence/client-id --type String \ --value 'paste-client-id' aws ssm put-parameter --name /cequence/client-secret --type SecureString \ --value 'paste-client-secret'
Attach IAM policy to your ECS EC2 instance role:
AWS Console: IAM → Roles → your ECS instance role → Add permissions → Create inline policy → JSON
{
"Version": "2012-10-17",
"Statement": [
{ "Sid": "ReadCequenceParams", "Effect": "Allow",
"Action": ["ssm:GetParameter", "ssm:GetParameters"],
"Resource": "arn:aws:ssm:*:*:parameter/cequence/*" },
{ "Sid": "DecryptCequenceSecret", "Effect": "Allow",
"Action": "kms:Decrypt", "Resource": "*",
"Condition": {"StringEquals": {"kms:ViaService": "ssm.YOUR-REGION.amazonaws.com"}} }
]
}Also attach the AWS managed policy AmazonSSMManagedInstanceCore to the same role.
B-2 — Build the AMI
Upload build files to S3:
tar -xzf ami-bake.tar.gz aws s3 cp ami-bake/cequence-sensor-bundle-rhel-5.1.1.tar.gz \ s3://YOUR-BUCKET/cequence-sensor/cequence-sensor-bundle-rhel-5.1.1.tar.gz aws s3 cp ami-bake/cequence-firstboot.sh \ s3://YOUR-BUCKET/cequence-sensor/cequence-firstboot.sh aws s3 cp ami-bake/cequence-firstboot.service \ s3://YOUR-BUCKET/cequence-sensor/cequence-firstboot.service
Open the component YAML (ami-bake/imagebuilder/cequence-sensor-component.yaml), replace {{S3_BUCKET}} with your bucket name, then register it:
aws imagebuilder create-component \ --name CequenceSensorBake --semantic-version 1.0.0 --platform Linux \ --data file://ami-bake/imagebuilder/cequence-sensor-component.yaml \ --region YOUR-REGION
Add to your existing Image Builder pipeline (recommended):
- EC2 Image Builder → Image recipes → your ECS recipe → Create new version
- Build components → Add → select
CequenceSensorBake→ keep existing components → Create recipe version - EC2 Image Builder → Image pipelines → your pipeline → Actions → Run pipeline
- When done (~10–15 min), note the new AMI ID from Output resources
No existing pipeline? Use the helper script instead:
export AWS_REGION=YOUR-REGION export AWS_ACCOUNT_ID=YOUR-ACCOUNT-ID export S3_BUCKET=YOUR-BUCKET export BASE_AMI_ID=ami-xxxxxxxx # your current ECS Launch Template AMI bash ami-bake/imagebuilder/setup.sh
B-3 — Launch a Test EC2 and Verify
Before updating the whole fleet, launch a single EC2 from the new AMI to confirm the sensor installs and connects correctly.
Launch from AWS Console: EC2 → Launch instances → AMI = new AMI ID from Step B-2 → same instance type and security groups as your ECS cluster → paste this user-data:
#!/bin/bash echo "ECS_CLUSTER=YOUR_CLUSTER_NAME" >> /etc/ecs/ecs.config # Optional — only if your Parameter Store path is not /cequence: # cat > /etc/default/cequence-firstboot <<'EOF' # SSM_PREFIX=/your/prefix # EOF
Wait ~3 minutes for first boot to complete, then connect via SSM Session Manager (AWS Console → Systems Manager → Session Manager → Start session → select your instance) and run:
# 1. Firstboot completed sudo systemctl status cequence-firstboot.service # Expected: active (exited) # 2. Sensor running sudo docker ps | grep sensor # Expected: "sensor" container Up # 3. Forwarding to UAP sudo docker exec sensor tail /opt/cequence/sensor/log/connector.log # Look for: connected: true written: N errors: 0
Once all 3 checks pass, proceed to update the fleet.
B-4 — Update the Fleet (Launch Template + Instance Refresh)
- EC2 → Launch Templates → your ECS template → Actions → Modify template (Create new version) → set Image ID to the new AMI → Create template version
- Set as default: Actions → Set default version
Confirm your ASG uses
$Default— check under Auto Scaling Groups → Details → Launch template. If it shows a pinned version number, update it:aws autoscaling update-auto-scaling-group \ --auto-scaling-group-name YOUR-ASG-NAME \ --launch-template "LaunchTemplateId=YOUR-LT-ID,Version=\$Default"
- Auto Scaling Groups → Instance refresh → Start instance refresh