Esta página foi traduzida pela API Cloud Translation.

Mudanças para criar e implantar no Google Cloud

Este documento orienta 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 em repositórios padrão do Artifact Registry, 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 tiver configurado 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 do Artifact Registry correspondente, e as contas de serviço padrão que têm 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 recebimento com o Docker.

Use essas informações para adaptar comandos, configurações ou documentação existentes com foco no Container Registry com o Cloud Build.

Antes de começar

Este documento pressupõe que você já tenha:

Ativou o Artifact Registry no projeto.
Ative a API Cloud Build e a API para qualquer outro serviço do Google Cloud que você estiver 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 é assim:

Crie, marque e envie uma imagem para o repositório com o Cloud Build, usando um Dockerfile ou um arquivo de configuração do build.

O exemplo a seguir cria a imagem my-image, a marca com tag1 e a envia para o host gcr.io no projeto my-project:
```
gcloud builds submit --tag gcr.io/my-project/my-image:tag1
```
Google Cloud ambientes de execução, como o Cloud Run e o Google Kubernetes Engine, extraem imagens do registro.

Por exemplo, este 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 as responsabilidades do administrador com a criação e a 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 builds no Cloud Build podem enviar imagens para registros e adicionar hosts de registro por padrão.
A conta de serviço do Cloud Build tem permissões para criar buckets do Cloud Storage. Isso significa que a conta pode adicionar automaticamente hosts do Container Registry a um projeto na primeira vez que uma imagem é enviada ao host. Isso também significa que a conta pode criar, ler e gravar em buckets de armazenamento em todo o projeto, incluindo os que não são usados pelo Container Registry.

No Artifact Registry, há uma separação clara entre as funções de administrador e de build que muda as etapas no fluxo de trabalho de build e implantação. Para adaptar o fluxo de trabalho do Container Registry ao Artifact Registry, faça as seguintes mudanças. Cada etapa tem um link para mais informações sobre como modificar o fluxo de trabalho.

Novo: ative a API Artifact Registry.

Ative a API Artifact Registry. O Cloud Build e ambientes de execução, como o Cloud Run e o GKE, não ativam a API automaticamente.
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: crie, marque e envie 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 é o mesmo 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
```
Mudança: implante a imagem em um ambiente de execução do Google Cloud , como o Cloud Run ou o GKE.

O comando de exemplo a seguir é o mesmo 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 funções diferentes do Container Registry para controlar o acesso a 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.
Você usa 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 serviço ou usuários.

Ative a API

Pontos principais

É necessário ativar a API Artifact Registry e a API para outros serviços Google Cloud , como Cloud Build, Cloud Run e GKE.

A comparação a seguir descreve como ativar a 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
Funções do Cloud Run
Cloud Run
Verificação de contêineres 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, escanear contêineres com o Artifact Analysis ou implantar contêineres no Google Cloud têm acesso implícito às imagens no Container Registry quando o registro está no mesmo projeto.

Artifact Registry

Ative a API Artifact Registry. Serviços como o Cloud Build, o Cloud Run e o GKE não ativam automaticamente a API Artifact Registry.

É possível ativar várias APIs no mesmo projeto usando o gcloud. Por exemplo, para ativar a API Cloud Build e a API 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 do 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 projeto. Para adicionar um host de registro, envie a primeira imagem.

Para adicionar um registro, como gcr.io, ao seu projeto, uma conta com a função de administrador do Storage no nível do projeto envia uma imagem inicial.

Por exemplo, se o host gcr.io não existir no projeto my-project, o envio da imagem gcr.io/my-project/my-image:1.0 aciona as etapas a seguir:
1. Adicionar o host gcr.io ao projeto
2. Crie um bucket de armazenamento para gcr.io no projeto.
3. Armazenar a imagem como gcr.io/my-project/my-image:1.0
Após esse envio inicial, você pode 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. Assim, o envio inicial de imagem e os envios subsequentes não podem ser diferenciados.

Em 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 no 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 a função de administrador do repositório do Artifact Registry precisa criar o repositório antes de enviar imagens para ele. Em seguida, você pode conceder permissões ao repositório para outros usuários.

No Artifact Registry, cada repositório é um recurso separado. Portanto, todos os caminhos de imagem 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

Os exemplos a seguir mostram situações em que o envio de uma imagem para um repositório ausente falha.

Envio de uma imagem para us-central1-docker.pkg.dev/my-project/team1 se us-central1-docker.pkg.dev/my-project/team1 não existir.
O envio de uma imagem para us-central1-docker.pkg.dev/my-project/team2 quando us-central1-docker.pkg.dev/my-project/team1 existe, mas us-central1-docker.pkg.dev/my-project/team2 não existe.

Como conceder permissões

Pontos principais

Os serviços doGoogle Cloud têm acesso de leitura ou gravação equivalente 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 as funções adequadas 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 de 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 de armazenamento para adicionar hosts do Container Registry a um projeto.

Leitor de objetos do Storage no nível do bucket de armazenamento: Extrair (ler) imagens de hosts de registro no projeto.
Gravador de bucket legado do Storage no nível do bucket de armazenamento: Enviar (gravar) e extrair (ler) imagens para hosts de registro no projeto.
Administrador de armazenamento no nível do projeto: Adicione um host de registro a um projeto enviando uma imagem inicial para o host.

Após o envio inicial da imagem para um registro, você concede papéis do Cloud Storage a outras contas que precisam de 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 do Storage 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 para gcr.io/my-project pode ler imagens em todos esses 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 funções próprias para controlar o acesso. Essas funções fornecem uma separação clara entre as funções de administrador e de usuário do repositório.

O Cloud Build tem permissões no papel de escritor do Artifact Registry, já que só precisa enviar e extrair imagens com repositórios padrão no domínio pkg.dev.

Somente as contas que gerenciam repositórios podem ter a função de administrador do repositório do Artifact Registry ou 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 de escritor do Artifact Registry e permissões para excluir artefatos e tags.
Administrador do Artifact Registry: Permissões de administrador do repositório do Artifact Registry e permissões 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
Conceder 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 do 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 envio inicial de imagem, 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 seus repositórios antes de enviar imagens para eles.
Atualize os caminhos de imagem no arquivo de configuração do build ou nos comandos gcloud builds submit.

Como criar com um arquivo de configuração de compilação

Substitua os caminhos do Container Registry para imagens que você cria pelo caminho de um repositório do Artifact Registry.

O exemplo de arquivo cloudbuild.yaml a seguir 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'

Em seguida, crie a imagem com o comando:

gcloud builds submit --config cloudbuild.yaml

Como criar com um Dockerfile

Substitua os caminhos do Container Registry para imagens que você cria pelo caminho para um repositório do Artifact Registry.

O exemplo de comando a seguir 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 principal:

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 de imagem na configuração e nos comandos de implantação. As seções a seguir mostram exemplos para o Cloud Build, o Cloud Run e o 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 para imagens implantadas pelo caminho de um repositório do Artifact Registry.

O exemplo de arquivo cloudbuild.yaml a seguir implanta a imagem de exemplo 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 para imagens implantadas pelo caminho de um repositório 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 para imagens que você cria pelo caminho de um repositório do Artifact Registry.

Os exemplos a seguir para o Artifact Registry usam a imagem de exemplo us-docker.pkg.dev/artifact-registry-samples/containers/gke/hello-app:1.0.

Criação de 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

Como 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