Executar as imagens oficiais do Amazon ECR Public ou do Docker para a AWS CLI

Este tópico descreve como executar, controlar a versão e configurar a AWS CLI versão 2 no Docker usando a imagem do Amazon Elastic Container Registry Public (Amazon ECR Public) ou do Docker Hub. Para obter mais informações sobre como usar o Docker, consulte a documentação do Docker.

As imagens oficiais fornecem isolamento, portabilidade e segurança aos quais a AWS oferece suporte e mantém diretamente. Isso permite usar a AWS CLI versão 2 em um ambiente baseado em contêiner sem precisar gerenciar a instalação sozinho.

Pré-requisitos

É necessário ter o Docker instalado. Para obter instruções de instalação, consulte o site do Docker.

Para verificar a instalação do Docker, execute o seguinte comando e confirme se há uma saída.

$ docker --version
Docker version 19.03.1

Decidir entre o Amazon ECR Public e o Docker Hub

Recomendamos usar o Amazon ECR Public em vez do Docker Hub para imagens da AWS CLI. O Docker Hub tem um limite de taxa mais rígido para consumidores públicos, o que pode causar problemas de controle de utilização. Além disso, o Amazon ECR Public replica imagens em mais de uma região para fornecer sólida disponibilidade e lidar com problemas de interrupção da região.

Para obter mais informações sobre os limites de taxa do Docker Hub, consulte Understanding Docker Hub Rate Limiting (Noções básicas sobre a limitação de taxa do Docker Hub) no site do Docker.

Executar as imagens oficiais da AWS CLI versão 2

Na primeira vez que você usar o comando docker run, a imagem mais recente será baixada no computador. Cada uso subsequente do comando docker run é executado de sua cópia local.

Para executar as imagens do Docker da AWS CLI versão 2, use o comando docker run.

Amazon ECR Public

A imagem oficial do Amazon ECR Public da AWS CLI versão 2 está hospedada no Amazon ECR Public no repositório aws-cli/aws-cli.

$ docker run --rm -it public.ecr.aws/aws-cli/aws-cli command

Docker Hub

A imagem do Docker oficial da AWS CLI versão 2 está hospedada no Docker Hub no repositório amazon/aws-cli.

$ docker run --rm -it amazon/aws-cli command

É assim que o comando funciona:

• docker run --rm -it repository/name: o equivalente ao executável aws. Sempre que você executar esse comando, o Docker ativará um contêiner da imagem baixada e executará o comando aws. Por padrão, a imagem usa a versão mais recente da AWS CLI versão 2.

  Por exemplo, para chamar o comando aws --version no Docker, execute o seguinte.

  Amazon ECR Public

  $ docker run --rm -it public.ecr.aws/aws-cli/aws-cli --version
  aws-cli/2.17.20 Python/3.7.3 Linux/4.9.184-linuxkit botocore/2.4.5dev10

  Docker Hub

  $ docker run --rm -it amazon/aws-cli --version
  aws-cli/2.17.20 Python/3.7.3 Linux/4.9.184-linuxkit botocore/2.4.5dev10

• --rm: especifica a limpeza do contêiner após a saída do comando.

• -it: especifica a abertura de um pseudo-TTY com stdin. Isso permite fornecer uma entrada na AWS CLI versão 2 enquanto ela está sendo executada em um contêiner, por exemplo, usando os comandos aws configure e aws help. Ao escolher se deseja omitir -it, considere o seguinte:

  • Se você estiver executando scripts, não será necessário usar -it.

  • Se você estiver enfrentando erros em seus scripts, omitir -it de sua chamada do Docker poderá resolver o problema.

  • Se você estiver tentando canalizar a saída, -it poderá causar erros e omitir -it de sua chamada do Docker poderá resolver esse problema. Se quiser manter o sinalizador -it, mas ainda desejar canalizar a saída, desabilitar a paginação do lado do cliente que a AWS CLI usa por padrão deve resolver o problema.

