Como configurar a autenticação do Helm

Nesta página, descrevemos como configurar o Helm para autenticar com repositórios do Artifact Registry.

Antes de começar

  1. Se não existir um repositório para seus gráficos, crie um novo repositório. Escolha o Docker como o formato do repositório.
  2. (Opcional) Configure padrões para comandos gcloud.
  3. Instale o Helm 3, se ele ainda não estiver instalado.

  4. Ative o suporte experimental do Helm para imagens OCI com a variável HELM_EXPERIMENTAL_OCI. Adicione a linha a seguir a ~/.bashrc (ou ~/.bash_profile no macOS ou sempre que o shell armazenar variáveis de ambiente):

    export HELM_EXPERIMENTAL_OCI=1
    
  5. Execute o seguinte comando para carregar o arquivo atualizado .bashrc ou .bash_profile:

    source ~/.bashrc
    

Como escolher um método de autenticação

Na maioria das situações, recomendamos o uso de uma conta de serviço para autenticação para o Artifact Registry.

As contas de serviço não estão associadas a um usuário específico, e os aplicativos do Google Cloud podem usar uma estratégia de Application Default Credentials para receber credenciais automaticamente.

As contas de serviço de aplicativos que normalmente se integram ao Artifact Registry, como o Cloud Build ou Cloud Run, são configuradas por padrão com permissões para acessar repositórios no mesmo projeto. Não é necessário configurar a autenticação do Docker para esses aplicativos.

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

Usar credenciais do Artifact Registry configuradas para o Docker
É possível configurar o Helm para ver as configurações de registro do arquivo de configuração do Docker. Se você configurou o Docker (em inglês) com o gcloud ou o auxiliar de credenciais independente para autenticar com o Artifact Registry, o Helm pode autenticar com as mesmas credenciais usadas para o 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 para reduzir o risco de acesso não autorizado aos seus artefatos.

Como usar a configuração do Docker

Se você configurou o Docker (em inglês) com o gcloud ou com o auxiliar de credenciais independente para autenticar com o Artifact Registry, as configurações de registro são armazenadas no arquivo config.json no Docker. para começar.

Por padrão, o Helm armazena as configurações de registro em ~/.config/helm/registry.json. Em vez de manter as configurações do registro em dois arquivos de configuração diferentes, configure o Helm para autenticar com qualquer host do Artifact Registry configurado para o Docker.

Para configurar o Helm para usar as configurações de registro do Docker:

Linux

  1. Adicione as seguintes linhas a ~/.bashrc (ou ~/.bash_profile no macOS ou sempre que o shell armazenar variáveis de ambiente):

    export DOCKER_CONFIG="~/.docker"
    export HELM_REGISTRY_CONFIG="${DOCKER_CONFIG}/config.json"
    
    • DOCKER_CONFIG é a variável de ambiente do Docker para o local do arquivo de configuração do cliente Docker, config.json. O local padrão é ~/.docker.
    • HELM_REGISTRY_CONFIG é a variável de ambiente do Helm para o arquivo de configuração do registro. Ele aponta para o arquivo config.json do Docker.
  2. Execute o seguinte comando para carregar o arquivo atualizado .bashrc ou .bash_profile:

    source ~/.bashrc
    

Windows

Execute os seguintes comandos para configurar variáveis de ambiente do usuário para os arquivos de configuração do Docker e do Helm:

setx DOCKER_CONFIG %USERPROFILE%\.docker
setx HELM_REGISTRY_CONFIG %DOCKER_CONFIG%\config.json
  • DOCKER_CONFIG é a variável de ambiente do Docker para o local do arquivo de configuração do cliente Docker, config.json. O local padrão é %USERPROFILE%\.docker.
  • HELM_REGISTRY_CONFIG é a variável de ambiente do Helm para o arquivo de configuração do registro. Ele aponta para o arquivo config.json do Docker.

Agora, o Helm está configurado para usar as mesmas credenciais usadas pelo Docker para o Artifact Registry. É possível enviar e receber gráficos dos repositórios do Artifact Registry em locais de host que você configurou para o Docker.

Usar um token de acesso

Os tokens de acesso são tokens de curta duração que fornecem acesso aos recursos do Google Cloud. Como o token tem vida curta, solicite-o menos de uma hora antes de usá-lo para se conectar aos repositórios do Artifact Registry.

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

Para usar um token de acesso:

  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 o papel apropriado do Artifact Registry à conta de serviço para fornecer acesso ao repositório.

  3. Atribua o local do arquivo de chave da conta de serviço à variável GOOGLE_APPLICATION_CREDENTIALS para que o auxiliar de credenciais do Artifact Registry possa conseguir sua chave ao se conectar com os repositórios.

    export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
    

    Em que KEY-FILE é o caminho para o arquivo de chave da conta de serviço.

  4. Receber um token de acesso como credenciais ao autenticar no Artifact Registry com o Docker.

    Linux / macOS

    Execute este comando:

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

    Windows

    Execute este comando:

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

    Onde

    • oauth2accesstoken é o nome de usuário a ser usado na autenticação com um token de acesso.
    • gcloud auth application-default print-access-token é o comando gcloud para receber o token de acesso da conta de serviço. Seu token de acesso é a senha para autenticação.
    • LOCATION é o local regional ou multirregional do repositório em que a imagem está armazenada.

Agora o Helm é autenticado com o Artifact Registry.

Usar um 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. 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. Conceda o papel apropriado do Artifact Registry à conta de serviço para fornecer acesso ao repositório.

  4. Use a chave da conta de serviço para autenticar:

    Linux / macOS

    Execute este comando:

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

    Windows

    Execute este comando:

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

    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.

Agora o Helm é autenticado com o Artifact Registry.

A seguir