Enviar e extrair imagens

Nesta página, descrevemos 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 solucionando problemas no Google Kubernetes Engine.

Para informações sobre como implantar em 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 access 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)
Marque e envie imagens: Gravador do Artifact Registry (roles/artifactregistry.writer)

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Talvez você também consiga receber as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

Como autenticar em um repositório

Faça a autenticação em repositórios sempre que usar o Docker ou outro cliente de terceiros com um repositório do Docker. Nesta seção, você vê um resumo rápido do que é necessário para autenticar com êxito. Para instruções detalhadas, consulte Como configurar a autenticação para o Docker.

Como usar um auxiliar de credenciais

Para o auxiliar de credenciais da CLI gcloud ou , 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, você adiciona 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 configurados do Docker do Artifact Registry. Os nomes de host terminam em -docker.pkg.dev. O exemplo a seguir mostra alguns hosts configurados para o auxiliar de credencial 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 auxiliar de credencial novamente para adicioná-lo. Por exemplo, o comando a seguir adiciona us-east1-docker.pkg.dev.

Auxiliar de credenciais da CLI gcloud:

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

Auxiliar de credenciais independente

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

usar um token de acesso;

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

O exemplo a seguir gera um token de acesso usando a representação da conta de serviço e, em seguida, faz a autenticação no Artifact Registry. É necessário ter permissões no papel Criador de tokens da conta de serviço (roles/iam.serviceAccountTokenCreator) para gerar um token dessa maneira.

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 sessão da CLI gcloud e receba um token. Para mais detalhes, consulte as instruções sobre como configurar a autenticação do token de acesso.

Como usar uma chave de conta de serviço

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

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

Linux

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

Windows

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

Veja mais detalhes nas instruções de configuração da 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 a imutabilidade de tags estiver ativada no repositório Docker do Artifact Registry, uma tag precisará 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. Para mais informações sobre resumos de imagens, tags e imutabilidade de tags, consulte Versões de imagens de contêiner.

Para imagens grandes, os seguintes limites se aplicam:

Tempo de upload: Se você autenticar no Artifact Registry usando um token de acesso, o token só será válido por 60 minutos. Se você espera que o tempo de upload exceda 60 minutos, use outro método de autenticação.
Tamanho da imagem: O tamanho máximo do artefato é 5 TB.; O Artifact Registry não é compatível com uploads em partes do Docker. Algumas ferramentas são compatíveis com 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, por exemplo, us-east1 ou us.
- 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-east1
- 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-east1-docker.pkg.dev/my-project/my-repo/test-image
```
Observação :o nome da imagem que você armazenará no repositório pode ser diferente do nome da imagem na 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 aplicará a tag latest padrão.

Se a configuração de tags de imagem imutável estiver ativada (pré-lançamento), 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 no 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-east1-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-east1-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 o 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 visualizar 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-east1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:45  2019-04-10T15:08:45
  us-east1-docker.pkg.dev/my-project/my-repo/my-image  sha256:238...  2019-04-10T17:23:53  2019-04-10T17:23:53
  us-east1-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 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, por exemplo, us-east1 ou us.
- 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 ver 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-east1
- 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-east1-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, o repositório remoto fará o download e armazenará em cache a imagem da origem upstream se não houver uma cópia em cache.

Se você solicitar uma imagem de um repositório virtual, o Artifact Registry vai pesquisar repositórios upstream para a imagem solicitada. Se você solicitar uma versão disponível em mais de um repositório upstream, o Artifact Registry 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. Portanto, o repositório virtual sempre o 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 vai pesquisar esses repositórios em seguida. Como ambos têm o mesmo valor de prioridade, o Artifact Registry pode optar por 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 veiculará um artefato armazenado se nenhum dos outros repositórios upstream o tiver.

Extraindo imagens com `crictl`

crictl é uma ferramenta de linha de comando útil para desenvolvedores de ambiente de execução de CRI depurarem 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 do containerd, será possível extrair imagens do Artifact Registry usando crictl.

Como crictl é principalmente uma ferramenta de solução de problemas, alguns comandos do Docker, como envio ou 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ó com o problema em questão.

Consiga 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.
Saiba como usar crictl para extrair imagens de repositórios particulares do Artifact Registry.
Saiba mais sobre como configurar registros de imagem crictl

Enviar e extrair imagens

Antes de começar

Funções exigidas

Como autenticar em um repositório

Como 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`