Alterações ao Docker

Este documento explica as diferenças entre o Container Registry e o Artifact Registry para autenticar, enviar e extrair imagens de contentores com o Docker.

Neste guia, as comparações focam-se nos repositórios do pkg.devArtifact Registry, que são repositórios normais do Artifact Registry independentes do Container Registry e suportam todas as funcionalidades do Artifact Registry.

Se o seu administrador configurou repositórios com suporte do domínio gcr.io, os pedidos para os nomes de anfitrião gcr.io são automaticamente redirecionados para um repositório do Artifact Registry correspondente. Para usar um repositório gcr.io alojado no Artifact Registry, tem de ter uma função do Artifact Registry adequada ou uma função com autorizações equivalentes.

Para saber mais sobre as diferenças entre o Container Registry e o Artifact Registry ao criar com o Cloud Build e implementar no Cloud Run ou no Google Kubernetes Engine, consulte o artigo Alterações para o Cloud Build, o Cloud Run e o GKE.

Use estas informações para ajudar a adaptar os comandos, a configuração ou a documentação existentes focados no Container Registry com o Docker.

Antes de começar

Este documento pressupõe que:

1. Ativou o Artifact Registry no seu projeto.
2. Docker instalado. O Docker está incluído no Cloud Shell.

Vista geral

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

Container Registry	Artifact Registry
Administrador Ative a API Container Registry Adicione um anfitrião de registo, como `gcr.io`, enviando uma imagem inicial para o anfitrião. Conceda funções do Cloud Storage no contentor de armazenamento para que o anfitrião do registo forneça acesso às imagens.	Administrador Ative a API Artifact Registry Adicione um repositório Docker. Conceda funções do Artifact Registry para fornecer acesso a imagens.
Utilizadores do registo Defina a imagem como um ficheiro Dockerfile. Crie a imagem. Autentique-se no registo. Etiquete e envie a imagem para o registo. Extraia a imagem do registo ou implemente-a num Google Cloud tempo de execução.	Utilizadores do registo Defina a imagem como um ficheiro Dockerfile. Crie a imagem. Autentique-se no registo. Etiquete e envie a imagem para o registo. Extraia a imagem do registo ou implemente-a num Google Cloud tempo de execução.

No entanto, um atalho para o Container Registry combina as funções de administrador e utilizador num único fluxo de trabalho. Este atalho é comum em:

• Inícios rápidos e tutoriais em que está a testar num ambiente onde tem autorizações amplas.
• Fluxos de trabalho que usam o Cloud Build, uma vez que a conta de serviço do Cloud Build tem autorizações para adicionar um anfitrião do registo no mesmo Google Cloud projeto.

O fluxo de trabalho do atalho tem o seguinte aspeto:

1. Ative a API Container Registry.
2. Conceda autorizações à conta que vai aceder ao Container Registry.

3. Autentique-se no registo. A opção de autenticação mais simples é usar o auxiliar de credenciais do Docker na CLI do Google Cloud. Este é um passo de configuração único.

   gcloud auth configure-docker
   

4. Crie e etiquete a imagem. Por exemplo, este comando cria e etiqueta 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 registo. Por exemplo:

   docker push gcr.io/my-project/my-image:tag1
   

   Se o anfitrião do registo gcr.io não existir no projeto, o Container Registry adiciona o anfitrião antes de carregar a imagem.

6. Extraia a imagem do registo ou implemente-a num Google Cloud tempo de execução. Por exemplo:

   docker pull gcr.io/my-project/my-image:tag1
   

Este fluxo de trabalho baseia-se nos seguintes atalhos:

• A conta que envia imagens tem a função de administrador de armazenamento ou uma função com as mesmas autorizações, como proprietário. As autorizações abrangentes desta função permitem o acesso de leitura e escrita a todos os contentores de armazenamento num projeto, incluindo contentores que não são usados pelo Container Registry.
• Quando ativa algumas Google Cloud APIs, a API Container Registry é ativada automaticamente. Isto significa que os utilizadores destes serviços têm acesso implícito ao Container Registry no mesmo projeto. Por exemplo, os utilizadores que podem executar compilações no Cloud Build podem enviar imagens para registos e adicionar anfitriões de registos por predefinição.

No Artifact Registry, existe uma separação clara das funções de utilizador de administrador e de repositório que altera os passos no fluxo de trabalho de compilação e implementação. Para adaptar o fluxo de trabalho do Container Registry ao Artifact Registry, faça as seguintes alterações. Cada passo inclui um link para informações adicionais sobre a modificação do fluxo de trabalho.

1. Novo: ative a API Artifact Registry.

   Tem de ativar a API Artifact Registry. O Cloud Build e os ambientes de tempo de execução, como o Cloud Run e o GKE, não ativam automaticamente a API por si.

