Métodos de autenticação

Esta página descreve como configurar um cliente de terceiro para autenticação com o Container Registry.

Os serviços do Google Cloud que se integram ao Container Registry são pré-configurados com permissões para acessar repositórios no mesmo projeto. Não é necessário configurar a autenticação para esses serviços, mas é necessário verificar se as permissões estão configuradas corretamente.

Antes de começar

  1. A conta que você usará na autenticação precisa ter permissões para acessar o registro. Recomendamos o uso de uma conta de serviço em vez de uma conta de usuário. As contas de serviço não estão associadas a um usuário específico, e os aplicativos do Google Cloud podem usar a estratégia Application Default Credentials para receber credenciais automaticamente.

  2. Instale a versão mais recente do SDK do Cloud. Para atualizar uma instalação existente, execute o comando gcloud components update.

  3. O Docker precisa que os auxiliares de credenciais estejam no sistema PATH. Verifique se o comando gcloud está no sistema PATH.

  4. Instale o Docker se ele ainda não estiver instalado.

  5. O Docker requer acesso com privilégios para interagir com registros. Se o Docker estiver instalado no Linux ou no Windows, adicione o usuário que você usa para executar comandos do Docker ao grupo de segurança do Docker.

    No MacOS, o Docker é executado a partir de uma máquina virtual com o usuário raiz. Portanto, essa etapa não é necessária. Para detalhes sobre o Docker no MacOS, consulte a documentação do Docker.

    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;

Métodos de autenticação

É preciso configurar qualquer cliente de terceiro que precise acessar o Container Registry.

Os seguintes métodos de autenticação estão disponíveis:

gcloud como assistente de credencial (recomendado)
Configure suas credenciais do Container Registry para uso com o Docker diretamente no gcloud. Use esse método quando possível para acesso seguro e de curta duração aos recursos do projeto. Esta opção é compatível apenas com as versões 18.03 ou posteriores do Docker.
Auxiliar de credenciais do Docker independente
Esta opção é usada principalmente para configurar suas credenciais para uso com o Docker sem o Cloud SDK. Esta opção é compatível apenas com as versões 18.03 ou posteriores do Docker.
Token de acesso
O Application Default Credentials fornece tokens de acesso de curta duração que uma conta de serviço usa para acessar seus recursos do Google Cloud. É a alternativa mais segura para usar gcloud como auxiliar de credencial.
Arquivo de chave JSON

Um par de chaves gerenciado pelo usuário que você pode usar como credencial para 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 outro método de autenticação disponível para reduzir o risco de acesso não autorizado aos seus artefatos. Se você precisar usar uma chave de conta de serviço, siga as práticas recomendadas para gerenciar as credenciais.

Algumas ferramentas ou fluxos de trabalho não fornecem um bom suporte para o uso de gcloud como um auxiliar de credencial. Se você usar uma das opções alternativas, compreenda as implicações de segurança.

Ajudantes de credenciais

Ajudantes de credenciais do Docker configuram o Docker para autenticação com um registro específico. O Container Registry fornece:

  • Um auxiliar de credencial gcloud
  • Um auxiliar de credencial autônomo para sistemas em que o SDK do Cloud não está disponível

gcloud como um auxiliar de credenciais do Docker

É altamente recomendável que você use esse método quando possível. Ele permite o acesso seguro e de curta duração aos recursos do projeto.

Use gcloud para configurar a autenticação no Cloud Shell ou em qualquer ambiente em que o SDK do Cloud esteja instalado. O Cloud Shell inclui uma versão atual do Docker.

Para configurar a autenticação:

  1. Faça login no gcloud 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
      

      Em que

  2. Configure o Docker com o seguinte comando:

    gcloud auth configure-docker
    

    Suas credenciais são salvas no diretório inicial do usuário.

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

O Docker agora está configurado para autenticar com o Container Registry. Para enviar e extrair imagens, verifique se as permissões estão configuradas corretamente.

Auxiliar de credenciais do Docker independente

