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

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

Tem de autenticar-se no Artifact Registry quando usa uma aplicação de terceiros para se ligar a um repositório.

Não precisa de configurar a autenticação para o Cloud Build nem para os ambientes de execução, como o Google Kubernetes Engine e o Cloud Run, mas deve verificar se as autorizações necessárias estão configuradas. Google Cloud

Antes de começar

  1. Se o repositório de destino não existir, crie um novo repositório de pacotes Python.
  2. Confirme se o Python 3 está instalado. Para ver instruções de instalação, consulte o Google Cloud tutorial de configuração do Python.
  3. Verifique se a conta de utilizador ou a conta de serviço que está a usar tem as autorizações necessárias para aceder ao repositório.

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

    gcloud init

    Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

  5. (Opcional) Configure as predefinições para os comandos da CLI gcloud.

Vista geral

O Artifact Registry suporta os seguintes métodos de autenticação.

Biblioteca Python keyring (recomendado)
O Artifact Registry fornece um back-end de conjunto de chaves para armazenar as credenciais de ligação aos repositórios do Artifact Registry.
Autenticação por palavra-passe
Use esta opção quando não puder usar o conjunto de chaves e precisar de uma opção que suporte a autenticação básica de palavra-passe.

As instruções nesta documentação descrevem a configuração do pip como o único índice de pacotes que o pip procura. Recomendamos que use repositórios virtuais para pesquisar pacotes nos seus pacotes privados no Artifact Registry e pacotes públicos do PyPI, em vez de configurar vários índices de pacotes no ficheiro de configuração do pip. A ferramenta pip não pesquisa os índices de pacotes por nenhuma ordem específica, pelo que os seus consumidores podem transferir ou instalar por engano um pacote público com o mesmo nome de um dos seus pacotes privados. Os repositórios virtuais permitem-lhe configurar prioridades para origens a montante de forma a mitigar este risco de confusão de dependências.

A autenticar com o conjunto de chaves

A biblioteca keyring do Python oferece às aplicações uma forma de aceder aos backends do keyring, ou seja, aos sistemas operativos e às lojas de credenciais de terceiros.

O Artifact Registry fornece o backend do porta-chaves keyrings.google-artifactregistry-auth para processar a autenticação com repositórios do Artifact Registry.

Ordem de pesquisa de credenciais

Quando usa o back-end do conjunto de chaves do Artifact Registry, as suas credenciais não são armazenadas no seu projeto Python. Em alternativa, o Artifact Registry procura credenciais pela seguinte ordem:

  1. Credenciais padrão da aplicação (ADC), uma estratégia que procura credenciais pela seguinte ordem:

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

    2. Credenciais fornecidas pela conta de serviço predefinida do Compute Engine, do Google Kubernetes Engine, do Cloud Run, do App Engine ou das funções do Cloud Run.

  2. Credenciais fornecidas pela CLI do Google Cloud, incluindo credenciais de utilizador 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 resolução de problemas. Se não usar a variável, verifique se todas as contas que o ADC possa usar têm as autorizações necessárias. Por exemplo, a conta de serviço predefinida para VMs do Compute Engine, nós do Google Kubernetes Engine e revisões do Cloud Run tem acesso apenas de leitura aos repositórios. Se pretende fazer o carregamento a partir destes ambientes através da conta de serviço predefinida, tem de modificar as autorizações.

Configurar porta-chaves

Para configurar a autenticação com o back-end do conjunto de chaves do Artifact Registry:

  1. Instale a biblioteca 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 deve incluir

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

  4. Execute o seguinte comando para imprimir a configuração do repositório a adicionar 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 esta flag for omitida, é usado o projeto predefinido atual.
    • REPOSITORY é o ID do repositório. Se configurou um repositório do Artifact Registry predefinido, este é usado quando esta flag é omitida do comando.
    • LOCATION é a localização regional ou multirregional do repositório.

  5. Adicione as seguintes definições ao ficheiro .pypirc. A localização predefinida é:

    • 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 referenciar com ferramentas como o Twine.
    • PROJECT é o ID do projeto. Se esta flag for omitida, é usado o projeto predefinido atual.
    • REPOSITORY é o ID do repositório. Se configurou um repositório do Artifact Registry predefinido, este é usado quando esta flag é omitida do comando.
    • LOCATION é a localização regional ou multirregional do repositório.

  6. Adicione o seu repositório ao ficheiro de configuração do pip. A localização do ficheiro depende de querer atualizar o ficheiro por utilizador ou o ficheiro específico de um ambiente virtual que está a usar.

    Para o ficheiro associado ao utilizador do sistema operativo:

    • 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 definição index-url e certifique-se de que não existem outros índices de pacotes configurados com a definiçã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 o repositório implementa a API Python Simple Repository.

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

