Configurar a autenticação no Artifact Registry para repositórios de pacotes Python

É necessário se autenticar no Artifact Registry ao usar um aplicativo de terceiros para se conectar a um repositório.

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

O Artifact Registry é compatível com os seguintes métodos de autenticação para repositórios de pacotes Python:

  • Tokens de acesso: use tokens de acesso em automação, pipelines de CI/CD, builds de contêineres ou ambientes em que a instalação da biblioteca de keyring não é compatível.
  • Biblioteca keyring do Python (recomendada para desenvolvimento local): use essa opção em estações de trabalho de desenvolvedores para processar automaticamente a atualização de credenciais.
  • Autenticação por senha: use essa opção quando um aplicativo não for compatível com o Application Default Credentials, mas aceitar a autenticação com um nome de usuário e uma senha.

Antes de começar

  1. Se o repositório de destino não existir, crie um repositório de pacote Python.
  2. Verifique se o Python 3 está instalado. Para instruções de instalação, consulte o Google Cloud tutorial de configuração do Python.
  3. Verifique se a conta de usuário ou de serviço que você está usando tem as permissões necessárias para acessar o repositório.

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

    gcloud init

    Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  5. (Opcional) Configure padrões para comandos da CLI gcloud.

Gerar tokens para autenticação

Para autenticar seu pacote no Artifact Registry, primeiro gere um token de autenticação. Em seguida, use esse token ao fazer solicitações do seu pacote para o Artifact Registry.

É possível gerar um token de acesso oauth2 usando Google Cloud ou um token oauth2l fora do Google Cloud.

Os tokens de acesso são válidos por 60 minutos. Gere um token de acesso pouco antes de executar comandos que interagem com repositórios. Se o token de acesso expirou, gere um novo.

Gerar um token usando a gcloud

Para gerar um token de acesso oauth2 usando Google Cloud, execute o seguinte comando:

export ACCESS_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"

Agora é possível referenciar ACCESS_TOKEN ao fazer solicitações do seu pacote Python para o Artifact Registry.

Gerar um token sem usar a gcloud

Para gerar um token de acesso usando apenas a CLI oauth2l, faça o seguinte:

  1. Instale a versão mais recente do oauth2l executando o seguinte comando:

    go install github.com/google/oauth2l@latest

  2. Execute este comando:

    export ACCESS_TOKEN="oauth2l fetch --scope cloud-platform"

    Google Cloud gera um token de hash SHA256 e o armazena na variável ACCESS_TOKEN. Agora é possível referenciar ACCESS_TOKEN ao fazer solicitações do pacote Python para o Artifact Registry.

Autenticar com pip

Depois de exportar ACCESS_TOKEN, transmita para pip para instalar pacotes:

pip install PACKAGE --index-url https://$ACCESS_TOKEN@LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/

Autenticar com keyring

A biblioteca keyring do Python oferece aos aplicativos uma maneira de acessar backends de keyring, ou seja, sistemas operacionais e lojas de credenciais de terceiros. O Artifact Registry fornece o back-end keyring keyrings.google-artifactregistry-auth para processar a autenticação com repositórios do Artifact Registry.

As instruções nesta seção descrevem a configuração do pip como o único índice de pacote em que ele pesquisa. Recomendamos usar repositórios virtuais para pesquisar pacotes particulares no Artifact Registry e pacotes públicos do PyPI, em vez de configurar vários índices de pacotes no arquivo de configuração do pip. A ferramenta pip não pesquisa índices de pacotes em nenhuma ordem específica. Por isso, seus consumidores podem baixar ou instalar por engano um pacote público com o mesmo nome de um dos seus pacotes particulares. Com os repositórios virtuais, é possível configurar prioridades para fontes upstream e mitigar esse risco de confusão de dependências.

Ordem de pesquisa de credenciais

Quando você usa o back-end do keyring do Artifact Registry, suas credenciais não são armazenadas no projeto Python. Em vez disso, o Artifact Registry procura credenciais na seguinte ordem:

  1. Application Default Credentials (ADC), uma estratégia que procura credenciais na seguinte ordem:

    1. Credenciais definidas na variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

    2. Credenciais fornecidas pela conta de serviço padrão do Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine ou Cloud Run functions.

  2. Credenciais fornecidas pela Google Cloud CLI, incluindo credenciais de usuário do comando gcloud auth application-default login.

