Como enviar e extrair imagens

Enviar (fazer upload) e extrair (fazer o download) imagens são duas das tarefas mais comuns do Container Registry. Este documento se concentra em enviar e extrair imagens com o Docker.

Se você estiver usando o Cloud Build, consulte a documentação do Cloud Build para informações sobre como criar e enviar contêineres para o Container Registry.

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

Antes de começar

Certifique-se de que você:

  1. ativou o Container Registry no projeto;

  2. instalou e configurou o Docker;

Como adicionar um registro

É possível adicionar os seguintes registros do Container Registry a um projeto:

Nome do host Local de armazenamento
gcr.io Armazena imagens em data centers nos Estados Unidos
asia.gcr.io Armazena imagens em data centers na Ásia
eu.gcr.io Armazena imagens em data centers dentro de estados-membros da União Europeia
us.gcr.io Armazena imagens em data centers nos Estados Unidos

O primeiro envio de imagem para um nome de host aciona a criação do registro em um projeto e do bucket de armazenamento do Cloud Storage correspondente. Esse envio inicial exige permissões em todo o projeto para criar buckets de armazenamento.

Depois que um host de registro for criado no projeto, será possível configurar permissões no bucket de armazenamento para controlar o acesso a imagens no registro.

Para adicionar um registro e configurar permissões:

  1. Verifique se você tem as permissões necessárias. Você precisa ter a função Administrador do Storage (roles/storage.admin) ou uma função personalizada ou predefinida com as mesmas permissões.

    Para instruções sobre como conceder a função de administrador do Storage no nível do projeto, consulte a documentação do IAM.

  2. Envie uma imagem inicial para o host. Por exemplo, os seguintes comandos:

    • Extrair a imagem busybox do Docker Hub
    • Marque a imagem com o caminho de destino no Container Registry, incluindo o host de registro gcr.io e o ID do projeto my-project
    • Enviar a imagem para o registro
    docker pull busybox
docker tag busybox gcr.io/my-project/busybox
docker push gcr.io/my-project/busybox

O Container Registry adiciona o registro ao seu projeto, cria um bucket de armazenamento para o registro e armazena a imagem.

Agora é possível configurar o controle de acesso no bucket de armazenamento do registro para conceder acesso a outros usuários.

Como enviar uma imagem para um registro

Para enviar qualquer imagem local ao Container Registry usando o Docker ou outra ferramenta de terceiros, primeiro marque-a com o nome do registro e, em seguida, envie a imagem.

Os fatores a seguir podem afetar os uploads de imagens grandes:

Tempo de upload
Qualquer solicitação enviada ao Container Registry tem um tempo limite de duas horas. Se você autentica no Container Registry usando um token de acesso, ele expira após 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 Container Registry usa o Cloud Storage para o armazenamento subjacente de todos os registros. As cotas e limites do Cloud Storage se aplicam a cada registro, incluindo o tamanho máximo de 5 TB para um objeto no armazenamento.
O Container 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 Container Registry.

Permissões necessárias

O push de uma imagem exige um dos seguintes papéis do Cloud Storage ou um papel com as mesmas permissões:

Como enviar a primeira imagem para um registro no projeto

Função: administrador do Storage (roles/storage.admin) no nível do projeto do Google Cloud. O papel predefinido "Proprietário" inclui essas permissões.

Na primeira vez que você envia uma imagem para um host de registro no projeto (como gcr.io), o Container Registry cria um bucket de armazenamento para o registro. O papel de administrador do Storage tem as permissões necessárias para criar o bucket de armazenamento.

Como enviar imagens para um registro no projeto

Função: gravador de bucket legado do Storage (roles/storage.legacyBucketWriter) no bucket de armazenamento do registro.

Esse papel tem permissões para enviar e receber imagens de hosts de registro existentes no seu projeto. Por exemplo, se o projeto tiver apenas o registro gcr.io, um usuário com o papel de escritor de bucket legado do Storage poderá enviar imagens para gcr.io, mas não para asia.gcr.io.

Para informações sobre como conceder permissões a um registro, consulte Como configurar o controle de acesso.

Marcar a imagem local com o nome do registro

