Esta página foi traduzida pela API Cloud Translation.
Switch to English

Mudanças para criar e implantar no Google Cloud

Neste documento, você conhecerá 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.

Para saber mais sobre as diferenças entre o Container Registry e o Artifact Registry usando um cliente Docker, consulte Alterações no envio e extração com o Docker.

Use essas informações para adaptar os comandos, a configuração ou a documentação atuais do Container Registry com o Cloud Build.

Antes de começar

Neste documento, presume-se que você:

  1. Ativo o Artifact Registry no projeto.
  2. Ativar a API Cloud Build e a API de 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 tem esta aparência:

  1. 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 exemplo a seguir cria a imagem my-image, marca-a 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
    
  2. Os ambientes de execução do Google Cloud, como o Cloud Run e o Google Kubernetes Engine, extrai 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 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 criaçõ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 enviar uma imagem ao host. Isso também significa que a conta pode criar, ler e gravar em 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 criação que altera as etapas no fluxo de trabalho de criação 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 inclui links para mais informações sobre a modificação do fluxo de trabalho.

  1. Novo: ative a API Artifact Registry.

    Você precisa ativar a API Artifact Registry. Os ambientes do Cloud Build e do ambiente de execução como o Cloud Run e o GKE não ativam automaticamente a API.

  2. Novo: crie o repositório de destino do Docker, se ele ainda não existir. É necessário criar um repositório antes de enviar as imagens para ele. Enviar uma imagem não pode acionar 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.

  3. Alterado: crie, marque e envie uma imagem ao repositório com o Cloud Build usando um arquivo Dockerfile ou de configuração da versão.

    O exemplo de comando a seguir é igual ao exemplo do Container Registry. No entanto, usa um caminho de repositório do Artifact Registry para a imagem.

    gcloud builds submit --tag us-central1-docker.pkg.dev/my-repo/my-image:tag1
    
  4. Changed: implante a imagem em um ambiente de execução do Google Cloud, como o Cloud Run ou o GKE.

    O exemplo de comando a seguir é igual ao exemplo do Container Registry. No entanto, usa o caminho do repositório do Artifact Registry para a imagem.

    gcloud run deploy my-service --image us-central1-docker.pkg.dev/my-repo/my-image:tag1
    

Além disso, o Artifact Registry usa papéis diferentes do Container Registry para controlar o acesso a imagens. É necessário configurar permissões nas seguintes situações:

  • Os ambientes de execução do Cloud Build ou 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 Cloud Build ou 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

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 do 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 na análise de artefatos
  • Google Kubernetes Engine

Com as permissões padrão, os usuários que podem executar versões no Cloud Build, verificar contêineres com o Artifact Analysis ou implantar contêineres nos ambientes de execução do Google Cloud implicitamente têm acesso a imagens no Container Registry quando o registro está no mesmo projeto.

Artifact Registry

Você precisa ativar 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

  • É preciso 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. Você adiciona um host de registro ao enviar a primeira imagem.

  1. Para adicionar um registro como gcr.io ao seu projeto, uma conta com o papel de administrador de armazenamento no nível do projeto envia uma imagem inicial.

    Por exemplo, se o host gcr.io não existir no projeto my-project, enviar a imagem gcr.io/my-project/my-image:1.0 acionará as etapas a seguir:

    1. Adicione o host gcr.io ao projeto.
    2. Crie um bucket de armazenamento para gcr.io no projeto.
    3. Armazene a imagem como gcr.io/my-project/my-image:1.0
  2. 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. Assim, o envio inicial da imagem e os push subsequentes não podem ser diferenciados.

Em um projeto, um host de registro armazena todas as imagens no mesmo bucket de armazenamento. No exemplo a seguir, o projeto my-project tem duas imagens chamadas web-app no registro gcr.io. Um deles 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.