A variável GOOGLE_APPLICATION_CREDENTIALS torna a conta para autenticação explícita, o que facilita a solução de problemas. Se você não usar a variável, verifique se as contas que o ADC pode usar têm as permissões necessárias. Por exemplo, a conta de serviço padrão para VMs do Compute Engine, nós do Google Kubernetes Engine e revisões do Cloud Run tem acesso somente leitura aos repositórios. Se você quiser fazer upload desses ambientes usando a conta de serviço padrão, modifique as permissões.

Configurar keyring

Para configurar a autenticação com o back-end do keyring do Artifact Registry:

  1. Instale a biblioteca de keyring.

    pip install keyring

  2. Instale o back-end do Artifact Registry.

    pip install keyrings.google-artifactregistry-auth

  3. Liste os back-ends para confirmar a instalação.

    keyring --list-backends

    A lista precisa incluir

    • ChainerBackend(priority:10)
    • GooglePythonAuth(priority: 9)

  4. Execute o comando a seguir para mostrar a configuração do repositório e adicioná-la ao seu projeto Python.

    gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

    Substitua os seguintes valores:

    • PROJECT é o ID do projeto. Se essa sinalização for omitida, o projeto padrão ou atual é usado.
    • REPOSITORY é o ID do repositório. Se você tiver configurado um repositório do Artifact Registry padrão, ele será usado quando essa sinalização for omitida no comando.
    • LOCATION é o local regional ou multirregional do repositório.

  5. Adicione as seguintes configurações ao arquivo .pypirc. O local padrão é:

    • Linux e macOS: $HOME/.pypirc
    • Windows: %USERPROFILE%\.pypirc
    [distutils]
index-servers =
    PYTHON-REPO-ID

[PYTHON-REPO-ID]
repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/

    Substitua os seguintes valores:

    • PYTHON-REPO-ID é um ID do repositório que pode ser referenciado com ferramentas como o Twine.
    • PROJECT é o ID do projeto. Se essa sinalização for omitida, o projeto padrão ou atual é usado.
    • REPOSITORY é o ID do repositório. Se você tiver configurado um repositório do Artifact Registry padrão, ele será usado quando essa sinalização for omitida no comando.
    • LOCATION é o local regional ou multirregional do repositório.

  6. Adicione seu repositório ao arquivo de configuração do pip. O local do arquivo depende de você querer atualizar o arquivo por usuário ou o arquivo específico de um ambiente virtual que está usando.

    Para o arquivo associado ao usuário do sistema operacional:

    • Unix: $HOME/.config/pip/pip.conf ou $HOME/.pip/pip.conf
    • macOS: /Library/Application Support/pip/pip.conf ou $HOME/.config/pip/pip.conf
    • Windows: %APPDATA%\pip\pip.ini ou %USERPROFILE%\pip\pip.ini

    Para ambientes virtuais:

    • Unix e macOS: $VIRTUAL_ENV/pip.conf
    • Windows: %VIRTUAL_ENV%\pip.ini

    Para configurar o pip para pesquisar apenas no seu repositório, use a configuração index-url e verifique se não há outros índices de pacotes configurados com a configuração extra-index-url.

    [global]
index-url = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/

    A string /simple/ no final do caminho do repositório indica que ele implementa a API Python Simple Repository.

Seu ambiente Python agora está configurado para autenticar com o Artifact Registry.

autenticação keyring com credenciais do usuário

Depois de configurar o chaveiro, é possível usá-lo com suas credenciais de usuário na CLI gcloud. Faça login na Google Cloud CLI antes de se conectar a um repositório de pacotes Python.

Execute este comando:

gcloud auth login

Autenticação do keyring com credenciais da conta de serviço

