Esta página foi traduzida pela API Cloud Translation.

Enviar e extrair imagens

Esta página descreve como enviar e extrair imagens de contêiner com o Docker. Ele também fornece informações sobre como extrair imagens com a ferramenta crictl se você estiver solucionando problemas no Google Kubernetes Engine.

Para mais informações sobre a implantação em ambientes de execução Google Cloud , consulte Implantar em Google Cloud.

Para instruções sobre como listar, incluir tags e excluir imagens, consulte Como gerenciar imagens.

Antes de começar

Se não existir um repositório de destino, crie um novo repositório.
É preciso ter pelo menos o acesso de Gravador do Artifact Registry ao repositório.
Instale o Docker se ele ainda não estiver instalado.

Funções exigidas

Para receber as permissões necessárias para enviar e extrair imagens, peça ao administrador para conceder a você os seguintes papéis do IAM no repositório:

Solicitar imagens: Leitor do Artifact Registry (roles/artifactregistry.reader)
Marcar e enviar imagens: Gravador do Artifact Registry (roles/artifactregistry.writer)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Como autenticar em um repositório

É necessário fazer a autenticação nos repositórios sempre que você usar o Docker ou outro cliente de terceiros com um repositório do Docker. Esta seção fornece um resumo rápido do que você precisa para fazer a autenticação. Para instruções detalhadas, consulte Como configurar a autenticação para o Docker.

Usar um auxiliar de credenciais

Para o auxiliar de credenciais da gcloud CLI ou o auxiliar de credenciais independente, os hosts do Artifact Registry que você usa precisam estar no arquivo de configuração do Docker.

O Artifact Registry não adiciona automaticamente todos os hosts de registro ao arquivo de configuração do Docker. O tempo de resposta do Docker é significativamente mais lento quando há um grande número de registros configurados. Para minimizar o número de registros no arquivo de configuração, adicione os hosts necessários ao arquivo.

Para confirmar quais hosts estão configurados, execute o seguinte comando para exibir o conteúdo do arquivo de configuração:

Linux: cat ~/.docker/config.json
Windows: type %USERPROFILE%\.docker\config.json

A seção credHelpers lista os hosts do Docker do Artifact Registry configurados. Os nomes de host terminam em -docker.pkg.dev. O exemplo a seguir mostra alguns hosts configurados para o auxiliar de credenciais da CLI gcloud.

"credHelpers": {
  "asia.gcr.io": "gcloud",
  "eu.gcr.io": "gcloud",
  "gcr.io": "gcloud",
  "marketplace.gcr.io": "gcloud",
  "northamerica-northeast1-docker.pkg.dev": "gcloud",
  "us-central1-docker.pkg.dev": "gcloud",
  "us-east1-docker.pkg.dev": "gcloud",
  "us.gcr.io": "gcloud"
}

Se um host que você quer usar não estiver na lista, execute o assistente de credenciais novamente para adicionar o host. Por exemplo, o comando a seguir adiciona us-west1-docker.pkg.dev.

Auxiliar de credenciais da CLI gcloud:

gcloud auth configure-docker us-west1-docker.pkg.dev

Auxiliar de credenciais independente

docker-credential-gcr configure-docker us-west1-docker.pkg.dev

Usar um token de acesso

Para a autenticação de token de acesso, você gera um token e o usa como uma senha com o comando docker login. Os tokens são válidos por 60 minutos. Portanto, você precisa fazer a autenticação pouco antes de marcar, enviar ou extrair imagens.

O exemplo a seguir gera um token de acesso usando a impersonação de conta de serviço e, em seguida, se autentica no Artifact Registry. Você precisa ter permissões no papel de Criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) para gerar um token dessa forma.

Linux

gcloud auth print-access-token \
  --impersonate-service-account  ACCOUNT | docker login \
  -u oauth2accesstoken \
  --password-stdin https://LOCATION-docker.pkg.dev

Windows

gcloud auth print-access-token \
--impersonate-service-account  ACCOUNT

ya29.8QEQIfY_...

docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
https://LOCATION-docker.pkg.dev

Se você não tiver permissões para representar uma conta de serviço, ative a conta de serviço na sua sessão da CLI gcloud e receba um token. Para saber mais, consulte as instruções para configurar a autenticação de token de acesso.

Como usar uma chave de conta de serviço

Para uma chave de conta de serviço, use a chave como uma senha com o comando docker login.

Por exemplo, o comando a seguir usa a chave de conta de serviço codificada em base64 no arquivo key.json para autenticar em us-west1-docker.pkg.dev.

Linux

cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-west1-docker.pkg.dev

Windows

docker login -u _json_key_base64 --password-stdin https://us-west1-docker.pkg.dev < key.json

