Neste documento, orientamos você sobre as diferenças entre o Container Registry e o Artifact Registry ao criar imagens de contêiner com o Cloud Build e implantá-las em ambientes de execução do Google Cloud, como o Cloud Run ou o Google Kubernetes Engine.
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, e as contas de serviço padrão com acesso
ao Container Registry terão permissões padrão equivalentes para o Artifact Registry.
Para saber mais sobre as diferenças entre o Container Registry e o Artifact Registry usando um cliente do Docker, consulte Alterações no envio e extração com o Docker.
Use estas informações para adaptar os comandos, configurações ou documentação atuais focados no Container Registry com o Cloud Build.
Antes de começar
Para seguir este documento, você precisa ter:
- Ativou o Artifact Registry no projeto.
- ativar a API Cloud Build e a API para qualquer outro serviço do Google Cloud que você esteja usando com o Artifact Registry;
Mudanças no fluxo de trabalho
Quando você usa o Cloud Build com o Container Registry no mesmo projeto, o fluxo de trabalho fica assim:
Crie, marque e envie uma imagem para o repositório com o Cloud Build, usando um
Dockerfile
ou um arquivo de configuração de build.O exemplo a seguir cria a imagem
my-image
, marca-a comtag1
e a envia para o hostgcr.io
no projetomy-project
:gcloud builds submit --tag gcr.io/my-project/my-image:tag1
Os ambientes de execução do Google Cloud, como o Cloud Run e o Google Kubernetes Engine, extraem imagens do registro.
Por exemplo, esse comando implanta a imagem da etapa anterior no Cloud Run como
my-service
.gcloud run deploy my-service --image gcr.io/my-project/my-image:tag1
O fluxo de trabalho do Container Registry combina responsabilidades de administrador com a criação e implantação.
- 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.
- A conta de serviço do Cloud Build tem permissões para criar buckets de armazenamento do Cloud Storage. Isso significa que a conta pode adicionar automaticamente hosts do Container Registry a um projeto na primeira vez que ele enviar uma imagem ao host. Isso também significa que a conta pode criar, ler e gravar nos buckets de armazenamento em todo o projeto, incluindo buckets que não são usados pelo Container Registry.
No Artifact Registry, há uma separação clara dos papéis de administrador e de build, 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.
Alterado: Criar, marcar e enviar uma imagem para o repositório com o Cloud Build, usando um
Dockerfile
ou um arquivo de configuração da versão.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.
gcloud builds submit --tag us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
Alterado: implante a imagem em um ambiente de execução do Google Cloud, como o Cloud Run ou GKE.
O comando de exemplo a seguir é igual ao exemplo do Container Registry, mas usa o caminho do repositório do Artifact Registry para a imagem.
gcloud run deploy my-service --image us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
Além disso, o Artifact Registry usa papéis diferentes do Container Registry para controlar o acesso às imagens. É necessário configurar as permissões nas seguintes situações:
- Os ambientes de execução do Cloud Build ou do Google Cloud estão em um projeto diferente do Artifact Registry.
- Use contas de serviço personalizadas para serviços do Google Cloud, como o Cloud Build ou o GKE, em vez das contas de serviço padrão.
- Você concedeu permissões a outras contas de usuário ou de serviço.
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
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
A API Artifact Registry precisa ser ativada. 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.
- 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.
Por padrão, o Cloud Build tem as permissões necessárias para criar um bucket de armazenamento. Portanto, o envio da imagem inicial e os envios subsequentes são indistinguíveis.
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
O Cloud Build não tem permissões para criar um repositório
padrão no domínio pkg.dev
do 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
- 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 padrão
no domínio
pkg.dev
. - Conceda os papéis apropriados do Artifact Registry a outras contas que acessam o Artifact Registry.
- 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 as permissões para cada serviço:
Container Registry
O Container Registry usa os papéis do Cloud Storage para controlar o acesso. O Cloud Build tem as permissões necessárias no papel de administrador do Storage para adicionar hosts do Container Registry a um projeto.
- 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.
O Cloud Build tem permissões
no papel Gravador do Artifact Registry, porque ele só precisa enviar
e extrair imagens com repositórios padrão no domínio pkg.dev
.
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 criar e enviar imagens
Pontos principais
- É necessário criar um repositório Docker do Artifact Registry antes de enviar uma imagem para ele.
- Os nomes de host do Artifact Registry são diferentes dos nomes de host do Container Registry.
O Cloud Build pode criar, marcar e enviar uma imagem em uma única etapa.
Com o Container Registry, o Cloud Build pode enviar uma imagem para um host de registro que ainda não existe no projeto do Google Cloud. Para esse push de imagem inicial, o Cloud Build tem permissões para adicionar automaticamente o host do registro ao projeto.
Para adaptar um fluxo de trabalho do Container Registry:
- Configure os repositórios antes de enviar imagens para eles.
- Atualize os caminhos das imagens no arquivo de configuração do build, nos comandos
gcloud builds submit
ou no arquivo de configuração do build.
Como criar com um arquivo de configuração de compilação
Substitua os caminhos do Container Registry das imagens criadas por você pelo caminho para um repositório atual do Artifact Registry.
O arquivo cloudbuild.yaml
de exemplo abaixo cria a imagem
us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
:
steps:
- name: 'gcr.io/cloud-builders/docker'
args: [ 'build', '-t', 'us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1', '.' ]
images:
- 'us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1'
É possível criar a imagem com o comando:
gcloud builds submit --config cloudbuild.yaml
Como criar com um Dockerfile
Substitua os caminhos do Container Registry das imagens criadas por você pelo caminho para um repositório atual do Artifact Registry.
O comando de exemplo abaixo cria a imagem
us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
com um
Dockerfile
no diretório atual:
gcloud builds submit --tag us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
Como implantar imagens
Ponto-chave:
- Os nomes de host do Artifact Registry são diferentes dos nomes de host do Container Registry.
Para adaptar um fluxo de trabalho do Container Registry, atualize os caminhos da imagem na configuração e nos comandos de implantação. As seções a seguir mostram exemplos para o Cloud Build, Cloud Run e GKE, mas a mesma abordagem se aplica a qualquer outro serviço do Google Cloud que implanta imagens.
Cloud Build
Substitua os caminhos do Container Registry das imagens implantadas pelo caminho para um repositório atual do Artifact Registry.
O arquivo cloudbuild.yaml
de exemplo a seguir implanta a imagem de amostra
us-docker.pkg.dev/cloudrun/container/hello
.
steps:
- name: 'gcr.io/cloud-builders/gcloud'
args:
- 'run'
- 'deploy'
- 'cloudrunservice'
- '--image'
- 'us-docker.pkg.dev/cloudrun/container/hello'
- '--region'
- 'us-central1'
- '--platform'
- 'managed'
- '--allow-unauthenticated'
Cloud Run
Substitua os caminhos do Container Registry das imagens implantadas pelo caminho para um repositório atual do Artifact Registry.
Por exemplo, este comando implanta a imagem de amostra us-docker.pkg.dev/cloudrun/container/hello
.
gcloud run deploy my-service --image us-docker.pkg.dev/cloudrun/container/hello
GKE;
Substitua os caminhos do Container Registry das imagens criadas por você pelo caminho para um repositório atual do Artifact Registry.
Os exemplos a seguir do Artifact Registry usam a imagem de amostra
us-docker.pkg.dev/artifact-registry-samples/containers/gke/hello-app:1.0
.
Como criar um cluster na linha de comando:
kubectl create deployment hello-server --image=us-docker.pkg.dev/artifact-registry-samples/containers/gke/hello-app:1.0
Especificar uma imagem em um manifesto de implantação:
In a deployment manifest:
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
replicas: 3
selector:
matchLabels:
run: my-app
template:
metadata:
labels:
run: my-app
spec:
containers:
- name: hello-app
image: us-docker.pkg.dev/artifact-registry-samples/containers/gke/hello-app:1.0