Upgrade and Uninstall on ECS

The Odigos VM Agent is available as part of Odigos Pro. For access and licensing details, contact us.

Upgrade

An upgrade is a new image tag plus a new task definition revision. The agent’s configuration and identity live on the container instance at /etc/odigos-ecs-agent, so they survive the rollout.

Mirror the new image tag

Pull the new version and push it to your ECR repository, as in System Requirements. Use the architecture that matches your container instances.

Re-run the sed and register-task-definition steps from your install guide with the new TAG. This creates a new revision of the same family (odigos-ecs-agent).

grep -c '<' /tmp/agent-td.json   # want 0
aws ecs register-task-definition --cli-input-json file:///tmp/agent-td.json >/dev/null

Roll the service

aws ecs update-service --cluster "$CLUSTER" --service odigos-ecs-agent \
  --task-definition odigos-ecs-agent --force-new-deployment

ECS replaces the agent task on each instance. Instrumented workloads are not restarted — instrumentation is direct-attach and the agent re-attaches to the running tasks when it comes back up.

Upgrade the proxy too (Agent + Proxy mode)

Same pattern for odigos-ecs-proxy:

aws ecs update-service --cluster "$CLUSTER" --service odigos-ecs-proxy \
  --task-definition odigos-ecs-proxy --force-new-deployment

With a pinned proxy (host networking), the service must already have minimumHealthyPercent=0,maximumPercent=100 and --availability-zone-rebalancing DISABLED, or the rollout gets stuck: ECS tries to place the new task before stopping the old one, and both want port 4321 on the same instance. If the deployment is already stuck, apply the deployment configuration and stop the old task once to unblock it.

Upgrade the proxy and agents to the same version.

Changing an environment variable follows the exact same flow: new revision, then update-service --force-new-deployment. Remember that values already persisted in config.yaml on the instance take precedence over ODIGOS_DEFAULT_CONFIG.To move an existing Agent-only cluster onto the proxy without reinstalling, see Switch to Multi Node.

Uninstall

Removing Odigos does not touch your workloads: instrumentation is attached at runtime, so stopping the agent stops the telemetry — your tasks keep running untouched.

Delete the ECS services

aws ecs update-service --cluster "$CLUSTER" --service odigos-ecs-agent --desired-count 0
aws ecs delete-service --cluster "$CLUSTER" --service odigos-ecs-agent --force

# Agent + Proxy mode
aws ecs update-service --cluster "$CLUSTER" --service odigos-ecs-proxy --desired-count 0
aws ecs delete-service --cluster "$CLUSTER" --service odigos-ecs-proxy --force

Deregister the task definition revisions

for family in odigos-ecs-agent odigos-ecs-proxy; do
  for arn in $(aws ecs list-task-definitions --family-prefix "$family" --query 'taskDefinitionArns[]' --output text); do
    aws ecs deregister-task-definition --task-definition "$arn" >/dev/null
  done
done

Remove the leftover state on each container instance

The agent’s config directory and the synced instrumentation files are host directories and outlive the task. On each instance:

sudo rm -rf /etc/odigos-ecs-agent /var/odigos

/etc/odigos-ecs-agent holds the agent’s identity, license, and configuration. Removing it makes any future install start fresh — leave it in place if you plan to reinstall and want the configuration back.

Clean up the supporting AWS resources (optional)

aws logs delete-log-group --log-group-name /odigos/ecs-agent
aws logs delete-log-group --log-group-name /odigos/ecs-proxy

aws secretsmanager delete-secret --secret-id odigos-onprem-token --force-delete-without-recovery

aws iam delete-role-policy --role-name odigos-ecs-exec-role --policy-name odigos-extras
aws iam detach-role-policy --role-name odigos-ecs-exec-role \
  --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy
aws iam delete-role --role-name odigos-ecs-exec-role

aws iam delete-role-policy --role-name odigos-ecs-task-role --policy-name ssm-exec
aws iam delete-role-policy --role-name odigos-ecs-task-role --policy-name odigos-coverage 2>/dev/null || true
aws iam delete-role --role-name odigos-ecs-task-role

aws ecr delete-repository --repository-name odigos-ecs-agent --force
aws ecr delete-repository --repository-name odigos-ecs-proxy --force

Also delete the internal NLB, listener, and target group if you created them for the proxy.

Deleting and recreating the license secret gives it a new random ARN suffix. The install guides’ IAM policy uses a odigos-onprem-token-* wildcard so it keeps working — but any task definition still referencing the old ARN fails to start with ResourceNotFoundException ... can't find the specified secret.

Your ECS cluster and container instances are untouched by all of the above.

​Upgrade

​Uninstall

Upgrade

Uninstall