Neste documento, orientamos você sobre as diferenças entre o Container Registry e o Artifact Registry para autenticar, enviar e extrair imagens de contêiner com o Docker.
Neste guia, as comparações se concentram nos repositórios padrão do Artifact Registry e nos repositórios normais do Artifact Registry que são independentes do Container Registry e oferecem suporte a todos os recursos do Artifact Registry.
Se o administrador configurar
repositórios com suporte ao domínio gcr.io, as solicitações
para nomes de host gcr.io
serão redirecionadas automaticamente para um repositório
correspondente do Artifact Registry. Para usar um repositório gcr.io hospedado no
Artifact Registry, você precisa ter um
papel do Artifact Registry apropriado ou com
permissões equivalentes.
Para saber mais sobre as diferenças entre o Container Registry e o Artifact Registry ao criar com o Cloud Build e implantar no Cloud Run ou no Google Kubernetes Engine, consulte Mudanças no Cloud Build, Cloud Run e GKE.
Use essas informações para adaptar os comandos, a configuração ou a documentação atual focados no Container Registry com o Docker.
Antes de começar
Para seguir este documento, você precisa ter:
- Ativou o Artifact Registry no projeto.
- Instalou o Docker. O Docker está incluído no Cloud Shell.
Informações gerais
De modo geral, o fluxo de trabalho para usar o Docker com o Container Registry ou o Artifact Registry é o mesmo.
Container Registry | Artifact Registry |
---|---|
Administrador
|
Administrador
|
Usuários de registro
|
Usuários de registro
|
No entanto, um atalho do Container Registry é combinar as funções de administrador e usuário em um único fluxo de trabalho. Esse atalho é comum em:
- Guias de início rápido e tutoriais em que você está testando em um ambiente onde você tem permissões amplas.
- Workflows que usam o Cloud Build, já que a conta de serviço do Cloud Build tem permissões para adicionar um host de registro no mesmo projeto do Google Cloud.
O fluxo de trabalho de atalhos tem esta aparência:
- Ative a API Container Registry.
- Conceda permissões à conta que vai acessar o Container Registry.
Faça a autenticação no registro. A opção de autenticação mais simples é usar o auxiliar de credenciais do Docker na Google Cloud CLI. Essa é uma etapa de configuração única.
gcloud auth configure-docker
Crie e marque a imagem. Por exemplo, este comando cria e marca a imagem
gcr.io/my-project/my-image:tag1
:docker build -t gcr.io/my-project/my-image:tag1
Envie a imagem para o registro. Exemplo:
docker push gcr.io/my-project/my-image:tag1
Se o host de registro
gcr.io
não existir no projeto, o Container Registry o adicionará antes de fazer upload da imagem.Extraia a imagem do registro ou implante em um ambiente de execução do Google Cloud. Exemplo:
docker pull gcr.io/my-project/my-image:tag1
Esse fluxo de trabalho depende dos seguintes atalhos:
- A conta que envia imagens tem o papel de Administrador do Storage ou um papel com as mesmas permissões, como Proprietário. As permissões amplas desse papel dão acesso de leitura e gravação a todos os buckets de armazenamento em um projeto, incluindo os que não são usados pelo Container Registry.
- Quando você ativa algumas APIs do Google Cloud, a API Container Registry é ativada automaticamente. Isso significa que os usuários desses serviços têm acesso implícito ao Container Registry no mesmo projeto. Por exemplo, os usuários que podem executar versões no Cloud Build podem enviar imagens para os registros e adicionar hosts de registro por padrão.
No Artifact Registry, há uma separação clara dos papéis do administrador e do usuário do repositório, o que altera as etapas no fluxo de trabalho de build e implantação. Para adaptar o fluxo de trabalho do Container Registry para o Artifact Registry, faça as alterações a seguir. Cada etapa é vinculada a informações adicionais sobre como modificar o fluxo de trabalho.
Novo: ative a API Artifact Registry.
A API Artifact Registry precisa ser ativada. Os ambientes de execução e do Cloud Build, como o Cloud Run e o GKE, não ativam a API automaticamente para você.
Novo: crie o repositório de destino do Docker, se ele ainda não existir. É necessário criar um repositório antes de enviar imagens para ele. O envio de uma imagem não aciona a criação de um repositório e a conta de serviço do Cloud Build não tem permissões para criar repositórios.
Conceda permissões à conta que vai interagir com o Artifact Registry.
Alterado: Autenticar no repositório. Se você usa o auxiliar de credenciais na CLI gcloud, é necessário especificar os hosts que quer adicionar à configuração do cliente do Docker. Por exemplo, este comando adiciona o host
us-central1-docker.pkg.dev
:gcloud auth configure-docker us-central1-docker.pkg.dev
Alterado: crie e marque a imagem.
O comando de exemplo a seguir é igual ao exemplo do Container Registry, mas usa um caminho de repositório do Artifact Registry para a imagem.
docker build -t us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
Alterado: envie a imagem para o repositório usando o caminho do Artifact Registry. Exemplo:
docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
Alterado: puxe a imagem do repositório usando o caminho do Artifact Registry. Exemplo:
docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
Ative a API
Pontos principais
- É necessário ativar a API Artifact Registry além da API para outros serviços do Google Cloud, como Cloud Build, Cloud Run e GKE.
A comparação a seguir descreve a ativação da API para cada serviço:
Container Registry
É necessário ativar a API Container Registry antes de usar o Docker ou outros clientes de terceiros com o Container Registry.
Quando você ativa as seguintes APIs do Google Cloud, a API Container Registry também é ativada automaticamente:
- Ambiente flexível do App Engine
- Cloud Build
- Cloud Functions
- Cloud Run
- Verificação de contêiner ou verificação sob demanda no Artifact Analysis
- Google Kubernetes Engine
Com as permissões padrão, os usuários que podem executar builds no Cloud Build, verificar contêineres com o Artifact Analysis ou implantar contêineres em ambientes de execução do Google Cloud têm acesso implícito a imagens no Container Registry quando o registro está no mesmo projeto.
Artifact Registry
É necessário ativar a API Artifact Registry antes de usar clientes Docker ou outros serviços do Google Cloud com o Artifact Registry.
Serviços como Cloud Build, Cloud Run e GKE não ativam automaticamente a API Artifact Registry.
É possível ativar várias APIs no mesmo projeto usando a gcloud. Por exemplo, para ativar as APIs Cloud Build e Artifact Registry, execute o comando:
gcloud services enable
artifactregistry.googleapis.com \
cloudbuild.googleapis.com
Como adicionar registros e repositórios
Pontos principais
É necessário criar um repositório Docker do Artifact Registry antes de enviar uma imagem para ele.
Uma etapa de criação de registro geralmente é excluída da documentação que descreve como enviar imagens para o Container Registry porque uma conta com permissões de administrador de armazenamento pode adicionar um registro a um projeto com o envio inicial ao host de registro.
O Container Registry armazena todas as imagens em uma única multirregião no mesmo bucket de armazenamento. No Artifact Registry, é possível criar vários repositórios na mesma região ou multirregião com políticas de acesso separadas.
A comparação a seguir descreve a configuração do repositório em cada serviço:
Container Registry
No Container Registry, é possível adicionar até quatro hosts de registro ao seu projeto. Para adicionar um host de registro, envie a primeira imagem.
Para adicionar um registro como
gcr.io
ao projeto, uma conta com o papel de Administrador do Storage no nível do projeto envia uma imagem inicial.Por exemplo, se o host
gcr.io
não existir no projetomy-project
, enviar a imagemgcr.io/my-project/my-image:1.0
acionará as seguintes etapas:- Adicione o host
gcr.io
ao projeto - Crie um bucket de armazenamento para
gcr.io
no projeto. - Armazenar a imagem como
gcr.io/my-project/my-image:1.0
- Adicione o host
Após esse envio inicial, será possível conceder permissões ao bucket de armazenamento para outros usuários.
Dentro de um projeto, um host de registro armazena todas as imagens no mesmo bucket de armazenamento. No exemplo abaixo, o projeto my-project
tem duas imagens chamadas
web-app
no registro gcr.io
. Um está diretamente abaixo do ID do projeto
my-project
. A outra imagem está no repositório team1
.
gcr.io/my-project/web-app
gcr.io/my-project/team1/web-app
Artifact Registry
Uma conta com o papel de administrador do repositório do Artifact Registry precisa criar o repositório antes de enviar imagens para ele. Depois, conceda permissões ao repositório para outros usuários.
No Artifact Registry, cada repositório é um recurso separado. Portanto, todos os caminhos de imagens precisam incluir um repositório.
Caminhos de imagem válidos:
us-central1-docker.pkg.dev/my-project/team1/web-app:1.0
us-central1-docker.pkg.dev/my-project/team2/web-app:1.0
Caminho de imagem inválido (não inclui um repositório) :
us-central1-docker.pkg.dev/my-project/web-app:1.0
Nos exemplos a seguir, mostramos situações em que o envio de uma imagem para um repositório ausente falha.
- Enviar uma imagem para
us-central1-docker.pkg.dev/my-project/team1
seus-central1-docker.pkg.dev/my-project/team1
não existir. - Enviar uma imagem para
us-central1-docker.pkg.dev/my-project/team2
quandous-central1-docker.pkg.dev/my-project/team1
existir, masus-central1-docker.pkg.dev/my-project/team2
não existir.
Como conceder permissões
Pontos principais
- Conceda o papel apropriado do Artifact Registry à conta que você está usando com o Artifact Registry.
- Os serviços do Google Cloud têm acesso equivalente de leitura ou gravação ao Container Registry e ao Artifact Registry. No entanto, a conta de serviço padrão do Cloud Build não pode criar repositórios.
- O Container Registry oferece suporte ao controle de acesso no nível do bucket de armazenamento. O Artifact Registry oferece suporte ao controle de acesso no nível do repositório.
A comparação a seguir descreve a configuração das permissões em cada serviço:
Container Registry
O Container Registry usa os papéis do Cloud Storage para controlar o acesso.
- Leitor de objetos do Storage no nível do bucket do Storage
- Extrair (ler) imagens dos hosts de registro atuais do projeto.
- Gravador de bucket legado do Storage no nível do bucket de armazenamento
- Enviar (gravar) e extrair (ler) imagens para hosts de registro existentes no projeto.
- Administrador do Storage no nível do projeto
- Para adicionar um host de registro a um projeto, envie uma imagem inicial a ele.
Depois do envio da imagem inicial para um registro, conceda papéis do Cloud Storage a outras contas que exijam acesso ao bucket de armazenamento. Qualquer conta com todas as permissões no papel de Administrador do Storage pode ler, gravar e excluir buckets e objetos de armazenamento em todo o projeto.
As permissões em um bucket de armazenamento se aplicam a todos os repositórios no registro.
Por exemplo, qualquer usuário com permissões de Leitor de objetos do Storage no bucket de gcr.io/my-project
pode ler imagens em todos estes repositórios:
gcr.io/my-project/team1
gcr.io/my-project/team2
gcr.io/my-project/test
gcr.io/my-project/production
Artifact Registry
O Artifact Registry tem papéis próprios para controlar o acesso. Esses papéis oferecem uma separação clara entre os papéis do usuário de administrador e do repositório.
Apenas contas que gerenciam repositórios precisam ter o papel Administrador de repositórios do Artifact Registry ou de Administrador do Artifact Registry.
- Leitor do Artifact Registry
- Listar artefatos e repositórios. Faça o download dos artefatos.
- Gravador do Artifact Registry
- Listar artefatos e repositórios. Faça o download de artefatos, faça upload de novas versões de artefatos e adicione ou atualize tags.
- Administrador do repositório do Artifact Registry
- Permissões e permissões de gravador do Artifact Registry para excluir artefatos e tags.
- Administrador do Artifact Registry
- Permissões e permissões de administrador do repositório do Artifact Registry para criar, atualizar, excluir e conceder permissões a repositórios.
É possível aplicar essas permissões no nível do repositório. Exemplo:
- Conceder acesso à Equipe 1 para
us-central1-docker.pkg.dev/my-project/team1
- Conceda acesso à Equipe 2 para
us-central1-docker.pkg.dev/my-project/team2
.
Para detalhes sobre como conceder permissões do Artifact Registry, consulte a documentação de controle de acesso.
Como autenticar no registro
Pontos principais
- O Artifact Registry oferece suporte aos mesmos métodos de autenticação que o Container Registry.
- Para o auxiliar de credenciais do Docker, especifique os hosts que serão adicionados à configuração do cliente do Docker.
- Para autenticação usando
docker login
, use o host do Artifact Registry em vez de um host do Container Registry.
Como usar o auxiliar de credenciais
Por padrão, o comando gcloud auth configure-docker
e o auxiliar de credencial autônomo configuram apenas o Docker para nomes de host *.gcr.io
. No caso do Artifact Registry,
é preciso especificar uma lista dos hosts do Artifact Registry que você quer adicionar à configuração do cliente do
Docker.
Por exemplo, para configurar a autenticação em repositórios do Docker na região us-central1
, execute o seguinte comando:
gcloud auth configure-docker us-central1-docker.pkg.dev
Se mais tarde você adicionar repositórios em us-east1
e asia-east1
, execute
o comando novamente para adicionar os nomes de host regionais correspondentes à
configuração do Docker.
gcloud auth configure-docker us-east-docker.pkg.dev,asia-east1-docker.pkg.dev
Para detalhes sobre os métodos de autenticação do Artifact Registry, consulte Como configurar a autenticação para o Docker.
Como usar a autenticação por senha
Ao fazer login no Docker, use o nome do host do Artifact Registry em vez de
o nome do host *.gcr.io
. O exemplo a seguir mostra a autenticação com uma
chave de conta de serviço codificada em base64 para o host us-central1-docker.pkg.dev
:
cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-central1-docker.pkg.dev
Como criar e marcar imagens
Pontos principais: - O Artifact Registry usa um nome de host diferente para os repositórios.
Ao marcar uma imagem, use o caminho do Artifact Registry em vez do do Container Registry. Exemplo:
docker tag my-image us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0
Como enviar imagens ao registro
Pontos principais: - No Artifact Registry, o repositório de destino precisa existir antes que você envie uma imagem para ele. - O Artifact Registry usa um nome de host diferente para os repositórios.
Ao enviar uma imagem, use o caminho do Artifact Registry em vez do do Container Registry. Exemplo:
docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0
Extrair imagens do registro
Ponto-chave:
- Os nomes de host do Artifact Registry são diferentes dos nomes de host do Container Registry.
Ao extrair uma imagem, use o caminho do Artifact Registry em vez do do Container Registry. Exemplo:
docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0
Para ver exemplos de como implantar imagens nos ambientes de execução do Google Cloud, como o Cloud Run e o GKE, consulte Como implantar imagens.