Configure a autenticação no Artifact Registry para o Docker

Esta página descreve como configurar o Docker para autenticar repositórios Docker do Artifact Registry.

Não precisa de configurar a autenticação para o Cloud Build nem Google Cloud ambientes de tempo de execução, como o Google Kubernetes Engine e o Cloud Run, mas deve verificar se as autorizações necessárias estão configuradas.

Antes de começar

  1. Instale a CLI Google Cloud. Após a instalação, inicialize a CLI gcloud executando o seguinte comando: 

    gcloud init

    Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

  2. (Opcional) Configure as predefinições para os comandos da CLI gcloud.
  3. Verifique se a conta que está a usar para a autenticação tem autorização para aceder ao Artifact Registry. Recomendamos que use uma conta de serviço em vez de uma conta de utilizador.
  4. Instale o Docker se ainda não estiver instalado. O Docker está incluído no Cloud Shell.
  5. O Docker requer acesso privilegiado para interagir com registos. No Linux ou Windows, adicione o utilizador que usa para executar comandos do Docker ao grupo de segurança do Docker. Este passo não é necessário no macOS, uma vez que o Docker Desktop é executado numa máquina virtual como utilizador root.

    Linux

    O grupo de segurança do Docker chama-se docker. Para adicionar o seu nome de utilizador, execute o seguinte comando: 

          sudo usermod -a -G docker ${USER}

    Windows

    O grupo de segurança do Docker chama-se docker-users. Para adicionar um utilizador a partir da linha de comandos do administrador, execute o seguinte comando:

            net localgroup docker-users DOMAIN\USERNAME /add

    Onde:

    • DOMAIN é o seu domínio do Windows.
    • USERNAME é o seu nome de utilizador.

    Termine sessão e inicie-a novamente para que as alterações de subscrição do grupo entrem em vigor. Se estiver a usar uma máquina virtual, pode ter de a reiniciar para que as alterações à subscrição sejam aplicadas.

Escolher um método de autenticação

Estão disponíveis os seguintes métodos de autenticação:

auxiliar de credenciais da CLI gcloud
Configure as suas credenciais do Artifact Registry para utilização com o Docker diretamente na CLI gcloud. Este é o método de autenticação mais simples, mas pode ser mais lento do que o auxiliar de credenciais autónomo.
Assistente de credenciais do Docker autónomo
Esta opção destina-se principalmente à configuração das suas credenciais para utilização com o Docker na ausência da CLI do Google Cloud. É significativamente mais rápido do que o auxiliar de credenciais da CLI gcloud e usa Credenciais padrão da aplicação (ADC) para encontrar automaticamente credenciais no seu ambiente.
Chave de acesso
Pode gerar uma chave de acesso de curta duração para uma conta de serviço e, em seguida, usar a chave para a autenticação por palavra-passe. Uma vez que o token só é válido durante 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 gerido pelo utilizador que pode usar como credencial para uma conta de serviço. Uma vez que a credencial é de longa duração, é a opção menos segura de todos os métodos de autenticação disponíveis.

Sempre que possível, use um token de acesso ou um auxiliar de credenciais para reduzir o risco de acesso não autorizado às suas imagens de contentores. Se tiver de usar uma chave de conta de serviço, certifique-se de que segue as práticas recomendadas para gerir credenciais.

Definições de autenticação no ficheiro de configuração do Docker

O Docker guarda as definições de autenticação no ficheiro de configuração config.json.

  • Linux: ~/.docker/config.json
  • Windows: %USERPROFILE%\.docker\config.json

Existem secções separadas no ficheiro para diferentes métodos de autenticação:

credHelpers
Se usar o auxiliar de credenciais do Docker para autenticação, o Artifact Registry armazena as definições do auxiliar de credenciais na secção credHelpers do ficheiro.
auths
Se usar o Docker para iniciar sessão com um token ou uma chave de conta de serviço como palavra-passe, o Docker armazena uma versão codificada em base64 das suas credenciais na secção auths do ficheiro.
credStore
Se configurou um armazenamento de credenciais para gerir as suas credenciais, as definições do armazenamento de credenciais encontram-se na secção credStore do ficheiro.

Quando o Docker se liga a um registo, verifica primeiro se existe um auxiliar de credenciais associado ao anfitrião. Assim, se o seu config.json incluir definições do Artifact Registry nas secções credHelpers e auths, as definições na secção auths são ignoradas.

Assistente de credenciais da CLI gcloud

