# 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](https://docs.docker.com/).
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.
**Topics**
+ [Pré-requisitos](#cliv2-docker-prereq)
+ [Decidir entre o Amazon ECR Public e o Docker Hub](#cliv2-docker-versus)
+ [Executar as imagens oficiais da AWS CLI versão 2](#cliv2-docker-install)
+ [Observações sobre interfaces e compatibilidade com versões anteriores das imagens oficiais](#cliv2-docker-install-notes)
+ [Usar versões e tags específicas](#cliv2-docker-upgrade)
+ [Atualizar para a imagem oficial mais recente](#cliv2-docker-update)
+ [Compartilhar arquivos de host, credenciais, variáveis de ambiente e configuração](#cliv2-docker-share-files)
+ [Reduzir o comando de execução do Docker](#cliv2-docker-aliases)
## Pré-requisitos
É necessário ter o Docker instalado. Para obter instruções de instalação, consulte o [site do Docker](https://docs.docker.com/install/).
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](https://www.docker.com/increase-rate-limits/) (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`](https://gallery.ecr.aws/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.27.41 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.27.41 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](cli-usage-pagination.md#cli-usage-pagination-clientside) 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](https://docs.docker.com/engine/reference/run/).
## 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 `` 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
```
------
+ ``: 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](https://docs.docker.com/storage/volumes/).
**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](cli-configure-files.md).
### 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\$1PROFILE
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\$1PROFILE* 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 [https://www.linux.com/topic/desktop/understanding-linux-links/](https://www.linux.com/topic/desktop/understanding-linux-links/) (symlink) ou [https://www.linux.com/topic/desktop/aliases-diy-shell-commands/](https://www.linux.com/topic/desktop/aliases-diy-shell-commands/) no Linux e no macOS ou [https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/doskey](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/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.27.41 Python/3.7.3 Linux/4.9.184-linuxkit botocore/2.4.5dev10
```