Para obter mais informações sobre o comando docker run, consulte o Docker reference guide.

Observações sobre interfaces e compatibilidade com versões anteriores das imagens oficiais

• A única ferramenta compatível na imagem é a AWS CLI. Somente o executável aws deve ser executado diretamente. Por exemplo, mesmo que less e groff forem explicitamente instalados na imagem, eles não deverão ser executados diretamente fora de um comando da AWS CLI.

• O diretório de trabalho /aws é controlado pelo usuário. A imagem não será gravada nesse diretório, a menos que seja instruído pelo usuário na execução de um comando da AWS CLI.

• Não há garantias de compatibilidade com versões anteriores quando se utiliza a etiqueta mais recente. Para garantir a compatibilidade com versões anteriores, é necessário fixar uma tag <major.minor.patch> específica, pois essas tags são imutáveis. Elas só serão enviadas uma vez.

Usar versões e tags específicas

A imagem oficial da AWS CLI versão 2 oferece várias versões que podem ser usadas, começando pela versão 2.0.6. Para executar uma versão específica da AWS CLI versão 2, anexe a etiqueta apropriada ao seu comando docker run. Na primeira vez que você usar o comando docker run com uma tag, a imagem mais recente com essa tag será baixada no computador. Cada uso subsequente do comando docker run com essa etiqueta é executado de sua cópia local.

É possível usar dois tipos de etiqueta:

• latest: define a versão mais recente da AWS CLI versão 2 para a imagem. Recomendamos usar a etiqueta latest quando quiser a versão mais recente da AWS CLI versão 2. No entanto, não há garantias de compatibilidade com versões anteriores ao depender dessa etiqueta. A etiqueta latest é usada por padrão no comando docker run. Para usar explicitamente a etiqueta latest, anexe a etiqueta ao nome da imagem do contêiner.

  Amazon ECR Public

  $ docker run --rm -it public.ecr.aws/aws-cli/aws-cli:latest command

  Docker Hub

  $ docker run --rm -it amazon/aws-cli:latest command

• <major.minor.patch>: define uma versão específica da AWS CLI versão 2 para a imagem. Se você planeja usar a imagem oficial na produção, recomendamos usar uma versão específica da AWS CLI versão 2 para garantir a compatibilidade com versões anteriores. Por exemplo, para executar a versão 2.0.6, anexe a versão ao nome da imagem do contêiner.

  Amazon ECR Public

  $ docker run --rm -it public.ecr.aws/aws-cli/aws-cli:2.0.6 command

  Docker Hub

  $ docker run --rm -it amazon/aws-cli:2.0.6 command

Atualizar para a imagem oficial mais recente

Como a imagem mais recente é baixada no computador somente na primeira vez que você usa o comando docker run, é necessário extrair manualmente uma imagem atualizada. Para atualizar manualmente para a versão mais recente, recomendamos extrair a imagem marcada com a etiqueta latest. Ao extrair a imagem, você baixa a versão mais recente no computador.

Amazon ECR Public

$ docker pull public.ecr.aws/aws-cli/aws-cli:latest

Docker Hub

$ docker pull amazon/aws-cli:latest

Compartilhar arquivos de host, credenciais, variáveis de ambiente e configuração

Como a AWS CLI versão 2 é executada em um contêiner, por padrão, a CLI não pode acessar o sistema de arquivos de host, que inclui a configuração e as credenciais. Para compartilhar o sistema de arquivos de host, as credenciais e a configuração com o contêiner, monte o diretório ~/.aws do sistema de host no contêiner em /root/.aws com o sinalizador -v para o comando docker run. Isso permite que a AWS CLI versão 2 em execução no contêiner localize informações do arquivo de host.

Amazon ECR Public

Linux e macOS

$ docker run --rm -it -v ~/.aws:/root/.aws public.ecr.aws/aws-cli/aws-cli command

Prompt de comando do Windows

$ docker run --rm -it -v %userprofile%\.aws:/root/.aws public.ecr.aws/aws-cli/aws-cli command

