Como configurar a autenticação do Docker

Nesta página, descrevemos como configurar o Docker para autenticação nos repositórios do Docker do Artifact Registry.

Você não precisa configurar a autenticação para os ambientes de execução do Cloud Build ou do Google Cloud, como Google Kubernetes Engine e Cloud Run, mas é necessário verificar se as permissões necessárias estão configuradas de dados.

Antes de começar

  1. Ative a API Artifact Registry e instale o Cloud SDK. Consulte as instruções em Como ativar e desativar o serviço.
  2. Se não existir um repositório de destino, crie um novo repositório.
  3. Instale e inicialize o SDK do Cloud..
  4. (Opcional) Configure padrões para comandos gcloud.
  5. Verifique se a conta que você está usando para autenticação tem permissões para acessar o Artifact Registry. Recomendamos usar uma conta de serviço em vez de uma conta de usuário.
  6. Instale o Docker se ele ainda não estiver instalado. O Docker está incluído no Cloud Shell.
  7. 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 o 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:

Ajuda do gcloud credential
Configure suas credenciais do Container Registry para uso com o Docker diretamente no gcloud. Esse é o método de autenticação mais simples, mas pode ser mais lento do que o auxiliar de credenciais independente.
Auxiliar de credenciais do Docker independente
Esta opção é usada principalmente para configurar suas credenciais para uso com o Docker sem o Cloud SDK. Ele é significativamente mais rápido do que o auxiliar de credenciais do gcloud e usa o Application Default Credentials (ADC) para encontrar credenciais automaticamente no seu ambiente.
Token de acesso
É possível gerar um token de acesso de curta duração para uma conta de serviço e usá-lo para autenticação por senha. Como o token é válido apenas por 60 minutos, ele é 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 é possível usar como credencial de uma 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 credencial para reduzir o risco de acesso não autorizado às suas 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 configurações de autenticação no arquivo de configuração config.json.

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

Há diferentes seções 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 armazenará as configurações do auxiliar de credenciais na seção credHelpers do arquivo.
auths
Quando você usa o Docker para fazer login com um token ou uma chave de conta de serviço como senha, o Docker armazena uma versão codificada em base64 das credenciais no auths do arquivo.
credStore
Se você configurou um armazenamento de credenciais para gerenciar suas credenciais, as configurações do armazenamento de credenciais estarão na seção credStore do arquivo.

Quando o Docker se conecta a um registro, ele verifica primeiro se há um auxiliar de credenciais associado ao host. Portanto, se o 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 do gcloud

O auxiliar de credenciais do gcloud oferece acesso seguro e de curta duração aos recursos do projeto. Ele configura o Docker para autenticar nos hosts do Artifact Registry em qualquer ambiente em que o SDK do Cloud esteja instalado. O Cloud Shell inclui o SDK do Cloud e uma versão atual do Docker.

O auxiliar de credenciais gcloud é o método de autenticação mais simples de configurar. Ele configura o Docker com as credenciais do usuário ativo ou da conta de serviço na sua sessão do gcloud. Como esse auxiliar de credenciais depende da ferramenta gcloud, ele pode ser significativamente mais lento do que o auxiliar de credenciais autônomo. Para builds automatizados com ferramentas de terceiros ou clientes do Docker com um grande número de hosts de registro configurados, use o auxiliar de credenciais independente.

Para autenticar no Artifact Registry:

  1. Faça login no SDK do Cloud como o usuário que 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

  2. Execute este comando:

    gcloud auth configure-docker HOSTNAME-LIST
    

    Em que HOSTNAME-LIST é uma lista separada por vírgulas de nomes de host de repositório para adicionar à configuração do assistente de credenciais.

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

    gcloud auth configure-docker us-central1-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 posteriormente executando o comando novamente.

    Para ver uma lista de locais de repositório compatíveis, execute o comando:

    gcloud artifacts locations list
    
  3. O comando exibe a seção credHelpers da configuração atual do Docker e a configuração atualizada depois de adicionar os nomes do host especificados.

    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
  4. O Docker precisa que os auxiliares de credenciais estejam no sistema PATH. Verifique se o comando gcloud está no sistema PATH.

Auxiliar de credenciais independente

