- [Using Private Registry Authentication](#using-private-registry-authentication)

If you want to use privately hosted container images with ECS, the ECS CLI can store your private registry credentials in AWS Secrets Manager and create an IAM role which ECS can use to access the credentials and private images. This allows you to:

* Store private registry credentials within AWS for use with ECS

* Add the permissions needed to use your registry secrets to a new or existing Task Execution Role

* Automatically add your private registry credentials to your task definition when running a task or service

Using privately hosted images with the ECS CLI is done in two parts:

1) Create new AWS Secrets Manager secrets and an IAM Task Execution Role with `ecs-cli registry-creds up`

2) Run `ecs-cli compose` commands to create and run a task definition that includes the new resources

To get started, first create an input file that contains the name of your registry and the credentials needed to access it:

In this example, we're storing credentials for a registry called `my-registry.example.com` and passing in the password with an environment variable. `container_names` is a list of the `service_names` in your Docker Compose project which need access to images in this registry. If you don't plan to use the output of `registry-creds up` to launch a task or service with `compose`, then you can leave this field empty.

Other options:

* To store credentials for multiple private registries, add additional (up to 10 total) registry names and their required details as separate keys under `registry_credentials`.

* Existing registry secrets from other regions can be included by specifying their `secrets_manager_arn` and associated `kms_key_id`. Creating or updating secrets must be done from within that region.

* If you want to encrypt the AWS Secrets Manager secret for your registry with a custom KMS Key, then add the ARN, ID or Alias of the Key in the `kms_key_id` field. Otherwise, AWS Secrets Manager will use the default key in your account.

* If you don't want to create or update an IAM Task Execution Role for these secrets, use the `--no-role` flag instead of specifying a role name.

* If you don't want to generate an output file for use with `compose` or for records purposes, use the `--no-output-file` flag.

* If you want the output file to be created in a specific directory on your machine, you can specify it with the `--output-dir <value>` flag. Otherwise, the file will be created in your working directory.

After creating the input file, run the `registry-creds up` command on the file and pass in the name of the new or existing Task Execution Role you want to use for the secrets:

The command will output the names of the resources it creates, including the name of the output file which was generated:

The output file `ecs-registry-creds_20181023T210805Z.yml` should like like this:

This file contains:

* the name of the IAM Task Execution Role with permissions for the new secrets

* the ARN of the new `credentials_parameter` created for the registry

* the list of containers the new `credentials_parameter` should be used for when running a task or service

We can now use this file with `ecs-cli compose` commands to start a task with images in our private registry.

Now that we have an output file that identifies which resources we need to use our private registry, the ECS CLI will incorporate them into our Docker Compose project when we run `ecs-cli compose`.

In the same directory (let's call it "privateImageApp"), create a docker-compose.yml file for your application:

Now run the command `ecs-cli compose up` to launch a task. The ECS CLI will automatically detect and use the newest `ecs-registry-creds` file within the current directory:

The within your new task definition `privateImageApp:1`, the container definitions for both `web` and `log` should have your "my-registry.example.com" secret as a `credentialsParameter`. The `executionRoleArn` field will be the role we created in the previous step, "myTaskExecutionRole".

Other options:

* to use an ecs-registry-creds output file from outside the current directory, you can specify it in with the `--registry-creds <value>` flag

For more information about using private registries with ECS, see [Private Registry Authentication for Tasks](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/private-auth.html).