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

Nesta página, descrevemos como configurar a autenticação com um repositório de pacotes Python do Artifact Registry.

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

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

Antes de começar

  1. Se o repositório de destino não existir, crie um novo repositório de pacotes do Python.
  2. Verifique se o Python 3 está instalado. Para instruções de instalação, consulte o tutorial de configuração do Python do Google Cloud.
  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 Google Cloud CLI e inicialize-a executando o seguinte comando: 

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

Visão geral

O Artifact Registry é compatível com os seguintes métodos de autenticação.

Biblioteca de keyring do Python (recomendado)
O Artifact Registry fornece um back-end de keyring para armazenar as credenciais de conexão com os repositórios do Artifact Registry.
Autenticação por senha
Use essa opção quando não for possível usar o keyring e precisar de uma opção com suporte à autenticação de senha básica.

Nas instruções desta documentação, descrevemos a configuração do pip como o único índice de pacote em que o pip procura pacotes. Recomendamos o uso de repositórios virtuais para pesquisar pacotes nos pacotes particulares no Artifact Registry e em pacotes públicos de PyPI em vez de configurar vários índices de pacotes no arquivo de configuração de pip. A ferramenta pip não pesquisa índices de pacotes em nenhuma ordem específica. Por isso, os consumidores podem fazer o download ou instalar por engano um pacote público com o mesmo nome de um dos pacotes particulares. Os repositórios virtuais permitem configurar prioridades para origens upstream para reduzir esse risco de confusão de dependências.

Como autenticar com o keyring

A biblioteca de keyring do Python fornece aos aplicativos uma maneira de acessar back-ends de keyring, ou seja, armazenamentos de credenciais de terceiros e do sistema operacional.

O Artifact Registry fornece o back-end de keyring keyrings.google-artifactregistry-auth para processar a autenticação com os repositórios do Artifact Registry.

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 em 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 que a conta de serviço padrão do Compute Engine, do Google Kubernetes Engine, do Cloud Run, do App Engine ou do Cloud Functions fornece.

  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 autenticação da conta explícita, o que facilita a solução de problemas. Se você não usar a variável, verifique se alguma conta que o ADC pode usar tem 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ê pretende fazer o upload a partir desses ambientes usando a conta de serviço padrão, modifique as permissões.

Configurando o keyring

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

  1. Instale a biblioteca do keyring.

    pip install keyring

  2. Instale o back-end do Artifact Registry.

    pip install keyrings.google-artifactregistry-auth

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

    keyring --list-backends

    A lista deve incluir

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

  4. Execute o comando a seguir para imprimir a configuração do repositório a ser adicionada ao seu projeto em 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 configurações abaixo 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 para o 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 da atualização do arquivo por usuário ou do arquivo específico de um ambiente virtual que você está usando.

    Para o arquivo associado ao usuário do seu 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 seu repositório, use a configuração index-url e verifique se não há outros índices de pacote 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 Simple Repository Python (em inglês).

Seu ambiente Python agora está configurado para autenticação com o Artifact Registry.

Autenticação de keyring com credenciais de usuário

Depois de configurar o keyring, use-o com suas credenciais de usuário na CLI gcloud. Faça login no Google Cloud CLI antes de se conectar a um repositório de pacotes do Python.

Execute este comando:

gcloud auth login

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

Depois de configurar o keyring, configure 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ê use para automação.
  2. Conceda o papel específico do Artifact Registry à conta de serviço para fornecer acesso ao repositório.

  3. Use uma das seguintes opções para autenticar 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 de VM antes das credenciais na CLI gcloud.

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

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

Como autenticar com uma chave de conta de serviço

Use essa abordagem quando precisar de autenticação com nome de usuário e 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".

    Acesse 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 imprimir a configuração do repositório a ser adicionada ao seu projeto em 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 configurações abaixo ao arquivo .pypirc. O local padrão é o arquivo de configuração de 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 para o 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 da atualização do arquivo por usuário ou do arquivo específico para um ambiente virtual que você está usando.

    Para o arquivo associado ao usuário do seu 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 linha abaixo 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 sua conta de serviço.
    • A string /simple/ no final do caminho do repositório indica que ele implementa a API Simple Repository Python (em inglês).

A seguir