Windows PowerShell

C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws  public.ecr.aws/aws-cli/aws-cli command

Docker Hub

Linux e macOS

$ docker run --rm -it -v ~/.aws:/root/.aws amazon/aws-cli command

Prompt de comando do Windows

$ docker run --rm -it -v %userprofile%\.aws:/root/.aws amazon/aws-cli command

Windows PowerShell

C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws  amazon/aws-cli command

Para obter mais informações sobre o sinalizador -v e a montagem, consulte o Docker reference guide.

nota

Para obter mais informações sobre os arquivos config e credentials, consulte Configurações do arquivo de configuração e credenciais na AWS CLI.

Exemplo 1: Fornecer credenciais e configuração

Neste exemplo, estamos fornecendo a configuração e as credenciais de host ao executar o comando s3 ls para listar os buckets no Amazon Simple Storage Service (Amazon S3). Os exemplos abaixo usam o local padrão para credenciais e arquivos de configuração da AWS CLI. Para usar um local diferente, altere o caminho do arquivo.

Amazon ECR Public

Linux e macOS

$ docker run --rm -it -v ~/.aws:/root/.aws public.ecr.aws/aws-cli/aws-cli s3 ls
2020-03-25 00:30:48 aws-cli-docker-demo

Prompt de comando do Windows

$ docker run --rm -it -v %userprofile%\.aws:/root/.aws public.ecr.aws/aws-cli/aws-cli s3 ls
2020-03-25 00:30:48 aws-cli-docker-demo

Windows PowerShell

C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws public.ecr.aws/aws-cli/aws-cli s3 ls

Docker Hub

Linux e macOS

$ docker run --rm -it -v ~/.aws:/root/.aws amazon/aws-cli s3 ls
2020-03-25 00:30:48 aws-cli-docker-demo

Prompt de comando do Windows

$ docker run --rm -it -v %userprofile%\.aws:/root/.aws amazon/aws-cli s3 ls
2020-03-25 00:30:48 aws-cli-docker-demo

Windows PowerShell

C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws amazon/aws-cli s3 ls

Você pode chamar variáveis de ambiente do sistema específicas usando o sinalizador -e. Para usar uma variável de ambiente, chame-a pelo nome.

Amazon ECR Public

Linux e macOS

$ docker run --rm -it -v ~/.aws:/root/.aws -e ENVVAR_NAME public.ecr.aws/aws-cli/aws-cli s3 ls
2020-03-25 00:30:48 aws-cli-docker-demo

Prompt de comando do Windows

$ docker run --rm -it -v %userprofile%\.aws:/root/.aws -e ENVVAR_NAME public.ecr.aws/aws-cli/aws-cli s3 ls
2020-03-25 00:30:48 aws-cli-docker-demo

Windows PowerShell

C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws -e ENVVAR_NAME public.ecr.aws/aws-cli/aws-cli s3 ls

Docker Hub

Linux e macOS

$ docker run --rm -it -v ~/.aws:/root/.aws -e ENVVAR_NAME amazon/aws-cli s3 ls
2020-03-25 00:30:48 aws-cli-docker-demo

Prompt de comando do Windows

$ docker run --rm -it -v %userprofile%\.aws:/root/.aws -e ENVVAR_NAME amazon/aws-cli s3 ls
2020-03-25 00:30:48 aws-cli-docker-demo

Windows PowerShell

C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws -e ENVVAR_NAME amazon/aws-cli s3 ls

Exemplo 2: Baixar um arquivo do Amazon S3 no sistema de host

Para alguns comandos da AWS CLI versão 2, é possível ler arquivos do sistema de host no contêiner ou gravar arquivos do contêiner no sistema de host.

Neste exemplo, baixamos o objeto do S3 s3://aws-cli-docker-demo/hello no sistema de arquivos local, montando o diretório de trabalho atual no diretório /aws do contêiner. Ao baixar o objeto hello no diretório /aws do contêiner, o arquivo também é salvo no diretório de trabalho atual do sistema de host.