Autenticação da base de dados de chaves com credenciais de utilizador

Depois de configurar o conjunto de chaves, pode usar o conjunto de chaves com as suas credenciais de utilizador na CLI gcloud. Inicie sessão na CLI do Google Cloud antes de se ligar a um repositório de pacotes Python.

Execute o seguinte comando:

gcloud auth login

Autenticação de Keyring com credenciais da conta de serviço

Depois de configurar o conjunto de chaves, pode configurar uma conta de serviço para autenticação.

  1. Crie uma conta de serviço ou escolha uma conta de serviço existente que use para automatização.
  2. Conceda a função do Artifact Registry específica à conta de serviço para fornecer acesso ao repositório.

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

    • Credenciais padrão da aplicação (recomendado)

      Atribua a localização do ficheiro de chave da conta de serviço à variável GOOGLE_APPLICATION_CREDENTIALS para que o auxiliar de credenciais do Artifact Registry possa obter a sua chave quando se ligar a repositórios.

      export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE

    • Credenciais da CLI gcloud

      Antes de se ligar a um repositório, inicie sessão como conta de serviço. Evite esta opção se estiver a estabelecer ligação a repositórios a partir de VMs do Compute Engine, uma vez 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 ficheiro de chave da conta de serviço.

Autenticação com uma chave de conta de serviço

Use esta abordagem quando precisar de autenticação com um nome de utilizador e uma palavra-passe.

As chaves de contas 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 a função do Artifact Registry mínima exigida pela conta de serviço. Por exemplo, atribua a função Leitor do Artifact Registry a uma conta de serviço que apenas transfere artefactos.
  • Se os grupos na sua organização precisarem de diferentes níveis de acesso a repositórios específicos, conceda acesso ao nível do repositório e não ao nível do projeto.
  • Siga as práticas recomendadas para gerir credenciais.

Para configurar a autenticação:

  1. Crie uma conta de serviço para agir em nome da sua aplicação ou escolha uma conta de serviço existente que use para automatização.

    Precisa da localização do ficheiro de chave da conta de serviço para configurar a autenticação com o Artifact Registry. Para contas existentes, pode ver as chaves e criar novas chaves na página Contas de serviço.

    Aceda à página Contas de serviço

  2. Conceda a função do Artifact Registry adequada à conta de serviço para fornecer acesso ao repositório.

  3. Execute o seguinte comando para imprimir a configuração do repositório a adicionar 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 esta flag for omitida, é usado o projeto predefinido atual.
    • REPOSITORY é o ID do repositório. Se configurou um repositório do Artifact Registry predefinido, este é usado quando esta flag é omitida do comando.
    • LOCATION é a localização regional ou multirregional do repositório.
    • KEY-FILE é o caminho para o ficheiro de chave JSON da conta de serviço.

  4. Adicione as seguintes definições ao ficheiro .pypirc. A localização predefinida do ficheiro de configuração do pip por utilizador é:

    • 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 referenciar com ferramentas como o Twine.
    • PROJECT é o ID do projeto. Se esta flag for omitida, é usado o projeto predefinido atual.
    • REPOSITORY é o ID do repositório. Se configurou um repositório do Artifact Registry predefinido, este é usado quando esta flag é omitida do comando.
    • LOCATION é a localização regional ou multirregional do repositório.
    • KEY é a chave codificada em base64 no ficheiro de chave da conta de serviço.

  5. Adicione o seu repositório ao ficheiro de configuração do pip. A localização do ficheiro de configuração do pip depende de querer atualizar o ficheiro por utilizador ou o ficheiro específico de um ambiente virtual que está a usar.

    Para o ficheiro associado ao utilizador do sistema operativo:

    • 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 ficheiro 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 ficheiro de chave da conta de serviço.
    • A string /simple/ no final do caminho do repositório indica que o repositório implementa a API Python Simple Repository.

O que se segue?