O Artifact Registry é o serviço recomendado para gerenciar imagens de contêiner. O Container Registry ainda é compatível, mas só recebe correções de segurança críticas. Saiba mais sobre a transição para o Artifact Registry.

Visão geral do Container Registry

O Container Registry é um registro de imagem de contêiner particular executado no Google Cloud. O Container Registry é compatível com o Docker Image Manifest V2 e com formatos de imagem OCI.

Muitas pessoas usam o Docker Hub como um registro central para armazenar imagens públicas do Docker. No entanto, para controlar o acesso às suas imagens, é necessário usar um registro privado como o Container Registry.

Acesse o Container Registry nos pontos de extremidade HTTPS seguros para executar pull, push e gerenciar de imagens de qualquer sistema, instância de VM ou do próprio hardware.

Registros

Registros no Container Registry são nomeados pelo host e pelo código do projeto. Para trabalhar com imagens (por exemplo, push, pull, delete), identifique a imagem usando o seguinte formato:

HOSTNAME/PROJECT-ID/IMAGE:TAG

ou

HOSTNAME/PROJECT-ID/IMAGE@IMAGE-DIGEST

em que:

  • HOSTNAME é o local onde a imagem está armazenada:

    • gcr.io hospeda as imagens nos Estados Unidos, mas o local pode mudar no futuro
    • us.gcr.io hospeda a imagem 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 as imagens 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.

  • PROJECT-ID é o ID do projeto do seu Console do Google Cloud. Se o código do projeto contiver dois pontos (:), consulte abaixo Projetos com escopo de domínio.

  • IMAGE é o nome da imagem. Ele pode ser diferente do nome local da imagem. No Console do Google Cloud, os registros do projeto são listados pelo nome da imagem. Cada repositório pode conter várias imagens com o mesmo nome. Por exemplo, ele pode conter versões diferentes de uma imagem denominada "my-image".

  • adicionar :TAG e @IMAGE-DIGEST no final permite distinguir uma versão específica da imagem, mas também é opcional. Se você não especificar uma tag ou o resumo, o Container Registry procurará a imagem com a tag padrão latest. Consulte abaixo versões de imagens dentro de um registro.

Para a imagem my-image no registro gcr.io/PROJECT-ID, use este formato para enviar ou extrair uma imagem:

gcr.io/PROJECT-ID/my-image:tag1

em que PROJECT-ID é o ID do projeto do seu Console do Google Cloud.

Como organizar imagens com repositórios

É possível agrupar imagens relacionadas em um repositório dentro em um registro. Ao marcar, enviar ou extrair uma imagem, você especifica o nome do repositório no projeto no caminho da imagem.

Veja o exemplo a seguir.

us.gcr.io/builds/dev/web-app:beta-2.0
us.gcr.io/builds/stable/web-app:1.0

Há duas imagens chamadas web-app no projeto builds. Uma está em um repositório dev e a outra está em um repositório stable. Essa estrutura permite armazenar diferentes versões de uma imagem para ser compatível com diferentes estágios de desenvolvimento ou equipes diferentes.

Se necessário, você pode aninhar repositórios. Neste exemplo, dois produtos separados têm um repositório de nível superior com repositórios filhos abaixo deles. 

us.gcr.io/builds/product1/dev/product1-app:beta-2.0
us.gcr.io/builds/product1/stable/product1:1.0
us.gcr.io/builds/product2/dev/product2:alpha
us.gcr.io/builds/product2/stable/product2:1.0

Os repositórios são auxiliares de organização. Eles funcionam como pastas lógicas no caminho da imagem, mas não refletem a estrutura real do sistema de arquivos ou são compatíveis com um controle de acesso mais granular.

Versões de imagens dentro de um registro

Um registro pode conter muitas imagens, e essas imagens podem ter versões diferentes. Para identificar uma versão específica da imagem em um registro, você pode especificar a tag ou o resumo da imagem.

  • As tags atuam como um rótulo. É possível aplicar várias tags a uma imagem. Por exemplo, uma imagem pode ter a tag v1.5 para um número de versão e release-candidate para indicar a prontidão para testes finais.
  • Os resumos são gerados automaticamente, são exclusivos de uma versão de uma imagem e têm a forma @IMAGE-DIGEST, em que IMAGE-DIGEST é o valor de hash sha256 do conteúdo da imagem.

Para identificar uma versão específica da imagem my-image:

  • adicione a tag da imagem:

    gcr.io/PROJECT-ID/my-image:tag1

  • ou adicione o resumo da imagem:

    gcr.io/PROJECT-ID/my-image@sha256:4d11e24ba8a615cc85a535daa17b47d3c0219f7eeb2b8208896704ad7f88ae2d

em que PROJECT-ID é o ID do projeto do seu Console do Google Cloud. Se o código do projeto contiver dois pontos (:), consulte abaixo Projetos com escopo de domínio.

No Console do Cloud, na tela Imagens, a coluna Tags lista as tags da imagem. Clique na respectiva versão da imagem para ver os metadados, incluindo o Resumo da imagem.

Consulte Como incluir tags em imagens para saber como modificar tags.

Projetos de escopo de domínio

