AWS Compute Blog
Introducing private registry authentication support for AWS Fargate
This post courtesy of Tiffany Jernigan, AWS Developer Advocate – Containers
Private registry authentication support for Amazon Elastic Container Service (Amazon ECS) is now available with the AWS Fargate launch type! Now, in addition to Amazon Elastic Container Registry (Amazon ECR), you can use any private registry or repository of your choice for both EC2 and Fargate launch types.
For ECS to pull from a private repository, it needs a secret in AWS Secrets Manager with your registry credentials, an ECS task execution IAM role in AWS Identity Access Management (IAM) with a policy granting access to the secret, and a task with the secret and task execution IAM role ARNs in the task definition.
Here’s how to use ECS with a private repository on Docker Hub via the AWS Management Console.
Registry
If you don’t already have a private repository (or account), you can create a free repo now. To follow along, run the following commands in a terminal to pull an image, get the image ID, and push it to your new repository:
Secrets Manager
In the Secrets Manager console, store a new secret with your Docker Hub credentials, which is used to access your private repository.
By default, Secrets Manager creates an encryption key, DefaultEncryptionKey, on your behalf. You can instead use an existing key or add a new one with AWS Key Management Service (AWS KMS), if you would prefer.
Choose Other type of secrets and add secret keys and values for username and password.
Next, create a name, such as dockerhub, and description for your secret.
Because the keys are corresponding to your Docker Hub credentials, leave rotation disabled.
On the next page, you can review your settings and store your secret. Open your new secret to see the details. Write down the Secret ARN value and keep it handy, as it is used in the next step and later, in your task definition.
IAM
Now that you have a secret, you need to provide Fargate permissions to read it. This is done via a task execution IAM role.
In the IAM console, choose Policies, Create policy. Provide Secrets Manager with read access for secretsmanager:GetSecretValue, with your secret’s ARN as the resource.
Name your policy dockerhubsecret.
If you chose to use your own encryption key, you also need to create a policy with kms:Decrypt permissions for KMS.
Next, choose Role to create an IAM role, which is used as your task execution role. Choose AWS service, Elastic Container Service, and Elastic Container Service Task.
Search for your dockerhubsecret policy and attach it to the role.
Lastly, give the role a name, such as ecsExecutionRoleDockerHub, and create it. Copy the role ARN value. Depending on how you create your task definition, you may need it.
ECS
While the mechanism to authenticate private registries is supported on both EC2 and Fargate launch types, for this example we will be launching a task on Fargate.
Before you can create a task, you need an ECS cluster, VPC, and subnets. If you don’t already have them, in the ECS console, choose Clusters, Get Started. Keep track of the cluster name, VPC ID, and subnet IDs, as you use them soon.
It’s time to create your task definition, which is used to create your task (grouping of up to ten containers that run on the same host). This is where you need your Secrets Manager ARN and IAM role name.
Choose Task Definitions, Create new Task Definition, and select the Fargate launch type. You can then configure your task definition via the wizard or scroll down, choose Configure via JSON and paste the following task definition after replacing fields with angle brackets. This task definition also works with the EC2 launch type.
{
"family": "space-td",
"containerDefinitions": [
{
"name": "space",
"image": "<your-username/repository-name>",
"portMappings": [
{
"protocol": "tcp",
"containerPort": 80
}
],
"cpu": 0,
"repositoryCredentials": {
"credentialsParameter": "<secret-ARN>"
}
}
],
"memory": "512",
"cpu": "256",
"requiresCompatibilities": [
"FARGATE"
],
"networkMode": "awsvpc",
"executionRoleArn": "<execution-role-ARN>"
}
If you use the wizard, give your task a name, such as space-td, and specify your task execution IAM role (ecsTaskExecutionRoleDockerHub), a task size of 0.5 GB of memory, and 0.25 vCPU.
Next, choose Container Definitions, Add container. Give the container a name, specify your image <your-username/repository-name>, check the box for private registry authentication, and add your secrets manager ARN and a container port 80. Choose Add.
After you create your task definition, choose Actions, Run Task, and specify the Fargate launch type, your cluster, cluster VPC, subnets, a security group with inbound permissions for your container ports (the default one provides access to port 80). Enable auto-assigning a public IP address.
Open the task from its ID to see the details:
When the Last status field is RUNNING, under Network, copy the public IP address and paste it in a browser.
If you used pushed tiffanyfay/space to your repository, you should see the following:
I hope this post has helped you. If you have any questions, feel free to reach out!
Special thanks to Yuling Zhou, Deepak Dayama, Derek Petersen, Varun Iyer, Adnan Khan and several others for their insights in this blog.