Para saber mais, consulte as instruções para configurar a autenticação da chave da conta de serviço.

Como enviar uma imagem

Modos de repositório: padrão

Para enviar uma imagem local a um repositório padrão do Docker, marque-a com o nome do repositório e envie a imagem.

Se o repositório do Docker do Artifact Registry tiver a imutabilidade de tag ativada, uma tag sempre vai precisar referenciar o mesmo resumo de imagem no repositório. Não é possível usar a tag em outra versão da mesma imagem que você envia para o repositório. Para mais informações sobre resumos de imagem, tags e imutabilidade de tags, consulte Versões de imagem de contêiner.

Para imagens grandes, os seguintes limites se aplicam:

Tempo de upload: Se você usar um token de acesso para autenticar no Artifact Registry, ele só vai ser válido por 60 minutos. Se você acha que o tempo de upload vai ser maior que 60 minutos, use um método de autenticação diferente.
Tamanho da imagem: O tamanho máximo do artefato é de 5 TB.; O Artifact Registry não oferece suporte a uploads em partes do Docker. Algumas ferramentas suportam o upload de imagens grandes com uploads em partes ou um único upload monolítico. Use uploads monolíticos para enviar imagens ao Artifact Registry.

Como marcar a imagem local

Verifique se você está autenticado no repositório.
Determine o nome da imagem. O formato do nome completo de uma imagem é:
```
LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
```
Substitua os seguintes valores:
- LOCATION é o local regional ou multirregional do repositório em que a imagem está armazenada.
- PROJECT-ID é o ID do projeto do console do Google Cloud. Caso o ID do projeto contenha dois pontos (:), consulte Projetos com escopo de domínio.
- REPOSITORY é o nome do repositório em que a imagem está armazenada.
- IMAGE é o nome da imagem. Ele pode ser diferente do nome local da imagem.
Por exemplo, considere uma imagem com as seguintes características:
- Local do repositório: us-west1
- Nome do repositório: my-repo
- ID do projeto: my-project
- Nome da imagem local: my-image
- Nome da imagem de destino: test-image
O nome da imagem deste exemplo é:
```
us-west1-docker.pkg.dev/my-project/my-repo/test-image
```
Observação: o nome da imagem que você vai armazenar no repositório pode ser diferente do nome da imagem na sua máquina local.

Para detalhes sobre o formato do nome da imagem, incluindo o gerenciamento de projetos com escopo de domínio, consulte Nomes de repositório e imagens.
Marque a imagem local com o nome do repositório.
```
docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
```
Substitua SOURCE-IMAGE pelo nome da imagem local ou pelo ID da imagem e TAG pela tag. Se você não especificar uma tag, o Docker vai aplicar a tag padrão latest.

Se a configuração de tags de imagem imutáveis estiver ativada, as tags precisarão ser exclusivas para cada versão da imagem, incluindo a tag latest. Não é possível enviar uma imagem para o repositório se a tag já estiver sendo usada por outra versão da mesma imagem no repositório. Para verificar se a configuração está ativada para o repositório, execute o comando:
```
gcloud artifacts repositories describe REPOSITORY \
    --project=PROJECT-ID \
    --location=LOCATION
```
No exemplo de imagem da etapa anterior, use o comando a seguir se a imagem local my-image estiver no diretório atual:
```
docker tag my-image us-west1-docker.pkg.dev/my-project/my-repo/test-image
```
Se você quiser aplicar uma tag específica, use o comando:
```
docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
```
Para usar a tag staging com a imagem de exemplo, adicione :staging ao comando:
```
docker tag my-image us-west1-docker.pkg.dev/my-project/my-repo/test-image:staging
```

Envie a imagem marcada para o Artifact Registry

Verifique se você está autenticado no repositório.

Se você usou gcloud auth configure-docker ou docker-credential-gcr configure-docker para configurar seu cliente do Docker, verifique se o nome do host de destino está no arquivo de configuração do Docker.
Envie a imagem marcada com o comando:
```
docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
```
Este comando envia a imagem que tem a tag latest. Se você quiser enviar uma imagem com uma tag diferente, use o comando:
```
docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
```

Quando você envia uma imagem, ela é armazenada no repositório especificado.

Depois de enviar a imagem, você pode:

Acesse o console do Google Cloud para conferir a imagem.

Execute o comando gcloud para visualizar as tags da imagem e o resumo gerado automaticamente:

gcloud artifacts docker images list \
LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE [--include-tags]

A saída de exemplo a seguir mostra resumos de imagens truncados, mas o comando sempre retorna o resumo de imagem completo.

 IMAGE                                                 DIGEST         CREATE_TIME          UPDATE_TIME
  us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:45  2019-04-10T15:08:45
  us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:238...  2019-04-10T17:23:53  2019-04-10T17:23:53
  us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:46  2019-04-10T15:08:46