O auxiliar de credenciais da CLI gcloud fornece acesso seguro e de curta duração aos recursos do seu projeto. Configura o Docker para autenticar em hosts do Artifact Registry em qualquer ambiente onde a CLI do Google Cloud esteja instalada. O Cloud Shell inclui a CLI Google Cloud e uma versão atual do Docker.

O auxiliar de credenciais da CLI gcloud é o método de autenticação mais simples de configurar. Configura o Docker com as credenciais do utilizador ativo ou da conta de serviço na sua sessão da CLI gcloud. Uma vez que este auxiliar de credenciais depende da CLI gcloud, pode ser significativamente mais lento do que o auxiliar de credenciais autónomo. Para compilações automatizadas com ferramentas de terceiros ou clientes Docker com um grande número de anfitriões de registo configurados, use o auxiliar de credenciais autónomo.

Para se autenticar no Artifact Registry:

  1. Inicie sessão na CLI gcloud como o utilizador que vai executar os comandos do Docker.

  1. Execute o seguinte comando:

    gcloud auth configure-docker HOSTNAME-LIST

    Em que HOSTNAME-LIST é uma lista separada por vírgulas de nomes de anfitriões do repositório a adicionar à configuração do auxiliar de credenciais.

    Por exemplo, para adicionar as regiões us-west1 e asia-northeast1, execute o comando:

    gcloud auth configure-docker us-west1-docker.pkg.dev,asia-northeast1-docker.pkg.dev

    Os nomes de anfitrião especificados são adicionados à configuração do auxiliar de credenciais. Pode adicionar outros nomes de anfitrião à configuração mais tarde executando novamente o comando.

    Para ver uma lista de localizações de repositórios suportadas, execute o comando:

    gcloud artifacts locations list

  2. O comando apresenta a secção credHelpers da sua configuração atual do Docker e a configuração atualizada após adicionar os nomes de anfitrião especificados.

    Para aceitar as alterações de configuração, introduza y.

    As suas credenciais são guardadas no diretório inicial do utilizador.

    • Linux: $HOME/.docker/config.json
    • Windows: %USERPROFILE%/.docker/config.json

  3. O Docker requer que os auxiliares de credenciais estejam no sistema PATH. Certifique-se de que o comando gcloud está no sistema PATH.

Assistente de credenciais autónomo

O auxiliar de credenciais do Docker autónomo configura o Docker para autenticar no Artifact Registry num sistema onde a CLI gcloud não está disponível. É significativamente mais rápido do que o auxiliar de credenciais da CLI gcloud e usa as Credenciais padrão da aplicação (ADC) para encontrar automaticamente credenciais no seu ambiente. Para operações que não sejam o envio e a obtenção de imagens, como etiquetar ou listar imagens. Recomendamos a utilização deste método de autenticação para compilações automáticas com ferramentas de terceiros ou clientes Docker com um grande número de anfitriões de registo configurados.

O auxiliar de credenciais do Docker autónomo obtém as suas credenciais do Artifact Registry e escreve-as no ficheiro de configuração do Docker. Desta forma, pode usar a ferramenta de linha de comandos do Docker, docker, para interagir diretamente com o Artifact Registry.

Para usar o auxiliar de credenciais do Docker:

  1. Inicie sessão no computador como o utilizador que vai executar os comandos do Docker.

  2. Transfira o assistente de credenciais do Docker autónomo a partir do GitHub.

    Opcionalmente, pode usar o utilitário de linha de comandos curl. Por exemplo:

    VERSION=2.1.29
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/

  3. Configure o Docker para usar as suas credenciais do Artifact Registry quando interagir com o Artifact Registry (só tem de o fazer uma vez):

    docker-credential-gcr configure-docker --registries=HOSTNAME-LIST

    Em que HOSTNAME-LIST é uma lista separada por vírgulas de nomes de anfitriões do repositório a adicionar à configuração do auxiliar de credenciais.

    Por exemplo, para adicionar as regiões us-west1 e asia-northeast1, execute o comando:

    docker-credential-gcr configure-docker --registries=us-west1-docker.pkg.dev,asia-northeast1-docker.pkg.dev

    Os nomes de anfitrião especificados são adicionados à configuração do auxiliar de credenciais. Pode adicionar outros nomes de anfitrião à configuração mais tarde executando novamente o comando.

    Para ver uma lista de localizações de repositórios suportadas, execute o comando:

    gcloud artifacts locations list

    Consulte a documentação de ajuda de credenciais do Docker autónomo no GitHub para mais informações.

    As suas credenciais são guardadas no diretório inicial do utilizador.

    • Linux: $HOME/.docker/config.json
    • Windows: %USERPROFILE%/.docker/config.json

  4. O Docker requer que os auxiliares de credenciais estejam no sistema PATH. Certifique-se de que o comando docker-credential-gcr está no sistema PATH.

  5. Para verificar se o auxiliar de credenciais consegue obter as suas credenciais com êxito, execute o seguinte comando:

    echo "https://HOSTNAME" | docker-credential-gcr get

    Substitua HOSTNAME por um nome do anfitrião que adicionou à configuração. Por exemplo:

    echo "https://us-west1-docker.pkg.dev" | docker-credential-gcr get

    Se o comando for bem-sucedido, o resultado JSON devolvido inclui um token no campo Secret. Por exemplo:

    {"ServerURL":"https://us-west1-docker.pkg.dev","Username":"_dcgcr_2_0_0_token","Secret":"ya29..."}