O auxiliar de credenciais do Docker autônomo configura o Docker para autenticar no Container Registry em um sistema em que o SDK do Cloud não está disponível.

As credenciais do Container Registry são fornecidas ao auxiliar de credenciais automaticamente ou a partir de uma localização especificada por meio da sinalização --token-source, Em seguida, elas são gravadas no arquivo de configuração do Docker. Assim, você pode usar a ferramenta de linha de comando do Docker, docker, para interagir diretamente com o Container Registry.

Para configurar a autenticação:

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

  2. Faça o download de docker-credential-gcr versões do GitHub:

    Opcionalmente, você pode usar o utilitário de linha de comando curl. Exemplo:

    VERSION=2.0.0
    OS=linux  # or "darwin" for OSX, "windows" for Windows.
    ARCH=amd64  # or "386" for 32-bit OSs, "arm64" for ARM 64.
    
    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/local/bin/docker-credential-gcr && chmod +x /usr/local/bin/docker-credential-gcr
    
  3. Configure o Docker com o seguinte comando:

    docker-credential-gcr configure-docker
    

    Suas credenciais são salvas no diretório inicial do usuário.

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

Consulte a documentação auxiliar auxiliar de credenciais do Docker no GitHub para mais informações.

O Docker agora está configurado para autenticar com o Container Registry. Para enviar e extrair imagens, verifique se as permissões estão configuradas corretamente.

Token de acesso

Um token de acesso é uma credencial de curta duração que fornece acesso aos seus recursos do Google Cloud. Você pode usar um token de acesso como uma senha para se conectar ao Container Registry.

