Mudanças no Docker

Neste documento, você conhecerá 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, em repositórios regulares do Artifact Registry que são independentes do Container Registry e compatíveis com 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, mas ainda será preciso Tenha em mente algumas diferenças no fluxo de trabalho, como:

  • Criação de repositórios: no Artifact Registry, só é possível enviar imagens para um repositório existente.
  • Permissões: o Artifact Registry tem permissões próprias para controlar o acesso aos repositórios.

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 Alterações no Cloud Build, Cloud Run e GKE de dados.

Use essas informações para adaptar os comandos, a configuração ou a documentação atual voltada ao Container Registry com o Docker.

Antes de começar

Veja o que é necessário para seguir este documento:

  1. ativou o Artifact Registry no projeto;
  2. Instalou o Docker. O Docker está incluído no Cloud Shell.

Visão geral

Em geral, o fluxo de trabalho para usar o Docker com o Container Registry ou o Artifact Registry é o mesmo.

Container Registry Artifact Registry
Administrador
  1. Ativar a API Container Registry
  2. Adicione um host de registro, como "gcr.io", enviando uma imagem inicial ao host.
  3. Conceda papéis do Cloud Storage no bucket de armazenamento do host do registro para fornecer acesso a imagens.
Administrador
  1. Ative a API Artifact Registry
  2. Adicione um repositório do Docker.
  3. Conceda papéis do Artifact Registry para conceder acesso a imagens.
Usuários do registro
  1. Defina a imagem como um arquivo Dockerfile.
  2. Crie a imagem.
  3. Faça a autenticação no registro.
  4. Marcar e enviar a imagem para o registro.
  5. Extraia a imagem do registro ou implante-a em um ambiente de execução do Google Cloud.
Usuários do registro
  1. Defina a imagem como um arquivo Dockerfile.
  2. Crie a imagem.
  3. Faça a autenticação no registro.
  4. Marcar e enviar a imagem para o registro.
  5. Extraia a imagem do registro ou implante-a em um ambiente de execução do Google Cloud.

No entanto, um atalho do Container Registry combina os papéis 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 com permissões amplas.
  • Fluxos de trabalho 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 atalho tem esta aparência:

  1. Ative a API Container Registry.
  2. Conceda permissões à conta que acessará o Artifact Registry.
  3. Faça a autenticação no registro. A opção de autenticação mais simples é usar o auxiliar de credenciais do Docker no SDK do Cloud. Esta é uma etapa de configuração única.

    gcloud auth configure-docker
    
  4. Crie e atribua uma tag à 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
    
  5. 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 adicionará o host antes de fazer upload da imagem.

  6. Extraia a imagem do registro ou implante-a 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 permitem acesso de leitura e gravação a todos os buckets de armazenamento em um projeto, incluindo buckets nã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 registros e adicionar hosts de registro por padrão.

No Artifact Registry, há uma separação clara dos papéis de usuário de administrador e repositório que alteram as etapas no fluxo de trabalho de criação e implantação. Para adaptar o fluxo de trabalho do Container Registry no Artifact Registry, faça as alterações a seguir. Cada etapa inclui informações adicionais sobre como modificar o fluxo de trabalho.

  1. Novo: Ativar a API Artifact Registry.

    Ative a API Artifact Registry. O Cloud Build e os ambientes 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 ainda não houver um. É preciso criar um repositório antes de enviar qualquer imagem para ele. O envio de 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. Conceda permissões à conta que interagirá com o Artifact Registry.

  4. Alterado: Autenticar no repositório. Se você usar o auxiliar de credenciais no SDK do Cloud, especifique os hosts que quer adicionar à configuração do cliente do Docker. Por exemplo, este comando adiciona o host us-central-docker.pkg.dev:

    gcloud auth configure-docker us-central-docker.pkg.dev
    
  5. Alterado: criar e marcar 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-central-docker.pkg.dev/my-project/my-repo/my-image:tag1
    
  6. Alterado: envie a imagem ao repositório usando o caminho do Artifact Registry. Exemplo:

    docker push us-central-docker.pkg.dev/my-project/my-repo/my-image:tag1
    
  7. Alterado: extraia a imagem do repositório usando o caminho do Artifact Registry. Exemplo:

    docker pull us-central-docker.pkg.dev/my-project/my-repo/my-image:tag1
    