2. Novo: crie o repositório Docker de destino, se ainda não existir. Tem de criar um repositório antes de poder enviar imagens para o mesmo. 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 autorizações para criar repositórios.

3. Conceda autorizações à conta que vai interagir com o Artifact Registry.

4. Alterado: autentique-se no repositório. Se usar o auxiliar de credenciais na CLI gcloud, tem de especificar os anfitriões que quer adicionar à configuração do cliente Docker. Por exemplo, este comando adiciona o anfitrião us-central1-docker.pkg.dev:

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

5. Alterado: crie e etiquete a imagem.

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

   docker build -t us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
   

6. Changed (Alterado): envie a imagem para o repositório através do caminho do Artifact Registry. Por exemplo:

   docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
   

7. Alterado: extraia a imagem do repositório através do caminho do Artifact Registry. Por exemplo:

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

Ativar a API

Pontos-chave:

• Tem de ativar a API Artifact Registry além da API para outros Google Cloud serviços, como o Cloud Build, o Cloud Run e o GKE.

A comparação seguinte descreve a ativação da API para cada serviço:

Container Registry

Tem de ativar a API Container Registry antes de usar o Docker ou outros clientes de terceiros com o Container Registry.

Quando ativa as seguintes Google Cloud APIs, a API Container Registry também é ativada automaticamente:

• Ambiente flexível do App Engine
• Cloud Build
• Funções do Cloud Run
• Cloud Run
• Análise de contentores ou análise a pedido na análise de artefactos
• Google Kubernetes Engine

Com as autorizações predefinidas, os utilizadores que podem executar compilações no Cloud Build, analisar contentores com a análise de artefactos ou implementar contentores emGoogle Cloud tempos de execução têm implicitamente acesso a imagens no Container Registry quando o registo está no mesmo projeto.

Artifact Registry

Tem de ativar a API Artifact Registry antes de usar clientes Docker ou outros Google Cloud serviços com o Artifact Registry.

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

Pode ativar várias APIs no mesmo projeto através do 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

Adicionar registos e repositórios

Pontos-chave:

• Tem de criar um repositório Docker do Artifact Registry antes de enviar uma imagem para o mesmo.

  Geralmente, é excluído um passo de criação de registo na documentação que descreve o envio de imagens para o Container Registry, porque uma conta com autorizações de administrador de armazenamento pode adicionar um registo a um projeto com o envio inicial para o anfitrião do registo.

• O Container Registry armazena todas as imagens numa única região múltipla no mesmo contentor de armazenamento. No Artifact Registry, pode criar vários repositórios na mesma região ou multirregião com políticas de acesso separadas.

A comparação seguinte descreve a configuração do repositório em cada serviço:

Container Registry

No Container Registry, pode adicionar até quatro anfitriões de registo ao seu projeto. Adiciona um anfitrião do registo enviando a primeira imagem.

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

   Por exemplo, se o anfitrião gcr.io não existir no projeto my-project, o envio da imagem gcr.io/my-project/my-image:1.0 aciona os seguintes passos:

   1. Adicione o anfitrião gcr.io ao projeto
   2. Crie um contentor de armazenamento para gcr.io no projeto.
   3. Armazene a imagem como gcr.io/my-project/my-image:1.0

2. Após este envio inicial, pode conceder autorizações ao contentor de armazenamento para outros utilizadores.

Num projeto, um anfitrião do registo armazena todas as imagens no mesmo contentor de armazenamento. No exemplo seguinte, o projeto my-project tem duas imagens denominadas web-app no registo 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

Uma conta com a função de administrador do repositório do Artifact Registry tem de criar o repositório antes de enviar imagens para o mesmo. Em seguida, pode conceder autorizações ao repositório para outros utilizadores.

No Artifact Registry, cada repositório é um recurso separado. Por conseguinte, todos os caminhos de imagens têm de incluir um repositório.

Caminhos de imagens 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 da imagem inválido (não inclui um repositório) :

us-central1-docker.pkg.dev/my-project/web-app:1.0

Os exemplos seguintes mostram situações em que o envio de uma imagem para um repositório em falta 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.

Conceder autorizações

Pontos-chave:

• Conceda a função adequada do Artifact Registry à conta que está a usar com o Artifact Registry.
• Google Cloud serviços têm acesso de leitura ou escrita equivalente a ambos os registos: o Container Registry e o Artifact Registry. No entanto, a conta de serviço do Cloud Build predefinida não pode criar repositórios.
• O Container Registry suporta o controlo de acesso ao nível do contentor de armazenamento. O Artifact Registry suporta o controlo de acesso ao nível do repositório.