O Google Cloud recebe um token de acesso usando o Application Default Credentials.

  1. Obtenha a chave da conta de serviço que interage com o Container Registry.

    Console

    1. No Google Cloud Console, abra a página Criar chave de conta de serviço.

      Acessar página "Criar chave da conta de serviço"

    2. Na lista de contas de serviço, selecione a conta de serviço que você quer usar.

      Para criar uma nova conta de serviço, escolha Nova conta de serviço e especifique o nome, o código e o Papel do Container Registry com base nas permissões que você quer conceder à conta de serviço.

    3. Selecione JSON como o tipo de chave.

    4. Clique em Criar O download de um arquivo JSON que contém sua chave é feito no computador.

      As instruções nesta página usam o nome de arquivo keyfile.json para este arquivo de chave.

    gcloud

    Você pode executar os seguintes comandos usando o Cloud SDK na sua máquina local ou no Cloud Shell.

    1. Crie a conta de serviço. Substitua NAME por um nome para a conta de serviço.

      gcloud iam service-accounts create NAME
      
    2. Conceda permissões à conta de serviço. Substitua PROJECT_ID pelo código do projeto e ROLE pelo papel apropriado do Container Registry para a conta de serviço. Essa função se aplica a todos os repositórios no projeto. Você pode alterar a função mais tarde e também definir permissões diferentes para a conta de serviço em repositórios específicos.

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"
      
    3. Gere o arquivo de chave. As instruções nesta página usam o nome de arquivo keyfile.json para o arquivo de chave.

      gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com
      
  2. Execute o seguinte comando para fazer login no Cloud SDK como uma conta de serviço.

    gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
    

    Em que

    • ACCOUNT é o nome da conta de serviço no formato [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com.
    • KEY-FILE é o arquivo de chave da conta de serviço. Consulte a documentação do IAM para informações sobre como criar uma chave.
  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. Obtenha um token de acesso para a conta de serviço. Como o token tem vida curta, solicite menos de uma hora antes de usá-lo para se conectar ao Container Registry.

    Linux/macOS

    • O nome de usuário é oauth2accesstoken
    • A Senha é o token de acesso. Por exemplo, gcloud auth print-access-token

    Exemplo:

    gcloud auth print-access-token | docker login -u oauth2accesstoken --password-stdin https://[HOSTNAME]
    

    em que [HOSTNAME] é gcr.io, us.gcr.io, eu.gcr.io ou asia.gcr.io.

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

    docker login -u oauth2accesstoken -p "$(gcloud auth print-access-token)" https://[HOSTNAME]
    

    Windows

    • O nome de usuário é oauth2accesstoken
    • Senha é a saída de gcloud auth print-access-token
    1. Receber o token de acesso
    gcloud auth print-access-token
    

    A string retornada é o token de acesso que você usa como sua senha. Neste exemplo, ya29.8QEQIfY_... representa o token de acesso retornado.

    ya29.8QEQIfY_...
    
    1. Faça login com o token de acesso
    docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." https://[HOSTNAME]
    

    em que [HOSTNAME] é gcr.io, us.gcr.io, eu.gcr.io ou asia.gcr.io.

O Docker agora está autenticado com o Container Registry.

Arquivo de chave JSON

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. 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. Por exemplo, algumas contas de serviço criadas automaticamente pelo Google Cloud, como a conta de serviço do Container Registry, recebem o papel de leitura/gravação Editor do projeto pai. A conta de serviço padrão do Compute Engine é configurada com acesso somente leitura ao armazenamento dentro do mesmo projeto.

Além disso, o ciclo de vida do acesso da chave à conta de serviço não depende do ciclo de vida do usuário que fez o download da chave.

Use as seguintes diretrizes para limitar o acesso às imagens do seu contêiner:

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 a conta de serviço para interagir com os repositórios:

    Console

    1. No Google Cloud Console, abra a página Criar chave de conta de serviço.

      Acessar página "Criar chave da conta de serviço"

    2. Na lista Conta de serviço, selecione Nova conta de serviço.

    3. No campo Nome da conta de serviço, insira um nome.

    4. Da lista de Papéis, selecione o Papel do Container Registry para a conta de serviço.

    5. Clique em Criar O download de um arquivo JSON que contém sua chave é feito no computador.

      As instruções nesta página usam o nome de arquivo keyfile.json para este arquivo de chave.

    gcloud

    Você pode executar os seguintes comandos usando o Cloud SDK na sua máquina local ou no Cloud Shell.

    1. Crie a conta de serviço. Substitua NAME por um nome para a conta de serviço.

      gcloud iam service-accounts create NAME
      
    2. Conceda permissões à conta de serviço. Substitua PROJECT_ID pelo código do projeto e ROLE pelo papel apropriado para a conta de serviço.

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"
      
    3. Gere o arquivo de chave. Neste exemplo, o nome do arquivo da chave de saída é keyfile.json

      gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com
      
  2. 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.

  3. Use a chave da conta de serviço como sua senha para autenticar com o Docker.

    Linux/macOS

    • Nome de usuário é _json_key (NÃO o nome da sua conta de serviço)
    • keyfile.json é a chave da conta de serviço que você criou

    Exemplo:

    cat keyfile.json | docker login -u _json_key --password-stdin https://[HOSTNAME]
    

    em que [HOSTNAME] é gcr.io, us.gcr.io, eu.gcr.io ou asia.gcr.io.

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

    docker login -u _json_key -p "$(cat keyfile.json)" https://[HOSTNAME]
    

    em que [HOSTNAME] é gcr.io, us.gcr.io, eu.gcr.io ou asia.gcr.io.

    Windows

    • Nome de usuário é _json_key (NÃO o nome da sua conta de serviço)
    • keyfile.json contém a chave JSON de conta de serviço

    Exemplo:

    docker login -u _json_key --password-stdin https://[HOSTNAME] < keyfile.json
    

    em que [HOSTNAME] é gcr.io, us.gcr.io, eu.gcr.io ou asia.gcr.io.

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

    set /p PASS=<keyfile.json
    docker login -u _json_key -p "%PASS%" https://[HOSTNAME]
    

    em que [HOSTNAME] é gcr.io, us.gcr.io, eu.gcr.io ou asia.gcr.io.

O Docker agora está autenticado com o Container Registry.