Para marcar uma imagem:

  1. Verifique se você configurou a autenticação para o Container Registry.

  2. Determine o nome da imagem no Container Registry:

    1. Escolha um nome de host, que especifica o local onde você armazenará a imagem.

      • gcr.io hospeda imagens em data centers nos Estados Unidos, mas o local pode mudar no futuro
      • us.gcr.io hospeda imagens em data centers nos Estados Unidos, em um bucket de armazenamento separado das imagens hospedadas por gcr.io
      • eu.gcr.io hospeda as imagens na União Europeia
      • asia.gcr.io hospeda imagens em data centers na Ásia

      Esses locais correspondem às multirregiões para os buckets de armazenamento do Cloud Storage. Quando você envia uma imagem para um registro com um novo nome do host, o Container Registry cria um bucket de armazenamento no local multirregional especificado. Esse bucket é o armazenamento subjacente para o registro. Em um projeto, todos os registros com o mesmo nome de host compartilham um bucket de armazenamento.

      No console, o nome do host das imagens será listado em Local.

    2. Escolha um nome de imagem de destino, que pode ser diferente do nome da imagem na sua máquina local. Por exemplo, a imagem local pode ser chamada de web-image, mas você quer armazená-la no Container Registry como web-site.

    3. Combine o nome do host, o ID do projeto do console do Google Cloud e o nome da imagem de destino:

      HOSTNAME/PROJECT-ID/TARGET-IMAGE

      Veja o exemplo a seguir.

      • Nome do host: gcr.io
      • Projeto do Google Cloud: my-project
      • Nome da imagem de destino: web-site

      A combinação do nome do host, do projeto e da imagem de destino fornece o caminho completo da imagem a ser usado para inclusão de tags:

      gcr.io/my-project/web-site

      Caso o ID do projeto contenha dois pontos (:), consulte Projetos com escopo de domínio.

  3. Marque a imagem local com o nome da etapa anterior. Se você quiser rotular essa versão da imagem com uma tag, inclua o nome dela.

    docker tag SOURCE_IMAGE HOSTNAME/PROJECT-ID/TARGET-IMAGE:TAG

    Substitua:

    • SOURCE_IMAGE é o nome da imagem local ou o ID da imagem.
    • HOSTNAME é o host de registro escolhido na etapa 2.
    • PROJECT é o ID do projeto do Google Cloud;
    • TARGET-IMAGE é o nome da imagem quando ela é armazenada no Container Registry.
    • TAG é a tag que você quer associar a essa versão da imagem.

    Por exemplo, este comando marca a imagem local web-image como gcr.io/my-project/web-site no Container Registry com a tag v1.5.

    docker tag web-image gcr.io/my-project/web-site:v1.5

    Se você não especificar uma tag, o Docker vai adicionar a tag padrão latest. Como latest é uma tag padrão, ela representa a versão da imagem mais recentemente marcada com a tag latest, e não necessariamente a versão mais recente de uma imagem.

O Docker marca sua imagem com o nome e a tag que você especificou no comando.

Enviar a imagem marcada para o Container Registry

  1. Verifique se você configurou a autenticação para o Container Registry.

  2. Envie a imagem marcada para o Container Registry:

    Execute o comando a seguir para enviar uma imagem com uma tag específica:

    docker push HOSTNAME/PROJECT-ID/IMAGE:TAG

    Se você omitir :TAG, o Docker vai enviar a versão da imagem com a tag latest.

    Por exemplo, este comando envia a imagem gcr.io/my-project/web-site com a tag v1.5:

    docker push gcr.io/my-project/web-site:v1.5

Quando você envia uma imagem para um host de registro que ainda não existe no seu projeto, o Container Registry cria um bucket de armazenamento para o host de registro.

Para conferir a imagem enviada:

  • Acesse o console do Google Cloud para conferir o registro e a imagem.

  • Execute gcloud container images list-tags para conferir a tag da imagem e o resumo gerado automaticamente:

    gcloud container images list-tags HOSTNAME/PROJECT-ID/IMAGE

    O resultado do comando é semelhante ao seguinte:

    DIGEST        TAGS        TIMESTAMP
44bde...      test        2017-..-..

Como extrair imagens de um registro

Para extrair uma imagem, é necessário ter o papel de Leitor de objetos do Storage no bucket de armazenamento do registro ou um papel com as mesmas permissões.

Para extrair do Container Registry, use o comando:

docker pull HOSTNAME/PROJECT-ID/IMAGE:TAG

ou

docker pull HOSTNAME/PROJECT-ID/IMAGE@IMAGE_DIGEST

onde:

  • HOSTNAME está listado em Local no console É uma das quatro opções: gcr.io, us.gcr.io, eu.gcr.io ou asia.gcr.io.
  • 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.
  • IMAGE é o nome da imagem no Container Registry;
  • TAG é a tag aplicada à imagem. Em um registro, as tags são exclusivas de uma imagem;
  • IMAGE_DIGEST é o valor de hash sha256 do conteúdo da imagem. No console do Google Cloud, clique na imagem específica para ver os metadados. O resumo é listado como Resumo da imagem.

Para receber o comando pull de uma imagem específica:

  1. Clique no nome de uma imagem para acessar o registro específico.

  2. No registro, marque a caixa ao lado da versão da imagem que você quer extrair.

  3. Clique em EXIBIR COMANDO PULL na parte superior da página.

  4. Copie o comando pull, que identifica a imagem usando a tag ou o resumo.

Próximas etapas