Como extrair imagens com o Docker

Modos de repositório: padrão, remoto, virtual

Verifique se você está autenticado no repositório.

Se você usou gcloud auth configure-docker ou docker-credential-gcr configure-docker para configurar seu cliente do Docker, verifique se o nome do host de destino está no arquivo de configuração do Docker.
Para extrair de um repositório, use o comando:
```
docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
```
ou
```
docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST
```
Substitua os seguintes valores:
- LOCATION é o local regional ou multirregional do repositório em que a imagem está armazenada.
- PROJECT é o ID do projeto do console do Google Cloud. Caso o ID do projeto contenha dois pontos (:), consulte Projetos com escopo de domínio.
- PROJECT é o ID do projeto do console do Google Cloud.
- REPOSITORY é o nome do repositório em que a imagem está armazenada.
- IMAGE é o nome da imagem no repositório.
- TAG é a tag da versão de imagem que você quer extrair.
- IMAGE-DIGEST é o valor de hash sha256 do conteúdo da imagem. Cada versão de uma imagem tem um resumo de imagem exclusivo. No console do Google Cloud, clique na imagem específica para conferir os metadados dela. O resumo é listado como Resumo da imagem.
Por exemplo, considere uma imagem com as seguintes características:
- Local do repositório: us-west1
- Nome do repositório: my-repo
- ID do projeto: my-project
- Nome da imagem: test-image
- Tag: staging
Use este comando para extrair a imagem:
```
docker pull us-west1-docker.pkg.dev/my-project/my-repo/test-image:staging
```

O Docker faz o download da imagem especificada.

Se você solicitar uma imagem de um repositório remoto, ele fará o download e armazenará em cache a imagem da origem upstream se uma cópia em cache não existir.

Se você solicitar uma imagem de um repositório virtual, o Artifact Registry vai procurar a imagem solicitada nos repositórios upstream. Se você solicitar uma versão disponível em mais de um repositório upstream, o Artifact Registry vai escolher um repositório upstream para usar com base nas configurações de prioridade definidas para o repositório virtual.

Por exemplo, considere um repositório virtual com as seguintes configurações de prioridade para repositórios upstream:

main-repo: prioridade definida como 100
secondary-repo1: prioridade definida como 80.
secondary-repo2: prioridade definida como 80.
test-repo: prioridade definida como 20.

main-repo tem o valor de prioridade mais alto, então o repositório virtual sempre o pesquisa primeiro.

secondary-repo1 e secondary-repo2 têm prioridade definida como 80. Se uma imagem solicitada não estiver disponível em main-repo, o Artifact Registry procurará esses repositórios em seguida. Como elas têm o mesmo valor de prioridade, o Artifact Registry pode escolher exibir uma imagem de qualquer um dos repositórios se a versão estiver disponível em ambos.

test-repo tem o menor valor de prioridade e vai servir um artefato armazenado se nenhum dos outros repositórios upstream tiver.

Como extrair imagens com `crictl`

O crictl é uma ferramenta de linha de comando útil para que os desenvolvedores de ambiente de execução do CRI depurem o ambiente de execução sem precisar configurar componentes do Kubernetes. Se os nós do Google Kubernetes Engine usarem um ambiente de execução containerd, será possível extrair imagens do Artifact Registry usando crictl.

Como o crictl é principalmente uma ferramenta de solução de problemas, alguns comandos do Docker, como o envio ou a inclusão de tags em imagens, não estão disponíveis.

Para extrair uma imagem do Artifact Registry:

No Console do Google Cloud, acesse a página Instâncias de VMs.

Acessar instâncias de VM
Conecte-se por SSH ao nó que você está solucionando.

Receber um token de acesso para autenticação com o repositório.

curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" -H "Metadata-Flavor: Google"

Extraia a imagem usando crictl pull --creds e o valor access_token

crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST

A saída será assim:

Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5

A seguir

Saiba mais sobre como gerenciar tags e excluir imagens.
Saiba mais sobre como executar contêineres no Compute Engine.
Use crictl para depurar nós do Kubernetes
Aprenda a usar crictl para extrair imagens de repositórios particulares do Artifact Registry.
Saiba mais sobre como configurar crictl registros de imagem.

Enviar e extrair imagens

Antes de começar

Funções exigidas

Como autenticar em um repositório

Usar um auxiliar de credenciais

Usar um token de acesso

Linux

Windows

Como usar uma chave de conta de serviço

Linux

Windows

Como enviar uma imagem

Como marcar a imagem local

Envie a imagem marcada para o Artifact Registry

Como extrair imagens com o Docker

Como extrair imagens com crictl

A seguir

Como extrair imagens com `crictl`