Nesta página, descrevemos como configurar o Docker para autenticação no Artifact Registry. repositórios do Docker.
Você não precisa configurar a autenticação para o Cloud Build ou o Google Cloud ambientes de execução, como o Google Kubernetes Engine e o Cloud Run, mas recomendamos verifique se as permissões necessárias estão configurados.
Antes de começar
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- (Opcional) Configure padrões para comandos da CLI gcloud.
- Verifique se a conta que você está usando para autenticação tem permissões para acessar o Artifact Registry. Recomendamos o uso de uma conta de serviço em vez de do que uma conta de usuário.
- Instale o Docker se ele ainda não estiver instalado. Ele está incluído no Cloud Shell.
O Docker requer acesso com privilégios para interagir com registros. No Linux ou no Windows, adicione o usuário utilizado para executar comandos do Docker no grupo de segurança do Docker. Esta etapa não é necessária no macOS, porque O Docker Desktop é executado em uma máquina virtual como usuário raiz.
Linux
O grupo de segurança do Docker é chamado de
docker
. Para adicionar seu nome de usuário, execute o seguinte comando:sudo usermod -a -G docker ${USER}
Windows
O grupo de segurança do Docker é chamado de
docker-users
. Para adicionar um usuário a partir do prompt de comando do administrador, execute o seguinte comando:net localgroup docker-users DOMAIN\USERNAME /add
Em que
- DOMAIN é seu domínio do Windows.
- USERNAME é seu nome de usuário.
Saia e acesse novamente para a mudança de filiação ao grupo fazer efeito. Se estiver usando uma máquina virtual, talvez seja necessário reiniciar a máquina virtual para a mudança fazer efeito;
Como escolher um método de autenticação
Os seguintes métodos de autenticação estão disponíveis:
- Auxiliar de credenciais da CLI gcloud
- Configurar suas credenciais do Artifact Registry para uso com Docker diretamente na CLI gcloud. Esse é o método de autenticação mais simples, pode ser mais lento que o auxiliar de credenciais autônomo.
- Auxiliar de credenciais do Docker independente
- Essa opção serve principalmente para configurar suas credenciais para uso com o Docker na ausência da Google Cloud CLI. É significativamente mais rápido do que a CLI gcloud auxiliar de credenciais e usa o Application Default Credentials (ADC) para encontrar automaticamente credenciais no seu ambiente.
- Token de acesso
- É possível gerar um token de acesso de curta duração para uma conta de serviço e, use o token para autenticação por senha. Como o token só é válido por 60 minutos, é uma opção mais segura do que uma chave de conta de serviço.
- Chave da conta de serviço
- Um par de chaves gerenciado pelo usuário que pode ser usado como credencial de um conta de serviço. Como a credencial é longa, é a opção menos segura de todos os métodos de autenticação disponíveis.
Quando possível, use um token de acesso ou um auxiliar de credenciais para reduzir o risco de acesso não autorizado às imagens de contêiner. Se você precisar usar uma chave de conta de serviço, siga as práticas recomendadas para gerenciar as credenciais.
Configurações de autenticação no arquivo de configuração do Docker
O Docker salva as definições de autenticação no arquivo de configuração config.json.
- Linux:
~/.docker/config.json
- Windows:
%USERPROFILE%\.docker\config.json
Há seções separadas no arquivo para diferentes métodos de autenticação:
credHelpers
- Se você usar o auxiliar de credenciais do Docker para autenticação
O Artifact Registry armazena as configurações do auxiliar de credenciais no
credHelpers
do arquivo. auths
- Se você usa o Docker para fazer login com um token ou uma chave da conta de serviço como seu
senha, o Docker armazena uma versão codificada em base64 de suas credenciais no
auths
do arquivo. credStore
- Se você configurou um
armazenamento de credenciais
para gerenciar suas credenciais, as configurações do armazenamento de credenciais estão em
a seção
credStore
do arquivo.
Quando o Docker se conecta a um registro, ele verifica primeiro se há um auxiliar de credenciais
que está associado ao host. Portanto, se config.json
incluir
Configurações do Artifact Registry nas seções credHelpers
e auths
as configurações na seção auths
serão ignoradas.
Auxiliar de credenciais da CLI gcloud
O auxiliar de credenciais da CLI gcloud fornece acesso seguro e de curta duração aos recursos do projeto. Ele configura o Docker para autenticação em O Artifact Registry hospeda em qualquer ambiente em que a Google Cloud CLI esteja instalada. Cloud Shell inclui a Google Cloud CLI e uma versão atual do Docker.
O auxiliar de credenciais da CLI gcloud é o método de autenticação mais simples de configurar. Ele configura o Docker com as credenciais da conta de serviço ou do usuário ativo. na sessão da CLI gcloud. Como esse auxiliar de credenciais depende CLI gcloud, ela pode ser significativamente mais lenta do que auxiliar de credenciais autônoma. Para builds automatizados com ferramentas de terceiros ou clientes Docker com um grande número de registros hosts, use o auxiliar de credenciais autônomo em seu lugar.
Para autenticar no Artifact Registry:
Faça login na CLI gcloud como o usuário que vai executar os comandos do Docker.
Para configurar a autenticação com credenciais de usuário, execute o seguinte comando:
gcloud auth login
Para configurar a autenticação com credenciais da conta de serviço, execute o seguinte comando:
gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
Onde
- ACCOUNT é a conta de serviço que você quer usar com
o Artifact Registry no formato
USERNAME@PROJECT-ID.iam.gserviceaccount.com
. Se você quiser usar uma conta existente, veja uma lista de serviços no Contas de serviço do console do Google Cloud ou com o comandogcloud iam service-accounts list
- KEY-FILE é o arquivo de chave da conta de serviço. Consulte a documentação do gerenciamento de identidade e acesso (IAM, na sigla em inglês) para informações sobre como criar uma chave.
- ACCOUNT é a conta de serviço que você quer usar com
o Artifact Registry no formato
Execute este comando:
gcloud auth configure-docker HOSTNAME-LIST
Em que HOSTNAME-LIST é uma lista separada por vírgulas de repositórios nomes de host para adicionar à configuração do auxiliar de credenciais.
Por exemplo, para adicionar as regiões
us-west1
easia-northeast1
, execute o comando:gcloud auth configure-docker us-west1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
Os nomes de host especificados são adicionados à configuração do auxiliar de credenciais. É possível adicionar outros nomes de host à configuração mais tarde executando o novamente.
Para ver uma lista de locais de repositório compatíveis, execute o comando:
gcloud artifacts locations list
O comando mostra a seção
credHelpers
do Docker atual. e a configuração atualizada após a adição do nomes de host.Para aceitar as mudanças de configuração, digite
y
.Suas credenciais são salvas no diretório inicial do usuário.
- Linux:
$HOME/.docker/config.json
- Windows:
%USERPROFILE%/.docker/config.json
- Linux:
O Docker precisa que os auxiliares de credenciais estejam no sistema
PATH
. Verifique se o comandogcloud
está no sistemaPATH
.
Auxiliar de credenciais independente
O auxiliar de credenciais autônomo do Docker configura o Docker para autenticação para o Artifact Registry em um sistema em que a CLI gcloud não está disponível. É significativamente mais rápido do que o auxiliar de credenciais da CLI gcloud e usa o Application Default Credentials (ADC) para encontrar automaticamente credenciais no seu ambiente. Para operações que não sejam push extrair imagens, por exemplo, marcando ou listando imagens; Recomendamos o uso deste método de autenticação para builds automatizados com ferramentas de terceiros ou do Docker clientes com um grande número de hosts de registro configurados.
O auxiliar de credenciais independente do Docker busca suas credenciais do Artifact Registry
e as grava no arquivo de configuração do Docker. Dessa forma, você
pode usar a ferramenta de linha de comando do Docker, docker
, para interagir diretamente com
o Artifact Registry.
Para usar o auxiliar de credenciais do Docker:
Faça login na máquina como o usuário que executará os comandos do Docker.
Faça o download do auxiliar de credenciais independente do Docker no GitHub.
Opcionalmente, você pode usar o utilitário de linha de comando
curl
. Por exemplo:VERSION=2.1.23 OS=linux # or "darwin" for OSX, "windows" for Windows. ARCH=amd64 # or "386" for 32-bit OSs curl -fsSL "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \ | tar xz docker-credential-gcr \ && chmod +x docker-credential-gcr && sudo mv docker-credential-gcr /usr/bin/
Configure o Docker para usar as credenciais do Artifact Registry ao interagir com ele. Você só precisa fazer isso uma vez:
docker-credential-gcr configure-docker --registries=HOSTNAME-LIST
Em que HOSTNAME-LIST é uma lista separada por vírgulas de repositórios nomes de host para adicionar à configuração do auxiliar de credenciais.
Por exemplo, para adicionar as regiões
us-west1
easia-northeast1
, execute o comando:docker-credential-gcr configure-docker --registries=us-west1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
Os nomes de host especificados são adicionados à configuração do auxiliar de credenciais. É possível adicionar outros nomes de host à configuração mais tarde executando o novamente.
Para ver uma lista de locais de repositório compatíveis, execute o comando:
gcloud artifacts locations list
Consulte a documentação do auxiliar de credenciais do Docker independente no GitHub para mais informações.
Suas credenciais são salvas no diretório inicial do usuário.
- Linux:
$HOME/.docker/config.json
- Windows:
%USERPROFILE%/.docker/config.json
- Linux:
O Docker precisa que os auxiliares de credenciais estejam no sistema
PATH
. Verifique se o comandodocker-credential-gcr
está no sistemaPATH
.Para verificar se o auxiliar de credenciais pode recuperar seu credenciais, execute o seguinte comando:
echo "https://HOSTNAME" | docker-credential-gcr get
Substitua HOSTNAME por um nome do host que você adicionou ao configuração do Terraform. Exemplo:
echo "https://us-west1-docker.pkg.dev" | docker-credential-gcr get
Se o comando for bem-sucedido, a saída JSON retornada incluirá um token no o campo
Secret
. Exemplo:{"ServerURL":"https://us-west1-docker.pkg.dev","Username":"_dcgcr_2_0_0_token","Secret":"ya29..."}
O Docker agora está configurado para autenticar com o Artifact Registry. Para enviar e extrair imagens, verifique se as permissões estejam configurados corretamente.
Token de acesso
É possível gerar um token de acesso OAuth de curta duração para autenticar com o Artifact Registry. Como o token é válido por 60 minutos, você deve solicitá-lo menos de uma hora antes de usá-lo para se conectar com o Artifact Registry.
Para usar um token de acesso com credenciais de conta de serviço:
Crie uma conta de serviço para agir em nome do aplicativo. ou escolha uma conta de serviço atual para automação.
Conceda o papel específico do Artifact Registry à conta de serviço para dar acesso ao repositório.
Gere um token de acesso para a conta de serviço e faça a autenticação:
Você precisa ter as permissões do papel Criador de token da conta de serviço (
roles/iam.serviceAccountTokenCreator
) para representar uma conta de serviço, para receber um token e fazer a autenticação como a conta de serviço.Execute o comando a seguir, substituindo ACCOUNT pelo seu o endereço de e-mail da conta de serviço e LOCATION regional ou multirregional local de repositório.
Linux
gcloud auth print-access-token \ --impersonate-service-account ACCOUNT | docker login \ -u oauth2accesstoken \ --password-stdin https://LOCATION-docker.pkg.dev
Windows
gcloud auth print-access-token --impersonate-service-account ACCOUNT | docker login -u oauth2accesstoken --password-stdin https://LOCATION-docker.pkg.dev
O Docker agora está autenticado com o Artifact Registry.
Chave da conta de serviço
Qualquer pessoa que tenha acesso a uma chave privada válida para uma conta de serviço poderá acessar recursos por meio da conta de serviço. O ciclo de vida do acesso da chave à conta de serviço (e, portanto, os dados a que a conta de serviço tem acesso) independe do ciclo de vida do usuário que fez o download da chave.
Use as seguintes diretrizes para limitar o acesso aos seus repositórios:
- Crie contas de serviço dedicadas que são usadas apenas para interagir com os repositórios.
- Conceda a assinatura Papel no Artifact Registry pelo acesso exigido pela conta de serviço. Por exemplo, uma conta de serviço que faz o download apenas de artefatos requer apenas o papel de Leitor do Artifact Registry.
- Configure as permissões para suas contas de serviço dedicadas em cada repositório, e não no nível do projeto. É possível especificar o acesso com base no contexto do repositório. Por exemplo, uma conta de serviço para versões de desenvolvimento pode ter o papel de leitor do Artifact Registry para um repositório de produção e o papel de gravador do Artifact Registry para um repositório de preparo.
- Siga as práticas recomendadas para gerenciar as credenciais.
Para criar uma nova conta de serviço e uma chave de conta de serviço para uso apenas com repositórios do Container Registry:
Crie uma conta de serviço para agir em nome do seu aplicativo ou escolha uma conta de serviço atual que você usa para automação.
Você precisará do local do arquivo de chave da conta de serviço para configurar a autenticação com o Artifact Registry. Para contas existentes, é possível ver as chaves e criar novas chaves na página "Contas de serviço".
Opcionalmente, você pode codificar todo o conteúdo do arquivo de chave em base64.
Linux
base64 FILE-NAME > NEW-FILE-NAME
macOS
base64 -i FILE-NAME -o NEW-FILE-NAME
Windows
Base64.exe -e FILE-NAME > NEW-FILE-NAME
em que FILE-NAME é o nome do arquivo da chave original e NEW-FILE-NAME é seu arquivo de chave codificado em base64.
Verifique se as permissões estão configuradas corretamente para a conta de serviço. Se você estiver usando a conta de serviço do Compute Engine, precisará configurar corretamente as permissões e os escopos de acesso.
Use a chave da conta de serviço para configurar a integração com o Docker:
Execute este comando:
Linux/macOS
cat KEY-FILE | docker login -u KEY-TYPE --password-stdin \ https://LOCATION-docker.pkg.dev
Windows
Get-Content KEY-FILE | docker login -u KEY-TYPE --password-stdin https://LOCATION-docker.pkg.dev
Substitua:
- KEY-TYPE é um destes:
_json_key
se você estiver usando a chave da conta de serviço no formato JSON, conforme fornecido ao criar o arquivo._json_key_base64
se você codificou todo o conteúdo do arquivo em base64.
- KEY-FILE é o nome do arquivo de chave da conta de serviço no formato JSON.
- LOCATION é o regional ou multirregional local do repositório em que a imagem é armazenada.
- KEY-TYPE é um destes:
O Docker agora está autenticado com o Artifact Registry.