O auxiliar de credenciais autônomo do Docker configura o Docker para autenticar no Artifact Registry em um sistema em que o SDK do Cloud não está disponível. Ele é significativamente mais rápido do que o Assistente de credenciais do gcloud e usa o Application Default Credentials (ADC) para encontrar credenciais automaticamente no seu ambiente. Para outras operações que não sejam push e pull, como marcação ou listagem. Recomendamos o uso desse método de autenticação para builds automatizados com ferramentas de terceiros ou clientes do Docker 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:

  1. Faça login na máquina como o usuário que executará os comandos do Docker.

  2. 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.0
    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 --to-stdout ./docker-credential-gcr \
    > /usr/bin/docker-credential-gcr && chmod +x /usr/bin/docker-credential-gcr
    
  3. 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 nomes de host de repositório para adicionar à configuração do assistente de credenciais.

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

    docker-credential-gcr configure-docker --registries=us-central1-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 posteriormente executando o comando 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 independente de credenciais do Docker 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
  4. O Docker precisa que os auxiliares de credenciais estejam no sistema PATH. Verifique se o comando docker-credential-gcr está no sistema PATH.

  5. Para verificar se o auxiliar de credenciais pode recuperar as credenciais, execute o seguinte comando:

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

    Substitua HOSTNAME por um nome do host que você adicionou à configuração. Exemplo:

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

    Se o comando for bem-sucedido, a saída JSON retornada incluirá um token no campo Secret. Exemplo:

    {"ServerURL":"https://us-central1-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 receber imagens, verifique se as permissões estão configuradas 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, solicite-o menos de 1 hora antes de usá-lo para se conectar ao Artifact Registry.

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

  1. 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".

    Acessar a página "Contas de serviço"

  2. Conceda ao papel do Artifact Registry apropriado à conta de serviço para fornecer acesso ao repositório.

  3. Gere um token de acesso para a conta de serviço usando uma das seguintes opções:

    • Se você tiver permissões no papel Criador de tokens da conta de serviço (roles/iam.serviceAccountTokenCreator), é possível personificar uma conta de serviço para receber um token e, em seguida, autenticar como a conta de serviço.

      Linux

      Execute o seguinte comando, substituindo ACCOUNT pelo endereço de e-mail da sua conta de serviço e LOCATION pelo local regional ou multirregional do repositório.

      gcloud auth print-access-token \
          --impersonate-service-account ACCOUNT | docker login \
          -u oauth2accesstoken \
          --password-stdin https://LOCATION-docker.pkg.dev
      

      Windows

      Execute o seguinte comando, substituindo ACCOUNT pelo endereço de e-mail da sua conta de serviço e LOCATION pelo local regional ou multirregional do repositório.

      gcloud auth print-access-token
          --impersonate-service-account ACCOUNT
      
      ya29.8QEQIfY_...
      
      docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
      https://LOCATION-docker.pkg.dev
      
    • Ative uma conta de serviço na sua sessão do gcloud e receba um token de acesso.

      1. Ative a conta de serviço que você quer usar. Substitua ACCOUNT pelo endereço de e-mail da conta de serviço e KEY-FILE pelo nome do arquivo da chave da conta de serviço.

        gcloud auth activate-service-account ACCOUNT \
            --key-file=KEY-FILE
        
      2. Receber um token de acesso como credenciais ao autenticar no Artifact Registry com o Docker.

      3. Gere um token e faça a autenticação no repositório.

        Linux

        Execute o seguinte comando, substituindo LOCATION pelo local regional ou multirregional do repositório.

        gcloud auth print-access-token | docker login -u oauth2accesstoken \
            --password-stdin https://LOCATION-docker.pkg.dev
        

        Windows

        Execute o seguinte comando, substituindo LOCATION pelo local regional ou multirregional do repositório.

        gcloud auth print-access-token
        ya29.8QEQIfY_...
        
        docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
            https://LOCATION-docker.pkg.dev
        

O Docker agora está autenticado com o Artifact Registry.

Chave da conta de serviço

Uma chave de conta de serviço é um par de chaves de longa duração que você pode usar como credencial para uma conta de serviço. Ao contrário do token de acesso OAuth, a chave de uma conta de serviço não expira. Você é responsável pela segurança da chave privada e outras operações de gerenciamento de chaves, como a rotação de chaves.

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 o papel específico do Artifact Registry para o 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:

  1. 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".

    Acessar a página "Contas de serviço"

  2. 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 de chave original, e NEW-FILE-NAME é o arquivo de chave codificado em base64.

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

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

    Linux / macOS

    Execute este comando:

    cat KEY-FILE | docker login -u KEY-TYPE --password-stdin \
    https://LOCATION-docker.pkg.dev
    

    Ou, para clientes mais antigos do Docker que não são compatíveis --password-stdin:

    docker login -u KEY-TYPE -p "$(cat FILE-NAME.json)" \
    https://LOCATION-docker.pkg.dev
    

    Onde

    • 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 local regional ou multirregional do repositório em que a imagem está armazenada.

    Windows

    Execute este comando:

    docker login -u KEY-TYPE --password-stdin https://LOCATION-docker.pkg.dev < KEY-FILE
    

    Ou, para clientes mais antigos do Docker que não são compatíveis --password-stdin:

    set /p PASS=<KEY-FILE
    docker login -u KEY-TYPE -p "%PASS%" https://LOCATION-docker.pkg.dev
    

    Onde

    • 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 local regional ou multirregional do repositório em que a imagem está armazenada.

O Docker agora está autenticado com o Artifact Registry.