Configuração de instâncias de contêiner do Amazon ECS para imagens do Docker privadas

O agente de contêiner do Amazon ECS pode realizar a autenticação com registros privados usando a autenticação básica. Ao ativar a autenticação de registro privado, você pode utilizar imagens de docker privadas nas definições de tarefa. Esse recurso só é compatível com tarefas que usam o tipo de inicialização do EC2.

Outro método para habilitar a autenticação de registro privado usa o AWS Secrets Manager para armazenar suas credenciais de registro privado de forma segura e, então, referenciá-las em sua definição de contêiner. Isso permite que suas tarefas usem imagens de repositórios privados. Esse método oferece suporte a tarefas que usam os tipos de inicialização do EC2 ou do Fargate. Para ter mais informações, consulte Uso de imagens de contêiner que não são da AWS no Amazon ECS.

O agente de contêiner do Amazon ECS procura duas variáveis de ambiente ao ser iniciado:

ECS_ENGINE_AUTH_TYPE, que especifica o tipo de dados de autenticação que está sendo enviado.
ECS_ENGINE_AUTH_DATA, que contém as credenciais de autenticação em si.

As variantes do Linux da AMI otimizada para Amazon ECS procuram essas variáveis no arquivo /etc/ecs/ecs.config quando a instância de contêiner é inicializada, e cada vez que o serviço é iniciado (com o comando sudo start ecs). As AMIs que não são otimizadas para Amazon ECS devem armazenar essas variáveis de ambiente em um arquivo e transmiti-las com a opção --env-file path_to_env_file para o comando docker run que inicia o agente de contêiner.

Importante

Não recomendamos que você injete essas variáveis de ambiente de autenticação na inicialização da instância com os dados de usuário do Amazon EC2 ou as transmita com a opção --env para o comando docker run. Esses métodos não são adequados para dados confidenciais, como credenciais de autenticação. Para obter informações sobre como adicionar credenciais de autenticação com segurança às instâncias de contêiner, consulte Armazenamento da configuração da instância de contêiner do Amazon ECS no Amazon S3.

Formatos de autenticação

Há dois formatos disponíveis para a autenticação de registro privado, dockercfg e docker.

Formato de autenticação dockercfg

O formato dockercfg usa as informações de autenticação armazenadas no arquivo de configuração criado quando você executa o comando docker login. É possível criar esse arquivo executando docker login no sistema local e inserindo o nome de usuário, a senha e o endereço de e-mail do registro. Também é possível fazer login em uma instância de contêiner e executar o comando daí. Dependendo de sua versão do Docker, esse arquivo é salvo como ~/.dockercfg ou ~/.docker/config.json.


cat ~/.docker/config.json

Saída:

{
  "auths": {
    "https://index.docker.io/v1/": {
      "auth": "zq212MzEXAMPLE7o6T25Dk0i"
    }
  }
}

Importante

As versões mais recentes do Docker criam um arquivo de configuração como mostrado acima, com um objeto auths externo. O agente do Amazon ECS oferece suporte somente aos dados de autenticação dockercfg que estão no formato abaixo, sem o objeto auths. Se tiver o utilitário jq instalado, será possível extrair esses dados com o comando a seguir: cat ~/.docker/config.json | jq .auths


cat ~/.docker/config.json | jq .auths

Saída:

{
  "https://index.docker.io/v1/": {
    "auth": "zq212MzEXAMPLE7o6T25Dk0i",
    "email": "email@example.com"
  }
}

No exemplo acima, as variáveis de ambiente a seguir devem ser adicionadas ao arquivo de variável de ambiente (/etc/ecs/ecs.config para a AMI otimizada para o Amazon ECS) que o agente de contêiner do Amazon ECS carrega no runtime. Se você não estiver usando a AMI otimizada para Amazon ECS e estiver iniciando o agente manualmente com docker run, especifique o arquivo de variável de ambiente com a opção --env-file path_to_env_file ao iniciar o agente.


ECS_ENGINE_AUTH_TYPE=dockercfg
ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"auth":"zq212MzEXAMPLE7o6T25Dk0i","email":"email@example.com"}}