A comparação seguinte descreve a configuração das autorizações em cada serviço:

Container Registry

O Container Registry usa as funções do Cloud Storage para controlar o acesso.

Storage Object Viewer ao nível do contentor de armazenamento

Extrair (ler) imagens de anfitriões de registo existentes no projeto.

Storage Legacy Bucket Writer ao nível do contentor de armazenamento

Enviar (escrever) e extrair (ler) imagens para anfitriões de registo existentes no projeto.

Administrador de armazenamento ao nível do projeto

Adicione um anfitrião de registo a um projeto enviando uma imagem inicial para o anfitrião.

Após o envio inicial da imagem para um registo, concede funções do Cloud Storage a outras contas que requerem acesso ao contentor de armazenamento. Tenha em atenção que qualquer conta com todas as autorizações na função de administrador de armazenamento pode ler, escrever e eliminar contentores de armazenamento e objetos de armazenamento em todo o projeto.

As autorizações num contentor de armazenamento aplicam-se a todos os repositórios no registo. Por exemplo, qualquer utilizador com autorizações de visualizador de objetos de armazenamento no contentor 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 suas próprias funções para controlar o acesso. Estas funções permitem uma separação clara entre as funções de utilizador de administrador e de repositório.

Apenas as contas que gerem repositórios devem ter a função de administrador do repositório do Artifact Registry ou administrador do Artifact Registry.

Leitor do Artifact Registry

Apresentar artefactos e repositórios. Transferir artefactos.

Escritor do Artifact Registry

Apresentar artefactos e repositórios. Transferir artefactos, carregar novas versões de artefactos e adicionar ou atualizar etiquetas.

Administrador do repositório do Artifact Registry

Autorizações de gravação do Artifact Registry e autorizações para eliminar artefactos e etiquetas.

Administrador do Artifact Registry

Autorizações de administrador do repositório do Artifact Registry e autorizações para criar, atualizar, eliminar e conceder autorizações a repositórios.

Pode aplicar estas autorizações ao nível do repositório. Por exemplo:

• Conceda acesso à equipa 1 para us-central1-docker.pkg.dev/my-project/team1
• Conceda acesso à equipa 2 para us-central1-docker.pkg.dev/my-project/team2.

Para ver detalhes sobre a concessão de autorizações do Artifact Registry, consulte a documentação de controlo de acesso.

Autenticação no registo

Pontos-chave:

• O Artifact Registry suporta os mesmos métodos de autenticação que o Container Registry.
• Para o auxiliar de credenciais do Docker, tem de especificar os anfitriões a adicionar à configuração do cliente do Docker.
• Para a autenticação com o docker login, use o anfitrião do Artifact Registry em vez de um anfitrião do Container Registry.

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 anfitriões *.gcr.io por predefinição. Para o Artifact Registry, tem de especificar uma lista dos anfitriões do Artifact Registry que quer adicionar à configuração do cliente 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 adicionar repositórios mais tarde em us-east1 e asia-east1, tem de executar novamente o comando para adicionar os nomes de anfitrião regionais correspondentes à sua configuração do Docker.

gcloud auth configure-docker us-east-docker.pkg.dev,asia-east1-docker.pkg.dev

Para ver detalhes sobre os métodos de autenticação do Artifact Registry, consulte o artigo Configurar a autenticação para o Docker.

Usar a autenticação por palavra-passe

Quando iniciar sessão no Docker, use o nome de anfitrião do Artifact Registry em vez de um nome de anfitrião *.gcr.io. O exemplo seguinte mostra a autenticação com uma chave de conta de serviço codificada em base64 para o anfitrião us-central1-docker.pkg.dev:

cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-central1-docker.pkg.dev

Criar e etiquetar imagens

Pontos importantes: - O Artifact Registry usa um nome de anfitrião diferente para os repositórios.

Quando etiquetar uma imagem, use o caminho do Artifact Registry em vez do caminho do Container Registry. Por exemplo:

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

Enviar imagens para o registo

Pontos importantes: - No Artifact Registry, o repositório de destino tem de existir antes de enviar uma imagem para o mesmo. – O Artifact Registry usa um nome do anfitrião diferente para os repositórios.

Quando envia uma imagem, use o caminho do Artifact Registry em vez do caminho do Container Registry. Por exemplo:

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

Extrair imagens do registo

Ponto-chave:

• Os nomes de anfitrião do Artifact Registry são diferentes dos nomes de anfitrião do Container Registry.

Quando extrai uma imagem, use o caminho do Artifact Registry em vez do caminho do Container Registry. Por exemplo:

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

Para ver exemplos de implementação de imagens em Google Cloud tempos de execução, como o Cloud Run e o GKE, consulte Implementar imagens.