Registering an external instance to a cluster - Amazon Elastic Container Service

Registering an external instance to a 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.


Before registering your 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.

New AWS Management Console
  1. Find the public IP or DNS address for your container instance.

    1. Open the new console at

    2. In the navigation pane, choose Clusters and select the cluster that hosts the instance.

    3. On the Cluster : name page, choose the Infrastructure tab.

    4. Under Container instances, select the instance ID

    5. On the Instances page, record the Public IP or Public DNS for your instance.

  2. Find the default username for your container instance AMI.

  3. You can connect to your instance by using RDP. For more information, see Connect to your Windows instance using RDP in the Amazon EC2 User Guide for Windows Instances.

Classic AWS Management Console
  1. Open the Amazon ECS console at

  2. From the navigation bar, select the Region to use.

  3. In the navigation pane, choose Clusters.

  4. On the Clusters page, choose a cluster to register your external instance to.

  5. Choose the ECS Instances tab, then choose Register external instances.

  6. On the Step 1: External instances activation details 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.

    2. For Number of instances, enter the number of external instances that you want to register to your cluster with the activation key.

    3. 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 Required IAM permissions for external instances.

    4. Choose Next step.

  7. On the Step 2: Register external instances page, copy the registration command. This command should be run on each external instance you want to register to the cluster.


    The bash portion of the script must be run as root. If the command isn't run as root, an error is returned.

  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 Required IAM permissions for external instances.

    aws ssm create-activation --iam-role ecsAnywhereRole | tee ssm-activation.json
  2. On your on-premises server or virtual machine (VM), download the installation script.

    curl --proto "https" -o "/tmp/" ""
  3. (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. For Linux systems, install gpg using the package manager on your flavor of Linux.

    2. Retrieve the Amazon ECS PGP public key.

      gpg --keyserver hkp:// --recv BCE9D9A42D51784F
    3. 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/" ""
    4. Verify the installation script file using the key.

      gpg --verify /tmp/ /tmp/

      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
  4. 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/ \ --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 your task definition.

    sudo bash /tmp/ \ --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
  2. 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.

  3. Remove the existing Amazon ECS agent data.

    sudo rm /var/lib/ecs/data/agent.db
  4. Start the Amazon ECS container agent.

    sudo systemctl start ecs.service

The AWS CLI can be used to create a Systems Manager activation before running the installation script to complete the external instance registration process.