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. Ela também fornece informações sobre como extrair imagens com a ferramenta crictl se você estiver resolver problemas no Google Kubernetes Engine.

Para informações sobre como implantar nos ambientes de execução do Google Cloud, consulte Implantar no 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:

Extrair 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 usar o Docker ou outro cliente de terceiros com um repositório Docker. Esta seção fornece um breve resumo do que você precisa para autenticar com êxito. Para instruções detalhadas, consulte Como configurar a autenticação para o Docker.

Usar um auxiliar de credenciais

Para o auxiliar de credenciais da CLI gcloud ou auxiliar de credenciais independente, a 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: cat %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 adicioná-lo. 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 uma conta de serviço impersonation e depois faz a autenticação 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 personificar uma conta de serviço, poderá ative a conta de serviço na sessão da CLI gcloud e consiga 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 docker login kubectl.

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 para um repositório padrão do Docker, marque-a com o o nome do repositório e enviar a imagem.

Se a imutabilidade de tags estiver ativada no repositório Docker do Artifact Registry, uma tag precisa sempre fazer referência ao mesmo resumo de imagem no repositório. Não é possível usar a tag em outra versão da mesma imagem enviada ao repositório de dados. 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 o Artifact Registry, ele só 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 regional ou multirregional local do repositório em que a imagem são armazenados.
- PROJECT-ID é o ID do projeto do console do Google Cloud. Se o ID do projeto contiver 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 ou ID da imagem local 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 de 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 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 o cliente Docker, Verifique se o nome do host de destino está no seu 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 regional ou multirregional local 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.
- 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 pesquisa repositórios upstream para a imagem solicitada. Se você solicitar uma disponível em mais de um repositório upstream, O Artifact Registry escolhe um repositório upstream para usar com base no as 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 pesquisa primeiro.

Tanto secondary-repo1 quanto 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.

Extraindo imagens com `crictl`

A crictl é uma ferramenta de linha de comando útil para que os desenvolvedores de ambientes de execução de CRI depurem o ambiente de execução sem precisar configurar os 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 nó com o problema que você está solucionando.

conseguir 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 a configuração de registros de imagem crictl

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

Extraindo imagens com crictl

A seguir

Extraindo imagens com `crictl`