Ative a API

Pontos principais

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 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

É 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 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.

    Uma etapa de criação de registro geralmente é excluída na documentação que descreve o envio de imagens para o Container Registry porque uma conta com permissões de administrador do Storage pode adicionar um registro a um projeto com o envio inicial para o host do 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.

  1. Para adicionar um registro como gcr.io ao seu projeto, uma conta com o papel 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 seguintes etapas:

    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
  2. Após esse envio inicial, é possível conceder permissões ao bucket de armazenamento de outros usuários.

Dentro de 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 fica 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

Uma conta com o papel Administrador de 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.

  • Enviar uma imagem para us-central1-docker.pkg.dev/my-project/team1 se us-central1-docker.pkg.dev/my-project/team1 não existir.
  • Enviar 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

  • 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, não é possível criar repositórios na conta de serviço padrão do Cloud Build.
  • O Container Registry é compatível com o 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 a configuração de permissões em cada serviço:

Container Registry

O Container Registry usa os papéis do Cloud Storage para controlar o acesso.

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

Após o envio da imagem inicial para um registro, você concede papéis do Cloud Storage a outras contas que exigem acesso ao bucket de armazenamento. Qualquer conta com todas as permissões no papel Administrador de armazenamento 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 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 as próprias funções para controlar o acesso. Esses papéis fornecem separação clara entre papéis de usuário administrador e de repositório.

Somente contas que gerenciam repositórios devem ter o papel de Administrador de repositórios do Artifact Registry ou Administrador do Artifact Registry.

Leitor do Artifact Registry
Liste artefatos e repositórios. Faça o download de artefatos.
Gravador do Artifact Registry
Liste artefatos e repositórios. Faça o download de artefatos, faça upload de novas versões deles e adicione ou atualize tags.
Administrador do repositório do Artifact Registry
Permissões do Artifact Registry Writer e permissões 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 aos repositórios.

É possível aplicar essas permissões no nível do repositório. Exemplo:

  • Conceda 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 do controle de acesso.

Como autenticar no registro

Pontos principais

  • O Artifact Registry é compatível com os mesmos métodos de autenticação que o Container Registry.
  • Para o auxiliar de credenciais do Docker, é preciso especificar os hosts a serem 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

O comando gcloud auth configure-docker e o auxiliar de credenciais autônomo só configuram o Docker para nomes de host *.gcr.io por padrão. No caso do Artifact Registry, você precisa especificar uma lista de hosts do Artifact Registry que você quer adicionar à configuração do cliente do Docker.

Por exemplo, para configurar a autenticação para repositórios do Docker na região us-central1, execute o seguinte comando:

gcloud auth configure-docker us-central1-docker.pkg.dev

Se você adicionar repositórios em us-east1 e asia-east1 posteriormente, 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 saber mais sobre os métodos de autenticação do Artifact Registry, consulte Como configurar a autenticação no Docker.

Como usar a autenticação de senha

Ao fazer login no Docker, use o nome do host do Artifact Registry em vez de um nome de 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 incluir tags em imagens

Pontos principais: - O Artifact Registry usa um nome de host diferente para repositórios.

Ao marcar uma imagem, use o caminho do Artifact Registry em vez do caminho do Container Registry. Exemplo:

docker tag my-image us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

Enviar imagens para o registro

Pontos principais: - No Artifact Registry, o repositório de destino precisa existir antes de você enviar uma imagem para ele. - O Artifact Registry usa um nome de host diferente para repositórios.

Ao enviar uma imagem por push, use o caminho do Artifact Registry em vez do caminho 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 do 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 caminho do Container Registry. Exemplo:

docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

Para exemplos de implantação de imagens nos ambientes de execução do Google Cloud, como o Cloud Run e o GKE, consulte Como implantar imagens.