Deregistering an external instance - Amazon Elastic Container Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Deregistering an external instance

We recommend that, after you finish using an external instance, you deregister the instance from both Amazon ECS and Amazon Systems Manager. 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.

To register an external instance to a new cluster, after the external instance has been deregistered from both Amazon ECS and Systems Manager, you can clean up the remaining Amazon resources on the instance and register it with a new cluster.

Amazon Web Services Management Console

  1. Open the console at https://console.amazonaws.cn/ecs/v2.

  2. From the navigation bar, choose the Region where your external instance is registered.

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

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

  5. Under Container instances, select the external instance ID to deregister. You're redirected to the container instance detail page.

  6. On the Container Instance : id page, choose Deregister.

  7. Review the deregistration message. Select Deregister from Amazon 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 instances in the Amazon Systems Manager User Guide.

  8. After you deregister the instance, clean up Amazon resources on your on-premises server or VM .

    Operating system Steps

    Linux

    1. Stop the Amazon ECS container agent and the SSM Agent services on the instance.

      sudo systemctl stop ecs amazon-ssm-agent

    2. Remove the Amazon ECS and Systems Manager packages.

      For CentOS 7, CentOS 8, and RHEL 7

      sudo yum remove -y amazon-ecs-init amazon-ssm-agent

      For SUSE Enterprise Server 15

      sudo zypper remove -y amazon-ecs-init amazon-ssm-agent

      For Debian and Ubuntu

      sudo apt remove -y amazon-ecs-init amazon-ssm-agent

    3. Remove the leftover directories.

       sudo rm -rf /var/lib/ecs /etc/ecs /var/lib/amazon/ssm /var/log/ecs /var/log/amazon/ssm
    Windows

    1. Stop the Amazon ECS container agent and the SSM Agent services on the instance.

      Stop-Service AmazonECS
      Stop-Service AmazonSSMAgent

    2. Remove the Amazon ECS package.

      .\ecs-anywhere-install.ps1 -Uninstall
Amazon 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 '"')

  2. Run the following command to drain the instance.

    aws ecs update-container-instances-state --cluster "{{ cluster }}" --region "{{ region }}" --container-instances "{{ containerInstanceArn }}" --status DRAINING

  3. 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 }}"

  4. Run the following command to remove the container instance from SSM.

    aws ssm deregister-managed-instance --region "{{ region }}" --instance-id "{{ instanceId }}"

  5. After you deregister the instance, clean up Amazon resources on your on-premises server or VM .

    Operating system Steps

    Linux

    1. Stop the Amazon ECS container agent and the SSM Agent services on the instance.

      sudo systemctl stop ecs amazon-ssm-agent

    2. Remove the Amazon ECS and Systems Manager packages.

      sudo (yum/apt/zypper) remove amazon-ecs-init amazon-ssm-agent

    3. Remove the leftover directories.

       sudo rm -rf /var/lib/ecs /etc/ecs /var/lib/amazon/ssm /var/log/ecs /var/log/amazon/ssm
    Windows

    1. Stop the Amazon ECS container agent and the SSM Agent services on the instance.

      Stop-Service AmazonECS
      Stop-Service AmazonSSMAgent

    2. Remove the Amazon ECS package.

      .\ecs-anywhere-install.ps1 -Uninstall