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

Mudanças no Docker

Neste documento, você verá as diferenças entre o Container Registry e o Artifact Registry para autenticar, enviar e extrair imagens de contêiner com o Docker.

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 para começar.

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

Antes de começar

Neste documento, presume-se que você:

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

Visão geral

Em um nível alto, 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 do Container Registry
  2. Adicione um host de registro, como "gcr.io", enviando uma imagem inicial para o host.
  3. Conceda papéis do Cloud Storage no bucket de armazenamento do host de registro para fornecer acesso a imagens.
Administrador
  1. Ativar a API Artifact Registry
  2. Adicione um repositório do Docker.
  3. Conceda papéis do Artifact Registry para fornecer acesso a imagens.
Usuários do Registro
  1. Defina a imagem como um arquivo Dockerfile.
  2. Crie a imagem.
  3. Autentique-se no registro.
  4. Marque e envie a imagem ao 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. Autentique-se no registro.
  4. Marque e envie a imagem ao registro.
  5. Extraia a imagem do registro ou implante-a em um ambiente de execução do Google Cloud.

No entanto, um atalho para o 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 em que tem permissões amplas.
  • Fluxos de trabalho que usam o Cloud Build, porque 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 do atalho tem a seguinte aparência:

  1. Ative a API Container Registry.
  2. Conceda permissões à conta que acessará o Artifact Registry.
  3. Autentique-se 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 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
    
  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 o 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 as imagens tem o papel de administrador do Storage ou um papel com as mesmas permissões, como Proprietário. As amplas permissões desse papel permitem acesso de leitura e gravação para todos os buckets de armazenamento em um projeto, incluindo buckets 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 criaçõ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 de usuário de administrador e repositório 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. Conceda permissões à conta que interagirá com o Artifact Registry.

  4. Alteração: autentique 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. Alteração: crie e marque a imagem como a imagem.

    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.

    docker build -t us-central-docker.pkg.dev/my-project/my-repo/my-image:tag1
    
  6. Changed: envie a imagem para o repositório usando o caminho do Artifact Registry. Exemplo:

    docker push us-central-docker.pkg.dev/my-project/my-repo/my-image:tag1
    
  7. Changed: envie 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 como ativar a API para cada serviço:

Container Registry

Você precisa 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 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 antes de usar clientes do 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 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.

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

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

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 há falha no envio de uma imagem para 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

  • 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 é 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 as configurações de 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 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.

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 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, você precisa especificar hosts a serem adicionados à configuração do cliente Docker.
  • Para autenticação usando docker login, use o host 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 configura apenas o Docker para nomes de host *.gcr.io por padrão. No Artifact Registry, especifique uma lista dos hosts do Artifact Registry que você quer adicionar à configuração do cliente do Docker.

Por exemplo, para configurar a autenticação nos 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 mais 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 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 no 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 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 os repositórios.

Ao enviar uma imagem, use o caminho 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 de host do Artifact Registry são diferentes dos nomes de host do Container Registry.

Ao extrair uma imagem, use o caminho 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 como implantar imagens em ambientes de execução do Google Cloud, como o Cloud Run e o GKE, consulte Como implantar imagens.