Amazon ECR Public

Linux e macOS

$ docker run --rm -it -v ~/.aws:/root/.aws -v $(pwd):/aws public.ecr.aws/aws-cli/aws-cli s3 cp s3://aws-cli-docker-demo/hello .
download: s3://aws-cli-docker-demo/hello to ./hello

Prompt de comando do Windows

$ docker run --rm -it -v %userprofile%\.aws:/root/.aws -v %cd%:/aws public.ecr.aws/aws-cli/aws-cli s3 cp s3://aws-cli-docker-demo/hello .
download: s3://aws-cli-docker-demo/hello to ./hello

Windows PowerShell

C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws -v $pwd\aws:/aws public.ecr.aws/aws-cli/aws-cli s3 cp s3://aws-cli-docker-demo/hello .

Docker Hub

Linux e macOS

$ docker run --rm -it -v ~/.aws:/root/.aws -v $(pwd):/aws amazon/aws-cli s3 cp s3://aws-cli-docker-demo/hello .
download: s3://aws-cli-docker-demo/hello to ./hello

Prompt de comando do Windows

$ docker run --rm -it -v %userprofile%\.aws:/root/.aws -v %cd%:/aws amazon/aws-cli s3 cp s3://aws-cli-docker-demo/hello .
download: s3://aws-cli-docker-demo/hello to ./hello

Windows PowerShell

C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws -v $pwd\aws:/aws amazon/aws-cli s3 cp s3://aws-cli-docker-demo/hello .

Para confirmar que o arquivo baixado existe no sistema de arquivos local, execute o seguinte.

Linux e macOS

$ cat hello
Hello from Docker!

Windows PowerShell

$ type hello
Hello from Docker!

Exemplo 3: Usar sua variável de ambiente AWS_PROFILE

Você pode chamar variáveis de ambiente do sistema específicas usando o sinalizador -e. Chame cada variável de ambiente que gostaria de usar. Neste exemplo, estamos fornecendo credenciais de host, a configuração e a variável de ambiente AWS_PROFILE ao executar o comando s3 ls para listar os buckets no Amazon Simple Storage Service (Amazon S3).

Amazon ECR Public

Linux e macOS

$ docker run --rm -it -v ~/.aws:/root/.aws -e AWS_PROFILE public.ecr.aws/aws-cli/aws-cli s3 ls
2020-03-25 00:30:48 aws-cli-docker-demo

Prompt de comando do Windows

$ docker run --rm -it -v %userprofile%\.aws:/root/.aws -e AWS_PROFILE public.ecr.aws/aws-cli/aws-cli s3 ls
2020-03-25 00:30:48 aws-cli-docker-demo

Windows PowerShell

C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws -e AWS_PROFILE public.ecr.aws/aws-cli/aws-cli s3 ls

Docker Hub

Linux e macOS

$ docker run --rm -it -v ~/.aws:/root/.aws -e AWS_PROFILE amazon/aws-cli s3 ls
2020-03-25 00:30:48 aws-cli-docker-demo

Prompt de comando do Windows

$ docker run --rm -it -v %userprofile%\.aws:/root/.aws -e AWS_PROFILE amazon/aws-cli s3 ls
2020-03-25 00:30:48 aws-cli-docker-demo

Windows PowerShell

C:\> docker run --rm -it -v $env:userprofile\.aws:/root/.aws -e AWS_PROFILE amazon/aws-cli s3 ls

Reduzir o comando de execução do Docker

Para reduzir o comando docker run, sugerimos usar a capacidade do sistema operacional para criar um symbolic link (symlink) ou alias no Linux e no macOS ou doskey no Windows. Para definir o alias aws, é possível executar um dos comandos a seguir.