O Docker está agora configurado para autenticar com o Artifact Registry. Para enviar e receber imagens, certifique-se de que as autorizações estão configuradas corretamente.

Chave de acesso

Pode gerar um token de acesso OAuth de curta duração para fazer a autenticação no Artifact Registry. Uma vez que o token é válido durante 60 minutos, deve solicitá-lo menos de uma hora antes de o usar para estabelecer ligação ao Artifact Registry.

Para usar um token de acesso com credenciais da conta de serviço:

  1. Crie uma conta de serviço para agir em nome da sua aplicação ou escolha uma conta de serviço existente que use para automatização.

  2. Conceda a função do Artifact Registry específica à conta de serviço para fornecer acesso ao repositório.

  3. Gere um token de acesso para a conta de serviço e autentique:

    Tem de ter as autorizações na função Criador de tokens de contas de serviço (roles/iam.serviceAccountTokenCreator) para roubar a identidade de uma conta de serviço, para obter um token para a mesma e, em seguida, autenticar-se como a conta de serviço.

    Execute o seguinte comando, substituindo ACCOUNT pelo seu endereço de email da conta de serviço e LOCATION pela localização regional ou multirregional do 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 está agora 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 pode aceder a recursos através da conta de serviço. Tenha em atenção que o ciclo de vida do acesso da chave à conta de serviço (e, por conseguinte, aos dados aos quais a conta de serviço tem acesso) é independente do ciclo de vida do utilizador que transferiu a chave.

Use as seguintes diretrizes para limitar o acesso aos seus repositórios:

  • Crie contas de serviço dedicadas que só são usadas para interagir com repositórios.
  • Conceda a função do Artifact Registry específica para o acesso exigido pela conta de serviço. Por exemplo, uma conta de serviço que transfere apenas artefactos requer apenas a função Leitor do Artifact Registry.
  • Configure as autorizações das suas contas de serviço dedicadas em cada repositório, em vez de ao nível do projeto. Em seguida, pode especificar o acesso com base no contexto do repositório. Por exemplo, uma conta de serviço para compilações de desenvolvimento pode ter a função Leitor do Artifact Registry para um repositório de produção e a função Escritor do Artifact Registry para um repositório de preparação.
  • Siga as práticas recomendadas para gerir credenciais.

Para criar uma nova conta de serviço e uma chave de conta de serviço para utilização apenas com repositórios do Artifact Registry:

  1. Crie uma conta de serviço para agir em nome da sua aplicação ou escolha uma conta de serviço existente que use para automatização.

    Precisa da localização do ficheiro de chave da conta de serviço para configurar a autenticação com o Artifact Registry. Para contas existentes, pode ver as chaves e criar novas chaves na página Contas de serviço.

    Aceda à página Contas de serviço

  2. Opcionalmente, pode codificar em base64 todo o conteúdo do ficheiro de chave.

    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

    Onde FILE-NAME é o nome do ficheiro da chave original e NEW-FILE-NAME é o ficheiro da chave codificado em Base64.

  3. Verifique se as autorizações estão configuradas corretamente para a conta de serviço. Se estiver a usar a conta de serviço do Compute Engine, tem de configurar corretamente as autorizações e os âmbitos de acesso.

  4. Use a chave da conta de serviço para configurar a integração com o Docker:

    Execute o seguinte 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 o seguinte:

    • KEY-TYPE é uma das seguintes opções:
      • _json_key se estiver a usar a chave da conta de serviço no formato JSON, tal como foi fornecida quando criou o ficheiro.
      • _json_key_base64 se codificou em Base64 todo o conteúdo do ficheiro.
    • KEY-FILE é o nome do ficheiro de chave da conta de serviço no formato JSON.
    • LOCATION é a localização regional ou multirregional do repositório onde a imagem está armazenada.

O Docker está agora autenticado com o Artifact Registry.