Skip to main content

AWS Cloud Agent Update

On AWS, the Fractal Cloud Agent runs in an ECS cluster in the management account. Updating the agent involves copying the new image to your ECR registry, creating a new task definition revision, and updating the ECS service.

For common prerequisites (regctl installation, Fractal registry authentication), see the main guide.

Step 1 — Find the current task definition​

Locate the ECS cluster and task definition used by the Fractal Cloud Agent. You can do this through the AWS Console or CLI:

# List ECS clusters
aws ecs list-clusters --profile <OPTIONAL_PROFILE>

# List task definitions (look for one containing "fractal")
aws ecs list-task-definitions --profile <OPTIONAL_PROFILE> | grep fractal

Note the current image location from the task definition. It will look like:

<ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/fractalcloud/fractal.cloudagent.aws.container:v<CURRENT_VERSION>

Step 2 — Authenticate with your ECR registry​

Log in to your AWS account and authenticate Docker with ECR:

# If using SSO
aws sso login --profile <OPTIONAL_PROFILE>

# Authenticate Docker with ECR
aws ecr get-login-password \
  --region <REGION> \
  --profile <OPTIONAL_PROFILE> \
  | docker login --username AWS --password-stdin <ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com

Also configure regctl to access your ECR:

ECR_PASSWORD=$(aws ecr get-login-password --region <REGION> --profile <OPTIONAL_PROFILE>)
regctl registry login <ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com -u AWS -p "$ECR_PASSWORD"

Step 3 — Copy the new image to ECR​

Use regctl to copy the new agent image directly from the Fractal registry to your ECR:

regctl image copy \
  yanchware/fractal.cloudagent.aws.container:<NEW_VERSION> \
  <ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/fractalcloud/fractal.cloudagent.aws.container:<NEW_VERSION>
info

regctl image copy transfers the image between registries server-side without pulling it locally, making it significantly faster than docker pull + docker tag + docker push.

Step 4 — Create a new task definition revision​

Register a new revision of the task definition with the updated image tag:

AWS Console:

  1. Go to ECS > Task Definitions.
  2. Select the Fractal Cloud Agent task definition.
  3. Click Create new revision.
  4. Update the container image to the new version tag.
  5. Click Create.

AWS CLI:

# Get the current task definition JSON
aws ecs describe-task-definition \
  --task-definition <TASK_DEFINITION_NAME> \
  --profile <OPTIONAL_PROFILE> \
  --query 'taskDefinition' > task-def.json

# Edit task-def.json: update the image tag to the new version
# Remove fields that cannot be included in a new registration:
# taskDefinitionArn, revision, status, requiresAttributes, compatibilities, registeredAt, registeredBy

# Register the new revision
aws ecs register-task-definition \
  --cli-input-json file://task-def.json \
  --profile <OPTIONAL_PROFILE>

Step 5 — Update the ECS service​

Update the service to use the new task definition revision:

aws ecs update-service \
  --cluster <CLUSTER_NAME> \
  --service <SERVICE_NAME> \
  --task-definition <TASK_DEFINITION_NAME>:<NEW_REVISION> \
  --profile <OPTIONAL_PROFILE>

AWS Console:

  1. Go to ECS > Clusters > (your cluster) > Services.
  2. Select the Fractal Cloud Agent service.
  3. Click Update.
  4. Select the new task definition revision.
  5. Click Update.

Step 6 — Verify the update​

Monitor the deployment to ensure the new task is running:

aws ecs describe-services \
  --cluster <CLUSTER_NAME> \
  --services <SERVICE_NAME> \
  --profile <OPTIONAL_PROFILE> \
  --query 'services[0].deployments'

Wait until the primary deployment shows runningCount matching desiredCount and the old deployment has been drained.