Depois de configurar o chaveiro, você pode configurar uma conta de serviço para autenticação.

  1. Crie uma conta de serviço ou escolha uma conta de serviço atual que você usa para automação.
  2. Conceda o papel específico do Artifact Registry à conta de serviço para dar acesso ao repositório.

  3. Use uma das seguintes opções para fazer a autenticação com sua conta de serviço:

    • Application Default Credentials (recomendado)

      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

    • Credenciais da CLI gcloud

      Antes de se conectar a um repositório, faça login como a conta de serviço. Evite essa opção se você estiver se conectando a repositórios de VMs do Compute Engine, já que o Artifact Registry encontra as credenciais da conta de serviço da VM antes das credenciais na CLI gcloud.

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

    Substitua KEY-FILE pelo caminho para o arquivo de chave da conta de serviço.

Configurar a autenticação de senha com chaves de conta de serviço

Use essa abordagem quando precisar de autenticação com um nome de usuário e uma senha.

As chaves da conta de serviço são credenciais de longa duração. Use as seguintes diretrizes para limitar o acesso aos seus repositórios:

  • Considere usar uma conta de serviço dedicada para interagir com repositórios.
  • Conceda o papel mínimo do Artifact Registry exigido pela conta de serviço. Por exemplo, atribua o leitor do Artifact Registry a uma conta de serviço que faz o download apenas de artefatos.
  • Se os grupos na sua organização exigirem níveis diferentes de acesso a repositórios específicos, conceda acesso no nível do repositório em vez de no nível do projeto.
  • Siga as práticas recomendadas para gerenciar as credenciais.

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

  3. Execute o comando a seguir para mostrar a configuração do repositório e adicioná-la ao seu projeto Python.

    gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --json-key=KEY-FILE

    Substitua os seguintes valores:

    • PROJECT é o ID do projeto. Se essa sinalização for omitida, o projeto padrão ou atual é usado.
    • REPOSITORY é o ID do repositório. Se você tiver configurado um repositório do Artifact Registry padrão, ele será usado quando essa sinalização for omitida no comando.
    • LOCATION é o local regional ou multirregional do repositório.
    • KEY-FILE é o caminho para o arquivo de chaves JSON da conta de serviço.

  4. Adicione as seguintes configurações ao arquivo .pypirc. O local padrão do arquivo de configuração do pip por usuário é:

    • Linux e macOS: $HOME/.pypirc
    • Windows: %USERPROFILE%\.pypirc
    [distutils]
index-servers =
    PYTHON-REPO-ID

[PYTHON-REPO-ID]
repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/
username: _json_key_base64
password: KEY

    Substitua os seguintes valores:

    • PYTHON-REPO-ID é um ID do repositório que pode ser referenciado com ferramentas como o Twine.
    • PROJECT é o ID do projeto. Se essa sinalização for omitida, o projeto padrão ou atual é usado.
    • REPOSITORY é o ID do repositório. Se você tiver configurado um repositório do Artifact Registry padrão, ele será usado quando essa sinalização for omitida no comando.
    • LOCATION é o local regional ou multirregional do repositório.
    • KEY é a chave codificada em base64 no arquivo de chave da sua conta de serviço.

  5. Adicione seu repositório ao arquivo de configuração do pip. O local do arquivo de configuração do pip depende de se você quer atualizar o arquivo por usuário ou o arquivo específico de um ambiente virtual que você está usando.

    Para o arquivo associado ao usuário do sistema operacional:

    • Unix: $HOME/.config/pip/pip.conf ou $HOME/.pip/pip.conf
    • macOS: /Library/Application Support/pip/pip.conf ou $HOME/.config/pip/pip.conf
    • Windows: %APPDATA%\pip\pip.ini ou %USERPROFILE%\pip\pip.ini

    Para ambientes virtuais:

    • Unix e macOS: $VIRTUAL_ENV/pip.conf
    • Windows: %VIRTUAL_ENV%\pip.ini

    Adicione a seguinte linha ao arquivo de configuração do pip:

    [global]
index-url = https://_json_key_base64:KEY@LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/
    • KEY a chave privada no arquivo de chave da conta de serviço.
    • A string /simple/ no final do caminho do repositório indica que ele implementa a API Python Simple Repository.

A seguir