Se seu projeto estiver no escopo de seu domínio, o ID do projeto incluirá o nome do domínio seguido por dois pontos (:). Por causa de como o Docker trata dois-pontos, você deve substituir o caractere de dois pontos por uma barra quando especificar um resumo de imagem no Container Registry. Identifique imagens nesses tipos de projetos usando o seguinte formato:

HOSTNAME/[DOMAIN]/[PROJECT]/IMAGE

Por exemplo, o projeto com o ID example.com:my-project poderia ter a seguinte imagem:

gcr.io/example.com/my-project/image-name

Nomes de registro como URLs

O URL https://HOSTNAME/PROJECT-ID/IMAGE é um URL deste registro no Console do Cloud. Esses links podem ser acessados por qualquer usuário autenticado que tenha permissão para acessar o registro. Veja acima como definir o nome do registro.

Por exemplo, os URLs a seguir vinculam a registros públicos no Console do Cloud:

Formatos de imagem de contêiner

O Container Registry é compatível com o Docker Image Manifest V2 e com formatos de imagem OCI.

Para mais informações, consulte Formatos de imagem de contêiner.

Controle de acesso

No Container Registry, as tags e os arquivos de camada para imagens de contêiner são armazenados em um bucket do Cloud Storage no mesmo projeto que o registro. O acesso ao bucket é configurado com as definições de gerenciamento de acesso e identidade (IAM, na sigla em inglês) do Cloud Storage.

Por padrão, os proprietários e editores do projeto têm permissões de push e pull para esse bucket do projeto do Container Registry. Os leitores do projeto têm apenas permissão de pull.

Para mais informações, consulte Como configurar Controle de acesso.

Acesse os avisos de suspensão de uso e veja mais informações sobre planos que mudam metadados de imagem do Cloud Storage para uma base de dados de back-end de alto desempenho.

Authentication

Antes de enviar ou extrair imagens, você deve configurar a autenticação. Você pode configurar o Docker para usar a ferramenta de linha de comando gcloud para autenticar solicitações para o Container Registry. O Container Registry é compatível com métodos avançados de autenticação com uso de tokens de acesso ou arquivos de chave JSON.

Auxiliar de credenciais do Docker

É necessário que o Docker tenha acesso ao Container Registry para enviar e receber imagens. Use a ferramenta de linha de comando auxiliar de credenciais do Docker para configurar as credenciais do Container Registry para uso com o Docker.

A ferramenta auxiliar de credenciais recebe as credenciais do Container Registry automaticamente ou de um local especificado usando um sinalizador --token-source. Em seguida, ela grava as credenciais no arquivo de configuração do Docker. Dessa forma, você pode usar a ferramenta de linha de comando do Docker, docker, para interagir diretamente com o Container Registry.

Para mais informações, consulte Autenticação avançada.

Conta do serviço do Container Registry

Quando você ativa a Container Registry API, o Container Registry adiciona ao seu projeto uma conta de serviço com o seguinte nome:

service-[PROJECT_NUMBER]@containerregistry.iam.gserviceaccount.com

Essa conta de serviço foi criada especificamente para que o Container Registry possa executar as tarefas do serviço no seu projeto. O Google é proprietário desta conta, mas é específico para seu projeto e está listado nas seções Contas de serviço e IAM do Console do Cloud.

Se você excluir essa conta de serviço ou alterar suas permissões, alguns recursos do Container Registry não funcionarão corretamente. Você não deve modificar papéis nem excluir a conta.

Cache de pull

O registro mirror.gcr.io armazena em cache imagens públicas solicitadas com frequência dos repositórios oficiais do Docker Hub.

O uso de imagens armazenadas em cache pode acelerar a execução de pulls do Docker Hub. Seu cliente sempre verifica a cópia em cache de uma imagem do Docker Hub antes de tentar extraí-la diretamente do Docker Hub.

Para mais informações, consulte Como extrair imagens armazenadas em cache do Docker Hub.

Notificações

É possível usar o Pub/Sub para receber notificações sobre alterações nas imagens do contêiner.

Para obter mais informações, consulte Como configurar notificações do Pub/Sub.

Como usar o Container Registry com o Google Cloud

As instâncias do Compute Engine e os clusters do Google Kubernetes Engine podem enviar e extrair imagens do Container Registry por push ou pull com base nos escopos do Cloud Storage nas instâncias. Consulte Como usar o Container Registry com o Google Cloud.

As imagens armazenadas no Container Registry podem ser implantadas no ambiente flexível do App Engine.

Integrações com ferramentas de entrega contínua

O Container Registry trabalha com sistemas de entrega contínua conhecidos.

Usar o Container Registry com soluções de terceiros

Ao desenvolver seus aplicativos, você pode usar o gerenciamento de cluster de terceiros, a integração contínua ou outras soluções fora do Google Cloud. É possível integrar o Container Registry a esses serviços externos.

Essas soluções podem não fornecer acesso à ferramenta de linha de comando gcloud para autenticação. Nesses casos, você pode usar docker login para autenticar diretamente com o Container Registry. Para mais informações, consulte Autenticação avançada.

Para ver uma lista de soluções de terceiros que se integram ao Container Registry, consulte Integrações de ferramenta de entrega contínua.