Uma conta com o papel 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 uma imagem não é enviada quando há um repositório ausente.

  • enviando uma imagem para us-central1-docker.pkg.dev/my-project/team1 se us-central1-docker.pkg.dev/my-project/team1 não existir.
  • Enviando uma imagem para us-central1-docker.pkg.dev/my-project/team2 quando us-central1-docker.pkg.dev/my-project/team1 existir, mas us-central1-docker.pkg.dev/my-project/team2 não existe.

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.
  • Conceda os papéis apropriados do Artifact Registry a outras contas que acessem o Artifact Registry.
  • O Container Registry é compatível com controle de acesso no nível do bucket de armazenamento. O Artifact Registry é compatível com o controle de acesso no nível do repositório.

A comparação a seguir descreve 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 de armazenamento
Extrair imagens (ler) de hosts de registro atuais no projeto.
Administrador de objetos do Storage no nível do bucket de armazenamento
Enviar (gravar) e extrair (ler) imagens para os hosts de registro existentes no projeto.
Administrador do armazenamento para envolvidos no projeto
Adicione um host de registro a um projeto enviando uma imagem inicial para ele.

Depois que a imagem inicial for enviada para um registro, você concederá papéis do Cloud Storage a outras contas que exigem acesso ao bucket de armazenamento. Qualquer conta com todas as permissões no papel de Administrador do Storage pode ler, gravar e excluir buckets de armazenamento 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 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 os próprios papéis para controlar o acesso. Esses papéis fornecem uma separação clara entre os papéis de usuário do administrador e do repositório.

O Cloud Build tem permissões no papel de gravador do Artifact Registry, já que ele só precisa enviar e extrair imagens.

Somente contas que gerenciam repositórios precisam ter o papel de administrador de repositório do Artifact Registry ou de administrador do Artifact Registry.

Leitor do Artifact Registry
Liste artefatos e repositórios. Faça o download dos artefatos.
Gravador do Artifact Registry
Liste artefatos e repositórios. Fazer o download de artefatos, fazer upload de novas versões de artefatos e adicionar ou atualizar tags.
Administrador do repositório do Artifact Registry
Permissões e permissões do gravador do Artifact Registry para excluir artefatos e tags.
Administrador do Artifact Registry
Permissões e permissões do administrador do repositório do Artifact Registry para criar, atualizar, excluir e conceder permissões aos 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 mais detalhes sobre como conceder permissões do Artifact Registry, consulte a documentação do controle de acesso.

Como criar e enviar imagens

Pontos principais

  • É preciso 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 envia com êxito uma imagem a um host de registro que ainda não existe no projeto do Google Cloud. Para este push de imagem inicial, o Cloud Build tem permissões para adicionar automaticamente o host de registro ao projeto.

Para adaptar um fluxo de trabalho do Container Registry:

  1. Configure seus repositórios antes de enviar imagens a eles.
  2. Atualize os caminhos da imagem no seu arquivo de configuração de build ou dos comandos gcloud builds submit.

Como criar com um arquivo de configuração da versão

Substitua os caminhos do Container Registry no caso de imagens criadas com o caminho para um repositório atual 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'

Depois, crie a imagem com o comando:

gcloud builds submit --config cloudbuild.yaml

Como criar com um Dockerfile

Substitua os caminhos do Container Registry no caso de imagens criadas com o caminho para um repositório atual 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-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 de imagem na configuração da implantação e nos comandos de implantação. As seções a seguir mostram exemplos de Cloud Build, Cloud Run e GKE, mas a mesma abordagem se aplica a qualquer outro serviço do Google Cloud que implante imagens.

Cloud Build

Substitua os caminhos do Container Registry no caso de imagens implantadas com o caminho em um repositório atual do Artifact Registry.

O exemplo de arquivo cloudbuild.yaml 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 no caso de imagens implantadas com o caminho em um repositório atual do Artifact Registry.

Por exemplo, esse 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 no caso de imagens criadas com o 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 a partir da 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