É possível configurar vários registros privados com a sintaxe a seguir:


ECS_ENGINE_AUTH_TYPE=dockercfg
ECS_ENGINE_AUTH_DATA={"repo.example-01.com":{"auth":"zq212MzEXAMPLE7o6T25Dk0i","email":"email@example-01.com"},"repo.example-02.com":{"auth":"fQ172MzEXAMPLEoF7225DU0j","email":"email@example-02.com"}}

Formato de autenticação docker

O formato docker usa uma representação JSON do servidor de registro com que o agente deve se autenticar. Ele também inclui os parâmetros de autenticação exigidos por esse registro (como nome de usuário, senha e endereço de e-mail dessa conta). Para uma conta do Docker Hub, a representação JSON terá a seguinte aparência:


{
  "https://index.docker.io/v1/": {
    "username": "my_name",
    "password": "my_password",
    "email": "email@example.com"
  }
}

Nesse exemplo as variáveis de ambiente a seguir devem ser adicionadas ao arquivo de variável de ambiente (/etc/ecs/ecs.config para a AMI otimizada para o Amazon ECS) que o agente de contêiner do Amazon ECS carrega no runtime. Se você não estiver usando a AMI otimizada para Amazon ECS e estiver iniciando o agente manualmente com docker run, especifique o arquivo de variável de ambiente com a opção --env-file path_to_env_file ao iniciar o agente.


ECS_ENGINE_AUTH_TYPE=docker
ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"username":"my_name","password":"my_password","email":"email@example.com"}}

É possível configurar vários registros privados com a sintaxe a seguir:


ECS_ENGINE_AUTH_TYPE=docker
ECS_ENGINE_AUTH_DATA={"repo.example-01.com":{"username":"my_name","password":"my_password","email":"email@example-01.com"},"repo.example-02.com":{"username":"another_name","password":"another_password","email":"email@example-02.com"}}

Procedimento

Use o procedimento a seguir para ativar registros privados para as instâncias de contêiner.

Para habilitar registros privados na AMI otimizada para Amazon ECS

Faça login em sua instância de contêiner usando SSH.

Abra o arquivo /etc/ecs/ecs.config e adicione os valores ECS_ENGINE_AUTH_TYPE e ECS_ENGINE_AUTH_DATA para o seu registro e conta:


sudo vi /etc/ecs/ecs.config

Este exemplo autentica uma conta de usuário do Docker Hub:


ECS_ENGINE_AUTH_TYPE=docker
ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"username":"my_name","password":"my_password","email":"email@example.com"}}

Verifique se o seu agente usa a variável de ambiente ECS_DATADIR para salvar seu estado:
```
docker inspect ecs-agent | grep ECS_DATADIR
```
Saída:
```
"ECS_DATADIR=/data",
```
Importante
Se o comando anterior não retornar a variável de ambiente ECS_DATADIR, você deverá interromper todas as tarefas em execução nessa instância de contêiner antes de interromper o agente. Agentes mais novos com a variável de ambiente ECS_DATADIR salvam seu estado, e você pode interrompê-los e iniciá-los enquanto as tarefas são executadas sem problemas. Para ter mais informações, consulte Atualizar o agente de contêiner do Amazon ECS.
Interrompa o serviço ecs:
```
sudo stop ecs
```
Saída:
```
ecs stop/waiting
```
Reinicie o serviço ecs.
- Para a AMI do Amazon Linux 2 otimizada para o Amazon ECS:
```
sudo systemctl restart ecs
```
- Para a AMI do Amazon Linux otimizada para o Amazon ECS:
```
sudo stop ecs && sudo start ecs
```
(Opcional) É possível verificar se o agente está em execução e consultar algumas informações sobre sua nova instância de contêiner consultando a operação da API de introspecção do agente. Para ter mais informações, consulte Introspecção de contêiner do Amazon ECS.
```
curl http://localhost:51678/v1/metadata
```

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Instalar o agente de contêiner do Amazon ECS

Limpeza de tarefas e de imagens