Deregistering an Amazon ECS container instance - Amazon Elastic Container Service

Deregistering an Amazon ECS container instance

Important

This topic is for container instances created in Amazon EC2 only. For more information about deregistering external instances, see Deregistering an Amazon ECS external instance.

When you are finished with an Amazon EC2 backed container instance, you should deregister it from your cluster. Following deregistration, the container instance is no longer able to accept new tasks.

If you have tasks running on the container instance when you deregister it, these tasks remain running until you terminate the instance or the tasks stop through some other means. However, these tasks are orphaned which means they are no longer monitored or accounted for by Amazon ECS. If an orphaned task on your container instance is part of an Amazon ECS service, then the service scheduler starts another copy of that task, on a different container instance, if possible. Any containers in orphaned service tasks that are registered with an Application Load Balancer target group are deregistered. They begin connection draining according to the settings on the load balancer or target group. If an orphaned tasks is using the awsvpc network mode, their elastic network interfaces are deleted.

If you intend to use the container instance for some other purpose after deregistration, you should stop all of the tasks running on the container instance before deregistration. This stops any orphaned tasks from consuming resources.

When deregistering a container instance, be aware of the following considerations.

  • Because each container instance has unique state information, they should not be deregistered from one cluster and re-registered into another. To relocate container instance resources, we recommend that you terminate container instances from one cluster and launch new container instances in the new cluster. For more information, see Terminate your instance in the Amazon EC2 User Guide and Launching an Amazon ECS Linux container instance.

  • If the container instance is managed by an Auto Scaling group or a AWS CloudFormation stack, terminate the instance by updating the Auto Scaling group or AWS CloudFormation stack. Otherwise, the Auto Scaling group or AWS CloudFormation will create a new instance after you terminate it.

  • If you terminate a running container instance with a connected Amazon ECS container agent, the agent automatically deregisters the instance from your cluster. Stopped container instances or instances with disconnected agents are not automatically deregistered when terminated.

  • Deregistering a container instance removes the instance from a cluster, but it does not terminate the Amazon EC2 instance. If you are finished using the instance, be sure to terminate it to stop billing. For more information, see Terminate your instance in the Amazon EC2 User Guide.

Procedure

  1. Open the console at https://console.aws.amazon.com/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 instance.

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

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

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

  7. On the confirmation screen, choose Deregister.

  8. If you are finished with the container instance, terminate the underlying Amazon EC2 instance. For more information, see Terminate Your Instance in the Amazon EC2 User Guide.