Amazon ECS interface VPC endpoints (AWS PrivateLink) - Amazon Elastic Container Service
Considerations Creating the VPC Endpoints for Amazon ECSCreating a VPC endpoint policy for Amazon ECS

Amazon ECS interface VPC endpoints (AWS PrivateLink)

You can improve the security posture of your VPC by configuring Amazon ECS to use an interface VPC endpoint. Interface endpoints are powered by AWS PrivateLink, a technology that allows you to privately access Amazon ECS APIs by using private IP addresses. AWS PrivateLink restricts all network traffic between your VPC and Amazon ECS to the Amazon network. You don't need an internet gateway, a NAT device, or a virtual private gateway.

For more information about AWS PrivateLink and VPC endpoints, see VPC endpoints in the Amazon VPC User Guide.

Considerations

Considerations for endpoints in Regions introduced starting on December 23, 2023

Before you set up interface VPC endpoints for Amazon ECS, be aware of the following considerations:

  • You must have the following Region-specific VPC endpoints:

    Note

    If you do not configure all of the endpoints, your traffic will go over the public endpoints, not your VPC endpoint.

    • com.amazonaws.region.ecs-agent

    • com.amazonaws.region.ecs-telemetry

    • com.amazonaws.region.ecs

    For example, the Canada West (Calgary) (ca-west-1) Region needs the following VPC endpoints:

    • com.amazonaws.ca-west-1.ecs-agent

    • com.amazonaws.ca-west-1.ecs-telemetry

    • com.amazonaws.ca-west-1.ecs

  • When you use a template to create AWS resources in the new Region and the template was copied from a Region introduced before December 23, 2023, depending on the copy-from Region, perform one of the following operations.

    For example, the copy-from Region is US East (N. Virginia) (us-east-1). The copy-to Region is Canada West (Calgary) (ca-west-1) .

    Configuration Action

    The copied-from Region does not have any VPC endpoints.

    Create all three VPC endpoints for the new Region (for example, com.amazonaws.ca-west-1.ecs-agent).

    The copied-from Region contains Region-specific VPC endpoints.

    1. Create all three VPC endpoints for the new Region (for example, com.amazonaws.ca-west-1.ecs-agent).

    2. Delete all three VPC endpoints for the copy-from Region (for example, com.amazonaws.us-east-1.ecs-agent).

Considerations for Amazon ECS VPC endpoints for the Fargate launch type

When there is an VPC endpoint for ecr.dkr and ecr.api in the same VPC where a Fargate task is deployed into, it will use the VPC endpoint. If there is no VPC endpoint, it will use the Fargate interface.

Before you set up interface VPC endpoints for Amazon ECS, be aware of the following considerations:

  • Tasks using the Fargate launch type don't require the interface VPC endpoints for Amazon ECS, but you might need interface VPC endpoints for Amazon ECR, Secrets Manager, or Amazon CloudWatch Logs described in the following points.

    • To allow your tasks to pull private images from Amazon ECR, you must create the interface VPC endpoints for Amazon ECR. For more information, see Interface VPC Endpoints (AWS PrivateLink) in the Amazon Elastic Container Registry User Guide.

      Important

      If you configure Amazon ECR to use an interface VPC endpoint, you can create a task execution role that includes condition keys to restrict access to a specific VPC or VPC endpoint. For more information, see Fargate tasks pulling Amazon ECR images over interface endpoints permissions.

    • To allow your tasks to pull sensitive data from Secrets Manager, you must create the interface VPC endpoints for Secrets Manager. For more information, see Using Secrets Manager with VPC Endpoints in the AWS Secrets Manager User Guide.

    • If your VPC doesn't have an internet gateway and your tasks use the awslogs log driver to send log information to CloudWatch Logs, you must create an interface VPC endpoint for CloudWatch Logs. For more information, see Using CloudWatch Logs with Interface VPC Endpoints in the Amazon CloudWatch Logs User Guide.

  • VPC endpoints currently don't support cross-Region requests. Ensure that you create your endpoint in the same Region where you plan to issue your API calls to Amazon ECS. For example, assume that you want to run tasks in US East (N. Virginia). Then, you must create the Amazon ECS VPC endpoint in US East (N. Virginia). An Amazon ECS VPC endpoint created in any other region can't run tasks in US East (N. Virginia).

  • VPC endpoints only support Amazon-provided DNS through Amazon Route 53. If you want to use your own DNS, you can use conditional DNS forwarding. For more information, see DHCP Options Sets in the Amazon VPC User Guide.

  • The security group attached to the VPC endpoint must allow incoming connections on TCP port 443 from the private subnet of the VPC.

  • Service Connect management of the Envoy proxy uses the com.amazonaws.region.ecs-agent VPC endpoint. When you don't use the VPC endpoints, Service Connect management of the Envoy proxy uses the ecs-sc endpoint in that Region. For a list of the Amazon ECS endpoints in each Region, see Amazon ECS endpoints and quotas.