• Para obter acesso básico a comandos aws, execute o seguinte.

  Amazon ECR Public

  Linux e macOS

  $ alias aws='docker run --rm -it public.ecr.aws/aws-cli/aws-cli'

  Prompt de comando do Windows

  C:\> doskey aws=docker run --rm -it public.ecr.aws/aws-cli/aws-cli $*

  Windows PowerShell

  C:\> Function AWSCLI {docker run --rm -it public.ecr.aws/aws-cli/aws-cli $args}
  Set-Alias -Name aws -Value AWSCLI

  Docker Hub

  Linux e macOS

  $ alias aws='docker run --rm -it amazon/aws-cli'

  Prompt de comando do Windows

  C:\> doskey aws=docker run --rm -it amazon/aws-cli $*

  Windows PowerShell

  C:\> Function AWSCLI {docker run --rm -it amazon/aws-cli $args}
  Set-Alias -Name aws -Value AWSCLI

• Para obter acesso ao sistema de arquivos de host e às definições de configuração ao usar comandos aws, execute o indicado a seguir.

  Amazon ECR Public

  Linux e macOS

  $ alias aws='docker run --rm -it -v ~/.aws:/root/.aws -v $(pwd):/aws public.ecr.aws/aws-cli/aws-cli'

  Prompt de comando do Windows

  C:\> doskey aws=docker run --rm -it -v %userprofile%\.aws:/root/.aws -v %cd%:/aws public.ecr.aws/aws-cli/aws-cli $*

  Windows PowerShell

  C:\> Function AWSCLI {docker run --rm -it -v $env:userprofile\.aws:/root/.aws -v $pwd\aws:/aws public.ecr.aws/aws-cli/aws-cli $args}
  Set-Alias -Name aws -Value AWSCLI

  Docker Hub

  Linux e macOS

  $ alias aws='docker run --rm -it -v ~/.aws:/root/.aws -v $(pwd):/aws amazon/aws-cli'

  Prompt de comando do Windows

  C:\> doskey aws=docker run --rm -it -v %userprofile%\.aws:/root/.aws -v %cd%:/aws amazon/aws-cli $*

  Windows PowerShell

  C:\> Function AWSCLI {docker run --rm -it -v $env:userprofile\.aws:/root/.aws -v $pwd\aws:/aws amazon/aws-cli $args}
  Set-Alias -Name aws -Value AWSCLI

• Para atribuir uma versão específica para usar no alias aws, anexe a etiqueta de versão.

  Amazon ECR Public

  Linux e macOS

  $ alias aws='docker run --rm -it -v ~/.aws:/root/.aws -v $(pwd):/aws public.ecr.aws/aws-cli/aws-cli:2.0.6'

  Prompt de comando do Windows

  C:\> doskey aws=docker run --rm -it -v %userprofile%\.aws:/root/.aws -v %cd%:/aws public.ecr.aws/aws-cli/aws-cli:2.0.6 $*

  Windows PowerShell

  C:\> Function AWSCLI {docker run --rm -it -v $env:userprofile\.aws:/root/.aws -v $pwd\aws:/aws public.ecr.aws/aws-cli/aws-cli:2.0.6 $args}
  Set-Alias -Name aws -Value AWSCLI

  Docker Hub

  Linux e macOS

  $ alias aws='docker run --rm -it -v ~/.aws:/root/.aws -v $(pwd):/aws amazon/aws-cli:2.0.6'

  Prompt de comando do Windows

  C:\> doskey aws=docker run --rm -it -v %userprofile%\.aws:/root/.aws -v %cd%:/aws amazon/aws-cli:2.0.6 $*

  Windows PowerShell

  C:\> Function AWSCLI {docker run --rm -it -v $env:userprofile\.aws:/root/.aws -v $pwd\aws:/aws amazon/aws-cli:2.0.6 $args}
  Set-Alias -Name aws -Value AWSCLI

Depois de definir o alias, é possível executar a AWS CLI versão 2 de dentro de um contêiner como se ela estivesse instalada no sistema do host.

$ aws --version
aws-cli/2.17.20 Python/3.7.3 Linux/4.9.184-linuxkit botocore/2.4.5dev10