Docker Registry credentials in AWS CloudFormation templates

With the changes at Docker Hub recently around image pulls and authentication, you might run into the situation where your AWS CloudFormation template pulls an image and receives an authorization error message. This can happen if you’re trying to deploy to Amazon ECS or just on an Amazon EC2 instance.

Note that this post doesn’t actually apply just to Docker Hub – this can be used for any container registry that requires authentication!

For Amazon ECS, the solution is to modify your template to get your Docker Hub credentials into AWS Secrets Manager. For Amazon EC2, it’s a bit simpler since you can just read the parameters and skip the secret.

Neither is are complex solutions, but it did take some trial and error on my part. So, here’s a post to help others get through it faster. The snippet below is for Amazon ECS.

You should really read the password from AWS Secret Store from within your template and not create it this way. This is just for illustration to help you see what’s going on. Ideally, the secret would already exist and just be referenced by ARN in the task definition below. Otherwise you’ll have scripts that contain your password and that’s not good. And don’t even think of just throwing NoEcho on it! That’s not a solution and is a blog post on its own. So with that said, here are the parameters:

  DockerHubUsername:
    Description: DockerHub username for pulling images
    Type: String

  DockerHubPassword:
    Description: DockerHub password for pulling images
    Type: String

Next, create a secret using the username and password.

  DockerHubSecret:
    Type: AWS::SecretsManager::Secret
    Properties:
      Description: DockerHub login credentials for
      SecretString: !Sub '{ "username" : "${DockerHubUsername}" , "password" : "${DockerHubPassword}" }'

Now, we can use that secret when pulling images to ECS:

  TaskDefinition:
    Type: AWS::ECS::TaskDefinition
    DependsOn: DockerHubSecret
    Properties:
      RequiresCompatibilities:
        - FARGATE
      Cpu: 512
      Memory: 4096
      NetworkMode: awsvpc
      ExecutionRoleArn: !RefFargateTaskExecutionRole
      TaskRoleArn: !Ref TaskRole
      ContainerDefinitions:
        - Name: ubuntu
          Image: ubuntu/ubuntu:latest
          RepositoryCredentials:
            CredentialsParameter: !Ref DockerHubSecret

Some images can be pulled without authentication, but some do require authentication. (It’s based on the subscription of the image owner’s Docker Hub account.) But, if you’re trying to pull an image and receive an authentication error, the above snippet should get you going.

Here’s some links for more reading: