The Amazon ECS container agent can authenticate with private registries, including Docker Hub, using basic authentication. When you enable private registry authentication, you can use private Docker images in your task definitions.

The agent looks for two environment variables when it launches: ECS_ENGINE_AUTH_TYPE, which specifies the type of authentication data that is being sent, and ECS_ENGINE_AUTH_DATA, which contains the actual authentication credentials.

The Amazon ECS-optimized AMI scans the /etc/ecs/ecs.config file for these variables when the container instance launches, and each time the service is started (with the sudo start ecs command). AMIs that are not Amazon ECS-optimized should store these environment variables in a file and pass them with the --env-filepath_to_env_file option to the docker run command that starts the container agent.

Important

We do not recommend that you inject these authentication environment variables at instance launch time with Amazon EC2 user data or pass them with the --env option to the docker run command. These methods are not appropriate for sensitive data like authentication credentials. To safely add authentication credentials to your container instances, see Storing Container Instance Configuration in Amazon S3.

Authentication Formats

There are two available formats for private registry authentication, dockercfg and docker.

dockercfg Authentication Format

The dockercfg format uses the authentication information stored in the configuration file that is created when you run the docker login command. You can create this file by running docker login on your local system (or by logging into a container instance and running the command there) and entering your registry user name, password, and email address. After you create the file, you can get the authentication information with the following command.

$ cat ~/.dockercfg
{"https://index.docker.io/v1/":{"auth":"zq212MzEXAMPLE7o6T25Dk0i","email":"[email protected]"}}

In this example, the following environment variables should be added to the environment variable file (/etc/ecs/ecs.config for the Amazon ECS-optimized AMI) that the Amazon ECS container agent loads at run time. If you are not using the Amazon ECS-optimized AMI and you are starting the agent manually with docker run, specify the environment variable file with the --env-file path_to_env_file option when you start the agent.

ECS_ENGINE_AUTH_TYPE=dockercfg
ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"auth":"zq212MzEXAMPLE7o6T25Dk0i","email":"[email protected]"}}

docker Authentication Format

The docker format uses a JSON representation of the registry server that the agent should authenticate with, as well as the authentication parameters required by that registry (such as user name, password, and the email address for that account). For a Docker Hub account, the JSON representation looks like this:

{
  "https://index.docker.io/v1/": {
    "username": "my_name",
    "password": "my_password",
    "email": "[email protected]"
  }
}

In this example, the following environment variables should be added to the environment variable file (/etc/ecs/ecs.config for the Amazon ECS-optimized AMI) that the Amazon ECS container agent loads at run time. If you are not using the Amazon ECS-optimized AMI and you are starting the agent manually with docker run, specify the environment variable file with the --env-file path_to_env_file option when you start the agent.

ECS_ENGINE_AUTH_TYPE=docker
ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"username":"my_name","password":"my_password","email":"[email protected]"}}

Enabling Private Registries

Use the following procedure to enable private registries for your container instances.

To enable private registries in the Amazon ECS-optimized AMI

1. Log into your container instance via SSH.
2. Open the /etc/ecs/ecs.config file and add the ECS_ENGINE_AUTH_TYPE and ECS_ENGINE_AUTH_DATAvalues for your registry and account.[ec2-user ~]$ vi /etc/ecs/ecs.configThis example authenticates a Docker Hub user account.ECS_ENGINE_AUTH_TYPE=docker ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"username":"my_name","password":"my_password","email":"[email protected]"}}
3. Check to see if your agent uses the ECS_DATADIR environment variable to save its state.[ec2-user ~]$ docker inspect ecs-agent | grep ECS_DATADIR "ECS_DATADIR=/data",ImportantIf the previous command does not return the ECS_DATADIR environment variable, you must stop any tasks running on this container instance before stopping the agent. Newer agents with theECS_DATADIR environment variable save their state and you can stop and start them while tasks are running without issues. For more information, see Updating the Amazon ECS Container Agent.
4. Stop the ecs service.[ec2-user ~]$ sudo stop ecs ecs stop/waiting
5. Restart the ecs service.[ec2-user ~]$ sudo start ecs ecs start/running, process 2959
6. (Optional) You can verify that the agent is running and see some information about your new container instance by querying the agent introspection API. For more information, see the section called “Amazon ECS Container Agent Introspection”.[ec2-user ~]$ curl http://localhost:51678/v1/metadata { "Cluster": "default", "ContainerInstanceArn": "<container_instance_ARN>", "Version":"Amazon ECS Agent - v1.5.0 (b197edd)" }

Views: 55