Considerations for Amazon ECS VPC endpoints for the EC2 launch type

Before you set up interface VPC endpoints for Amazon ECS, be aware of the following considerations:

  • Tasks using the EC2 launch type require that the container instances that they're launched on to run version 1.25.1 or later of the Amazon ECS container agent. For more information, see Amazon ECS Linux container instance management.

  • To allow your tasks to pull sensitive data from Secrets Manager, you must create the interface VPC endpoints for Secrets Manager. For more information, see Using Secrets Manager with VPC Endpoints in the AWS Secrets Manager User Guide.

  • If your VPC doesn't have an internet gateway and your tasks use the awslogs log driver to send log information to CloudWatch Logs, you must create an interface VPC endpoint for CloudWatch Logs. For more information, see Using CloudWatch Logs with Interface VPC Endpoints in the Amazon CloudWatch Logs User Guide.

  • VPC endpoints currently don't support cross-Region requests. Ensure that you create your endpoint in the same Region where you plan to issue your API calls to Amazon ECS. For example, assume that you want to run tasks in US East (N. Virginia). Then, you must create the Amazon ECS VPC endpoint in US East (N. Virginia). An Amazon ECS VPC endpoint created in any other Region can't run tasks in US East (N. Virginia).

  • VPC endpoints only support Amazon-provided DNS through Amazon Route 53. If you want to use your own DNS, you can use conditional DNS forwarding. For more information, see DHCP Options Sets in the Amazon VPC User Guide.

  • The security group attached to the VPC endpoint must allow incoming connections on TCP port 443 from the private subnet of the VPC.

Creating the VPC Endpoints for Amazon ECS

To create the VPC endpoint for the Amazon ECS service, use the Access an AWS service using an interface VPC endpoint procedure in the Amazon VPC User Guide to create the following endpoints. If you have existing container instances within your VPC, you should create the endpoints in the order that they're listed. If you plan on creating your container instances after your VPC endpoint is created, the order doesn't matter.

Note

If you do not configure all of the endpoints, your traffic will go over the public endpoints, not your VPC endpoint.

When you create endpoints, Amazon ECS also creates a private DNS name for the endpoint. For example, ecs-a.region.amazonaws.com for ecs-agent and ecs-t.region.amazonaws.com for ecs-telemetry.

  • com.amazonaws.region.ecs-agent

  • com.amazonaws.region.ecs-telemetry

  • com.amazonaws.region.ecs

Note

region represents the Region identifier for an AWS Region supported by Amazon ECS, such as us-east-2 for the US East (Ohio) Region.

The ecs-agent endpoint uses the ecs:poll API, and the ecs-telemetry endpoint uses the ecs:poll and ecs:StartTelemetrySession API.

If you have existing tasks that are using the EC2 launch type, after you have created the VPC endpoints, each container instance needs to pick up the new configuration. For this to happen, you must either reboot each container instance or restart the Amazon ECS container agent on each container instance. To restart the container agent, do the following.

To restart the Amazon ECS container agent

  1. Log in to your container instance via SSH.

  2. Stop the container agent.

    sudo docker stop ecs-agent

  3. Start the container agent.

    sudo docker start ecs-agent

After you have created the VPC endpoints and restarted the Amazon ECS container agent on each container instance, all newly launched tasks pick up the new configuration.

Creating a VPC endpoint policy for Amazon ECS

You can attach an endpoint policy to your VPC endpoint that controls access to Amazon ECS. The policy specifies the following information:

  • The principal that can perform actions.

  • The actions that can be performed.

  • The resources on which actions can be performed.

For more information, see Controlling access to services with VPC endpoints in the Amazon VPC User Guide.

Example: VPC endpoint policy for Amazon ECS actions

The following is an example of an endpoint policy for Amazon ECS. When attached to an endpoint, this policy grants access to permission to create and list clusters. The CreateCluster and ListClusters actions do not accept any resources, so the resource definition is set to * for all resources. 

{
   "Statement":[
    {
      "Effect": "Allow",
      "Action": [
        "ecs:CreateCluster",
        "ecs:ListClusters"
      ],
      "Resource": [
        "*"
      ]
    }
  ]
}