# Amazon ECS clusters for external instances Amazon ECS Anywhere provides support for registering an *external instance* such as an on-premises server or virtual machine (VM), to your Amazon ECS cluster. External instances are optimized for running applications that generate outbound traffic or process data. If your application requires inbound traffic, the lack of Elastic Load Balancing support makes running these workloads less efficient. Amazon ECS added a new `EXTERNAL` launch type that you can use to create services or run tasks on your external instances. ## Supported operating systems and system architectures The following is the list of supported operating systems. The `x86_64` and `ARM64` CPU architectures are supported. + Amazon Linux 2023 + Ubuntu 20, Ubuntu 22, Ubuntu 24 + RHEL 9 — You must ensure that Docker is installed before you run the [ECS Anywhere install script](https://github.com/aws/amazon-ecs-agent/blob/master/scripts/ecs-anywhere-install.sh). For more information, see [Install Docker Engine on RHEL](https://docs.docker.com/engine/install/rhel/) in the Docker documentation. Beginning August 7 2026, the following operating systems are no longer supported by Amazon ECS Anywhere: + Amazon Linux 2 + CentOS Stream 9 + RHEL 7, RHEL 8 + Fedora 32, Fedora 33, Fedora 40 + openSUSE Tumbleweed + Ubuntu 18 + Debian 9, Debian 10, Debian 11, Debian 12 + SUSE Enterprise Server 15 + Windows Server 2022, Windows Server 2019, Windows Server 2016, Windows Server 20H2 ## Considerations Before you start using external instances, be aware of the following considerations. + You can register an external instance to one cluster at a time. For instructions on how to register an external instance with a different cluster, see [Deregistering an Amazon ECS external instance](ecs-anywhere-deregistration.md). + Your external instances require an IAM role that allows them to communicate with AWS APIs. For more information, see [Amazon ECS Anywhere IAM role](iam-role-ecsanywhere.md). + Your external instances should not have a preconfigured instance credential chain defined locally as this will interfere with the registration script. + To send container logs to CloudWatch Logs, make sure that you create and specify a task execution IAM role in your task definition. + When an external instance is registered to a cluster, the `ecs.capability.external` attribute is associated with the instance. This attribute identifies the instance as an external instance. You can add custom attributes to your external instances to use as a task placement constraint. For more information, see [Custom attributes](task-placement-constraints.md#ecs-custom-attributes). + You can add resource tags to your external instance. For more information, see [Adding tags to External container instances for Amazon ECS](instance-details-tags-external.md). + ECS Exec is supported on external instances. For more information, see [Monitor Amazon ECS containers with ECS Exec](ecs-exec.md). + The following are additional considerations that are specific to networking with your external instances. For more information, see [Networking](#ecs-anywhere-networking). + Service load balancing isn't supported. + Service discovery isn't supported. + Tasks that run on external instances must use the `bridge`, `host`, or `none` network modes. The `awsvpc` network mode isn't supported. + There are Amazon ECS service domains in each AWS Region. These service domains must be allowed to send traffic to your external instances. + The SSM Agent installed on your external instance maintains IAM credentials that are rotated every 30 minutes using a hardware fingerprint. If your external instance loses connection to AWS, the SSM Agent automatically refreshes the credentials after the connection is re-established. For more information, see [Validating on-premises servers and virtual machines using a hardware fingerprint](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent-technical-details.html#fingerprint-validation) in the *AWS Systems Manager User Guide*. + You can run Linux tasks on external instances in an IPv6-only configuration as long as the instances are in IPv6-only subnets. For more information, see [Using a VPC in IPv6-only mode](task-networking.md#networking-ipv6-only). + The `UpdateContainerAgent` API isn't supported. For instructions on how to update the SSM Agent or the Amazon ECS agent on your external instances, see [Updating the AWS Systems Manager agent and Amazon ECS container agent on an external instance](ecs-anywhere-updates.md). + Amazon ECS capacity providers aren't supported. To create a service or run a standalone task on your external instances, use the `EXTERNAL` launch type. + SELinux isn't supported. + Using Amazon EFS volumes or specifying an `EFSVolumeConfiguration` isn't supported. + Integration with App Mesh isn't supported. + If you use the console to create an external instance task definition, you must create the task definition with the console JSON editor. + When you use a non Amazon ECS-optimized AMI, run the following commands on the external container instance to configure rules to use IAM roles for tasks. For more information, see [External instance additional configuration](task-iam-roles.md#enable_task_iam_roles). ``` $ sysctl -w net.ipv4.conf.all.route_localnet=1 $ iptables -t nat -A PREROUTING -p tcp -d 169.254.170.2 --dport 80 -j DNAT --to-destination 127.0.0.1:51679 $ iptables -t nat -A OUTPUT -d 169.254.170.2 -p tcp -m tcp --dport 80 -j REDIRECT --to-ports 51679 ``` ### Networking Amazon ECS external instances are optimized for running applications that generate outbound traffic or process data. If your application requires inbound traffic, such as a web service, the lack of Elastic Load Balancing support makes running these workloads less efficient because there isn't support for placing these workloads behind a load balancer. The following are additional considerations that are specific to networking with your external instances. + Service load balancing isn't supported. + Service discovery isn't supported. + Linux tasks that run on external instances must use the `bridge`, `host`, or `none` network modes. The `awsvpc` network mode isn't supported. For more information about each network mode, see [Amazon ECS task networking options for EC2 instances](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-networking.html). + You can run Linux tasks on external instances in an IPv6-only configuration as long as the instances are in IPv6-only subnets. For more information, see [Using a VPC in IPv6-only mode](task-networking.md#networking-ipv6-only). + There are Amazon ECS service domains in each Region and must be allowed to send traffic to your external instances. + The SSM Agent installed on your external instance maintains IAM credentials that are rotated every 30 minutes using a hardware fingerprint. If your external instance loses connection to AWS, the SSM Agent automatically refreshes the credentials after the connection is re-established. For more information, see [Validating on-premises servers and virtual machines using a hardware fingerprint](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent-technical-details.html#fingerprint-validation) in the *AWS Systems Manager User Guide*. The following domains are used for communication between the Amazon ECS service and the Amazon ECS agent that's installed on your external instance. Make sure that traffic is allowed and that DNS resolution works. For each endpoint, *region* represents the Region identifier for an AWS Region that's supported by Amazon ECS, such as `us-east-2` for the US East (Ohio) Region. The endpoints for all Regions that you use should be allowed. For the `ecs-a` and `ecs-t` endpoints, you should include an asterisk (for example, `ecs-a-*`). + `ecs-a-*.region.amazonaws.com` — This endpoint is used when managing tasks. + `ecs-t-*.region.amazonaws.com` — This endpoint is used to manage task and container metrics. + `ecs.region.amazonaws.com` — This is the service endpoint for Amazon ECS. + `ssm.region.amazonaws.com ` — This is the service endpoint for AWS Systems Manager. + `ec2messages.region.amazonaws.com` — This is the service endpoint that AWS Systems Manager uses to communicate between the Systems Manager agent and the Systems Manager service in the cloud. + `ssmmessages.region.amazonaws.com` — This is the service endpoint that is required to create and delete session channels with the Session Manager service in the cloud. + If your tasks require communication with any other AWS services, make sure that those service endpoints are allowed. Example applications include using Amazon ECR to pull container images or using CloudWatch for CloudWatch Logs. For more information, see [Service endpoints](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html) in the *AWS General Reference*. ### Amazon FSx for Windows File Server with ECS Anywhere **Important** Windows support for Amazon ECS Anywhere has been deprecated. This section is no longer applicable. In order to use the Amazon FSx for Windows File Server with Amazon ECS external instances you must establish a connection between your on-premises data center and the AWS Cloud. For information about the options for connecting your network to your VPC, see [Amazon Virtual Private Cloud Connectivity Options](https://docs.aws.amazon.com/whitepapers/latest/aws-vpc-connectivity-options/introduction.html). ### gMSA with ECS Anywhere **Important** Windows support for Amazon ECS Anywhere has been deprecated. This section is no longer applicable. The following use cases were supported for ECS Anywhere when Windows was a supported operating system. + The Active Directory is in the AWS Cloud - For this configuration, you create a connection between your on-premises network and the AWS Cloud using an AWS Direct Connect connection. For information about how to create the connection, see [Amazon Virtual Private Cloud Connectivity Options](https://docs.aws.amazon.com/whitepapers/latest/aws-vpc-connectivity-options/introduction.html).You create an Active Directory in the AWS Cloud. For information about how to get started with AWS Directory Service, see [Setting up AWS Directory Service](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/setting_up.html) in the *AWS Directory Service Administration Guide*. You can then join your external instances to the domain using the AWS Direct Connect connection. For information about working with gMSA with Amazon ECS, see [Learn how to use gMSAs for EC2 Windows containers for Amazon ECS](windows-gmsa.md). + The Active Directory is in the on-premises data center. - For this configuration, you join your external instances to the on-premises Active Directory. You then use the locally available credentials when you run the Amazon ECS tasks. # Creating an Amazon ECS cluster for External instance workloads You create a cluster to define the infrastructure your tasks and services run on. Before you begin, be sure that you've completed the steps in [Set up to use Amazon ECS](get-set-up-for-amazon-ecs.md) and assign the appropriate IAM permission. For more information, see [Amazon ECS cluster examples](security_iam_id-based-policy-examples.md#IAM_cluster_policies). The Amazon ECS console provides a simple way to create the resources that are needed by an Amazon ECS cluster by creating a CloudFormation stack. To make the cluster creation process as easy as possible, the console has default selections for many choices which we describe below. There are also help panels available for most of the sections in the console which provide further context. You can modify the following options: + Add a namespace to the cluster. A namespace allows services that you create in the cluster can connect to the other services in the namespace without additional configuration. For more information, see [Interconnect Amazon ECS services](interconnecting-services.md). + Configure the cluster for external instances + Assign a AWS KMS key for your managed storage. For information about how to create a key, see [Create a KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service User Guide*. + Add tags to help you identify your cluster. **To create a new cluster (Amazon ECS console)** 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. From the navigation bar, select the Region to use. 1. In the navigation pane, choose **Clusters**. 1. On the **Clusters** page, choose **Create cluster**. 1. Under **Cluster configuration**, configure the following: + For **Cluster name**, enter a unique name. The name can contain up to 255 letters (uppercase and lowercase), numbers, and hyphens. + (Optional) To have the namespace used for Service Connect be different from the cluster name, for **Namespace**, enter a unique name. 1. (Optional) Use Container Insights, expand **Monitoring**, and then choose one of the following options: + To use the recommended Container Insights with enhanced observability, choose **Container Insights with enhanced observability**. + To use Container Insights, choose **Container Insights**. 1. (Optional) To use ECS Exec to debug tasks in the cluster, expand **Troubleshooting configuration**, and then configure the following: + Select **Turn on ECS Exec**. + (Optional) For **AWS KMS key for ECS Exec**, enter the ARN of the AWS KMS key you want to use to encrypt the ECS Exec session data. + (Optional) For **ECS Exec logging**, choose the log destination: + To send logs to CloudWatch Logs, choose **Amazon CloudWatch**. + To send logs to Amazon S3, choose **Amazon S3**. + To disable logging, choose **None**. 1. (Optional) Encrypt the data on managed storage. Under **Encryption**, for **Managed storage**, enter the ARN of the AWS KMS key you want to use to encrypt the managed storage data. 1. (Optional) To help identify your cluster, expand **Tags**, and then configure your tags. [Add a tag] Choose **Add tag** and do the following: + For **Key**, enter the key name. + For **Value**, enter the key value. 1. Choose **Create**. ## Next steps You must register the instances with the cluster. For more information, see [Registering an external instance to an Amazon ECS cluster](ecs-anywhere-registration.md). Create a task definition for the external launch type. For more information, see [Creating an Amazon ECS task definition using the console](create-task-definition.md) Run your applications as standalone tasks, or as part of a service. For more information, see the following: + [Running an application as an Amazon ECS task](standalone-task-create.md) + [Creating an Amazon ECS rolling update deployment](create-service-console-v2.md) # Registering an external instance to an Amazon ECS cluster For each external instance you register with an Amazon ECS cluster, it must have the SSM Agent, the Amazon ECS container agent, and Docker installed. To register the external instance to an Amazon ECS cluster, it must first be registered as an AWS Systems Manager managed instance. You can create the installation script in a few clicks on the Amazon ECS console. The installation script includes an Systems Manager activation key and commands to install each of the required agents and Docker. The installation script must be run on your on-premises server or VM to complete the installation and registration steps. **Note** Before registering your Linux external instance with the cluster, create the `/etc/ecs/ecs.config` file on your external instance and add any container agent configuration parameters that you want. You can't do this after registering the external instance to a cluster. For more information, see [Amazon ECS container agent configuration](ecs-agent-config.md). ------ #### [ AWS Management Console ] 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. From the navigation bar, select the Region to use. 1. In the navigation pane, choose **Clusters**. 1. On the **Clusters** page, choose a cluster to register your external instance to. 1. On the **Cluster : *name*** page, choose the **Infrastructure** tab. 1. On the **Register external instances** page, complete the following steps. 1. For **Activation key duration (in days)**, enter the number of days that the activation key remains active for. After the number of days you entered pass, the key no longer works when registering an external instance. 1. For **Number of instances**, enter the number of external instances that you want to register to your cluster with the activation key. 1. For **Instance role**, choose the IAM role to associate with your external instances. If a role wasn't already created, choose **Create new role** to have Amazon ECS create a role on your behalf. For more information about what IAM permissions are required for your external instances, see [Amazon ECS Anywhere IAM role](iam-role-ecsanywhere.md). 1. Copy the registration command. This command should be run on each external instance you want to register to the cluster. **Important** The bash portion of the script must be run as root. If the command isn't run as root, an error is returned. 1. Choose **Close**. ------ #### [ AWS CLI for Linux operating systems ] 1. Create an Systems Manager activation pair. This is used for Systems Manager managed instance activation. The output includes an `ActivationId` and `ActivationCode`. You use these in a later step. Make sure that you specify the ECS Anywhere IAM role that you created. For more information, see [Amazon ECS Anywhere IAM role](iam-role-ecsanywhere.md). ``` aws ssm create-activation --iam-role ecsAnywhereRole | tee ssm-activation.json ``` 1. On your on-premises server or virtual machine (VM), download the installation script. ``` curl --proto "https" -o "/tmp/ecs-anywhere-install.sh" "https://amazon-ecs-agent.s3.amazonaws.com/ecs-anywhere-install-latest.sh" ``` 1. (Optional) On your on-premises server or virtual machine (VM), use the following steps to verify the installation script using the script signature file. 1. Download and install GnuPG. For more information about GNUpg, see the [GnuPG website](https://www.gnupg.org). For Linux systems, install `gpg` using the package manager on your flavor of Linux. 1. Retrieve the Amazon ECS PGP public key. ``` gpg --keyserver hkp://keys.gnupg.net:80 --recv BCE9D9A42D51784F ``` 1. Download the installation script signature. The signature is an ascii detached PGP signature stored in a file with the `.asc` extension. ``` curl --proto "https" -o "/tmp/ecs-anywhere-install.sh.asc" "https://amazon-ecs-agent.s3.amazonaws.com/ecs-anywhere-install-latest.sh.asc" ``` 1. Verify the installation script file using the key. ``` gpg --verify /tmp/ecs-anywhere-install.sh.asc /tmp/ecs-anywhere-install.sh ``` The following is the expected output. ``` gpg: Signature made Tue 25 May 2021 07:16:29 PM UTC gpg: using RSA key 50DECCC4710E61AF gpg: Good signature from "Amazon ECS " [unknown] gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: F34C 3DDA E729 26B0 79BE AEC6 BCE9 D9A4 2D51 784F Subkey fingerprint: D64B B6F9 0CF3 77E9 B5FB 346F 50DE CCC4 710E 61AF ``` 1. On your on-premises server or virtual machine (VM), run the installation script. Specify the cluster name, Region, and the Systems Manager activation ID and activation code from the first step. ``` sudo bash /tmp/ecs-anywhere-install.sh \ --region $REGION \ --cluster $CLUSTER_NAME \ --activation-id $ACTIVATION_ID \ --activation-code $ACTIVATION_CODE ``` For an on-premises server or virtual machine (VM) that has the NVIDIA driver installed for GPU workloads, you must add the `--enable-gpu` flag to the installation script. When this flag is specified, the install script verifies that the NVIDIA driver is running and then adds the required configuration variables to run your Amazon ECS tasks. For more information about running GPU workloads and specifying GPU requirements in a task definition, see [Specifying GPUs in an Amazon ECS task definition](ecs-gpu-specifying.md). ``` sudo bash /tmp/ecs-anywhere-install.sh \ --region $REGION \ --cluster $CLUSTER_NAME \ --activation-id $ACTIVATION_ID \ --activation-code $ACTIVATION_CODE \ --enable-gpu ``` Use the following steps to register an existing external instance with a different cluster. **To register an existing external instance with a different cluster** 1. Stop the Amazon ECS container agent. ``` sudo systemctl stop ecs.service ``` 1. Edit the `/etc/ecs/ecs.config` file and on the `ECS_CLUSTER` line, ensure the cluster name matches the name of the cluster to register the external instance with. 1. Remove the existing Amazon ECS agent data. ``` sudo rm /var/lib/ecs/data/agent.db ``` 1. Start the Amazon ECS container agent. ``` sudo systemctl start ecs.service ``` ------ #### [ AWS CLI for Windows operating systems ] 1. Create an Systems Manager activation pair. This is used for Systems Manager managed instance activation. The output includes an `ActivationId` and `ActivationCode`. You use these in a later step. Make sure that you specify the ECS Anywhere IAM role that you created. For more information, see [Amazon ECS Anywhere IAM role](iam-role-ecsanywhere.md). ``` aws ssm create-activation --iam-role ecsAnywhereRole | tee ssm-activation.json ``` 1. On your on-premises server or virtual machine (VM), download the installation script. ``` Invoke-RestMethod -URI "https://amazon-ecs-agent.s3.amazonaws.com/ecs-anywhere-install.ps1" -OutFile “ecs-anywhere-install.ps1” ``` 1. (Optional) The Powershell script is signed by Amazon and therefore, Windows automatically performs the certificate validation on the same. You do not need to perform any manual validation. To manually verify the certificate, right-click on the file, navigate to properties and use the Digital Signatures tab to obtain more details. This option is only available when the host has the certificate in the certificate store. The verification should return information similar to the following: ``` # Verification (PowerShell) Get-AuthenticodeSignature -FilePath .\ecs-anywhere-install.ps1 SignerCertificate Status Path ----------------- ------ ---- EXAMPLECERTIFICATE Valid ecs-anywhere-install.ps1 ... Subject : CN="Amazon Web Services, Inc.",... ---- ``` 1. On your on-premises server or virtual machine (VM), run the installation script. Specify the cluster name, Region, and the Systems Manager activation ID and activation code from the first step. ``` .\ecs-anywhere-install.ps1 -Region $Region -Cluster $Cluster -ActivationID $ActivationID -ActivationCode $ActivationCode ``` 1. Verify the Amazon ECS container agent is running. ``` Get-Service AmazonECS Status Name DisplayName ------ ---- ----------- Running AmazonECS Amazon ECS ``` Use the following steps to register an existing external instance with a different cluster. **To register an existing external instance with a different cluster** 1. Stop the Amazon ECS container agent. ``` Stop-Service AmazonECS ``` 1. Modify the `ECS_CLUSTER` parameter so that the cluster name matches the name of the cluster to register the external instance with. ``` [Environment]::SetEnvironmentVariable("ECS_CLUSTER", $ECSCluster, [System.EnvironmentVariableTarget]::Machine) ``` 1. Remove the existing Amazon ECS agent data. ``` Remove-Item -Recurse -Force $env:ProgramData\Amazon\ECS\data\* ``` 1. Start the Amazon ECS container agent. ``` Start-Service AmazonECS ``` ------ The AWS CLI can be used to create a Systems Manager activation before running the installation script to complete the external instance registration process. # Deregistering an Amazon ECS external instance We recommend that you deregister the instance from both Amazon ECS and AWS Systems Manager after you are done with the instance. Following deregistration, the external instance is no longer able to accept new tasks. If you have tasks that are running on the container instance when you deregister it, the tasks remain running until they stop through some other means. However, these tasks are no longer monitored or accounted for by Amazon ECS. If these tasks on your external instance are part of an Amazon ECS service, then the service scheduler starts another copy of that task, on a different instance, if possible. After you deregister the instance, clean up the remaining AWS resources on the instance. You can then register it to a new cluster. ## Procedure ------ #### [ AWS Management Console ] 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. From the navigation bar, choose the Region where your external instance is registered. 1. In the navigation pane, choose **Clusters** and select the cluster that hosts the external instance. 1. On the **Cluster : *name*** page, choose the **Infrastructure** tab. 1. Under **Container instances**, select the external instance ID to deregister. You're redirected to the container instance detail page. 1. On the **Container Instance : *id*** page, choose **Deregister**. 1. Review the deregistration message. Select **Deregister from AWS Systems Manager** to also deregister the external instance as an Systems Manager managed instance. Choose **Deregister**. **Note** You can deregister the external instance as an Systems Manager managed instance in the Systems Manager console. For instructions, see [Deregistering managed nodes in a hybrid and multicloud environment](https://docs.aws.amazon.com/systems-manager/latest/userguide/fleet-manager-deregister-hybrid-nodes.html) in the *AWS Systems Manager User Guide*. 1. After you deregister the instance, clean up AWS resources on your on-premises server or VM. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-anywhere-deregistration.html) ------ #### [ AWS CLI ] 1. You need the instance ID and the container instance ARN to deregister the container instance. If you do not have theses values, run the following comands Run the following commandto get the instance ID. You use the instance ID (`instanceID`) to get the container instance ARN (`containerInstanceARN`). ``` instanceId=$(aws ssm describe-instance-information --region "{{ region }}" | jq ".InstanceInformationList[] |select(.IPAddress==\"{{ IPv4 Address }}\") | .InstanceId" | tr -d'"' ``` Run the following commands. You use the `containerInstanceArn` as a parameter in the command to deregister the instance (`deregister-container-instance`). ``` instances=$(aws ecs list-container-instances --cluster "{{ cluster }}" --region "{{ region }}" | jq -c '.containerInstanceArns') containerInstanceArn=$(aws ecs describe-container-instances --cluster "{{ cluster }}" --region "{{ region }}" --container-instances $instances | jq ".containerInstances[] | select(.ec2InstanceId==\"{{ instanceId }}\") | .containerInstanceArn" | tr -d '"') ``` 1. Run the following command to drain the instance. ``` aws ecs update-container-instances-state --cluster "{{ cluster }}" --region "{{ region }}" --container-instances "{{ containerInstanceArn }}" --status DRAINING ``` 1. After the container instance finishes draining, run the following command to deregister the instance. ``` aws ecs deregister-container-instance --cluster "{{ cluster }}" --region "{{ region }}" --container-instance "{{ containerInstanceArn }}" ``` 1. Run the following command to remove the container instance from SSM. ``` aws ssm deregister-managed-instance --region "{{ region }}" --instance-id "{{ instanceId }}" ``` 1. After you deregister the instance, clean up AWS resources on your on-premises server or VM. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-anywhere-deregistration.html) ------ # Updating the AWS Systems Manager agent and Amazon ECS container agent on an external instance Your on-premises server or VM must run both the AWS Systems Manager Agent (SSM Agent) and the Amazon ECS container agent when running Amazon ECS workloads. AWS releases new versions of these agents when any capabilities are added or updated. If your external instances are using an earlier version of either agent, you can update them using the following procedures. ## Updating the SSM Agent on an external instance AWS Systems Manager recommends that you automate the process of updating the SSM Agent on your instances. They provide several methods to automate updates. For more information, see [Automating updates to SSM Agent](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent-automatic-updates.html) in the *AWS Systems Manager User Guide*. ## Updating the Amazon ECS agent on an external instance On your external instances, the Amazon ECS container agent is updated by upgrading the `ecs-init` package. Updating the Amazon ECS agent doesn't interrupt the running tasks or services. Amazon ECS provides the `ecs-init` package and signature file in an Amazon S3 bucket in each Region. Beginning with `ecs-init` version `1.52.1-1`, Amazon ECS provides separate `ecs-init` packages for use depending on the operating system and system architecture your external instance uses. Use the following table to determine the `ecs-init` package that you should download based on the operating system and system architecture your external instance uses. **Note** You can determine which operating system and system architecture that your external instance uses by using the following commands. ``` cat /etc/os-release uname -m ``` | Operating systems (architecture) | ecs-init package | | --- | --- | | CentOS 7 (x86\$164) CentOS 8 (x86\$164) CentOS Stream 9 (x86\$164) SUSE Enterprise Server 15 (x86\$164) RHEL 7 (x86\$164) RHEL 8 (x86\$164) | `amazon-ecs-init-latest.x86_64.rpm` | | CentOS 7 (aarch64) CentOS 8 (aarch64) CentOS Stream 9 (aarch64) RHEL 7 (aarch64) | `amazon-ecs-init-latest.aarch64.rpm` | | Debian 9 (x86\$164) Debian 10 (x86\$164) Debian 11 (x86\$164) Debian 12 (x86\$164) Ubuntu 18 (x86\$164) Ubuntu 20 (x86\$164) Ubuntu 22 (x86\$164) Ubuntu 24 (x86\$164) | `amazon-ecs-init-latest.amd64.deb` | | Debian 9 (aarch64) Debian 10 (aarch64) Debian 11 (aarch64) Debian 12 (aarch64) Ubuntu 18 (aarch64) Ubuntu 20 (aarch64) Ubuntu 22 (aarch64) Ubuntu 24 (aarch64) | `amazon-ecs-init-latest.arm64.deb` | Follow these steps to update the Amazon ECS agent. **To update the Amazon ECS agent** 1. Confirm the Amazon ECS agent version that you're running. ``` curl -s 127.0.0.1:51678/v1/metadata | python3 -mjson.tool ``` 1. Download the `ecs-init` package for your operating system and system architecture. Amazon ECS provides the `ecs-init` package file in an Amazon S3 bucket in each Region. Make sure that you replace the ** identifier in the command with the Region name (for example, `us-west-2`) that you're geographically closest to. **amazon-ecs-init-latest.x86\$164.rpm** ``` curl -o amazon-ecs-init.rpm https://s3..amazonaws.com/amazon-ecs-agent-/amazon-ecs-init-latest.x86_64.rpm ``` **amazon-ecs-init-latest.aarch64.rpm** ``` curl -o amazon-ecs-init.rpm https://s3..amazonaws.com/amazon-ecs-agent-/amazon-ecs-init-latest.aarch64.rpm ``` **amazon-ecs-init-latest.amd64.deb** ``` curl -o amazon-ecs-init.deb https://s3..amazonaws.com/amazon-ecs-agent-/amazon-ecs-init-latest.amd64.deb ``` **amazon-ecs-init-latest.arm64.deb** ``` curl -o amazon-ecs-init.deb https://s3..amazonaws.com/amazon-ecs-agent-/amazon-ecs-init-latest.arm64.deb ``` 1. (Optional) Verify the validity of the `ecs-init` package file using the PGP signature. 1. Download and install GnuPG. For more information about GNUpg, see the [GnuPG website](https://www.gnupg.org). For Linux systems, install `gpg` using the package manager on your flavor of Linux. 1. Retrieve the Amazon ECS PGP public key. ``` gpg --keyserver hkp://keys.gnupg.net:80 --recv BCE9D9A42D51784F ``` 1. Download the `ecs-init` package signature. The signature is an ASCII detached PGP signature that's stored in a file with the `.asc` extension. Amazon ECS provides the signature file in an Amazon S3 bucket in each Region. Make sure that you replace the ** identifier in the command with the Region name (for example, `us-west-2`) that you're geographically closest to. **amazon-ecs-init-latest.x86\$164.rpm** ``` curl -o amazon-ecs-init.rpm.asc https://s3..amazonaws.com/amazon-ecs-agent-/amazon-ecs-init-latest.x86_64.rpm.asc ``` **amazon-ecs-init-latest.aarch64.rpm** ``` curl -o amazon-ecs-init.rpm.asc https://s3..amazonaws.com/amazon-ecs-agent-/amazon-ecs-init-latest.aarch64.rpm.asc ``` **amazon-ecs-init-latest.amd64.deb** ``` curl -o amazon-ecs-init.deb.asc https://s3..amazonaws.com/amazon-ecs-agent-/amazon-ecs-init-latest.amd64.deb.asc ``` **amazon-ecs-init-latest.arm64.deb** ``` curl -o amazon-ecs-init.deb.asc https://s3..amazonaws.com/amazon-ecs-agent-/amazon-ecs-init-latest.arm64.deb.asc ``` 1. Verify the `ecs-init` package file using the key. **For the `rpm` packages** ``` gpg --verify amazon-ecs-init.rpm.asc ./amazon-ecs-init.rpm ``` **For the `deb` packages** ``` gpg --verify amazon-ecs-init.deb.asc ./amazon-ecs-init.deb ``` The following is the expected output. ``` gpg: Signature made Fri 14 May 2021 09:31:36 PM UTC gpg: using RSA key 50DECCC4710E61AF gpg: Good signature from "Amazon ECS " [unknown] gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: F34C 3DDA E729 26B0 79BE AEC6 BCE9 D9A4 2D51 784F Subkey fingerprint: D64B B6F9 0CF3 77E9 B5FB 346F 50DE CCC4 710E 61AF ``` 1. Install the `ecs-init` package. **For the `rpm` package on CentOS 7, CentOS 8, and RHEL 7** ``` sudo yum install -y ./amazon-ecs-init.rpm ``` **For the `rpm` package on SUSE Enterprise Server 15** ``` sudo zypper install -y --allow-unsigned-rpm ./amazon-ecs-init.rpm ``` **For the `deb` package** ``` sudo dpkg -i ./amazon-ecs-init.deb ``` 1. Restart the `ecs` service. ``` sudo systemctl restart ecs ``` 1. Verify the Amazon ECS agent version was updated. ``` curl -s 127.0.0.1:51678/v1/metadata | python3 -mjson.tool ```