Fazer o download de pacotes Python usando acesso direto ao repositório para o nível sem custo financeiro

No nível sem custo financeiro, os pacotes do Assured Open Source Software são hospedados em um repositório do Artifact Registry gerenciado pelo Google.

Nesta página, explicamos como se conectar ao repositório do Artifact Registry para o Assured OSS e acessar e baixar diretamente os pacotes Python.

Este documento se aplica apenas ao nível sem custo financeiro. Para o nível Premium, consulte Fazer o download de pacotes Python usando acesso direto ao repositório.

Antes de começar

Peça ao administrador para conceder a você o papel do IAM Administrador da chave da conta de serviço (roles/iam.serviceAccountKeyAdmin) na sua organização. Você precisa dessa permissão para receber a string codificada em base64 da chave da conta de serviço. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Configure o Assured OSS. Para o nível sem custo financeiro, envie o formulário de capacitação do cliente para ativar o acesso ao Assured OSS.
Valide a conectividade com o Assured OSS para as contas de serviço solicitadas.
Ative a API Artifact Registry para o projeto pai Google Clouddas contas de serviço usadas para acessar o Assured OSS.
Instale a versão mais recente da Google Cloud CLI. Se você já instalou a Google Cloud CLI, verifique se tem a versão mais recente executando este comando:
```
gcloud components update
```

Configurar a autenticação

É possível autenticar o repositório de pacotes Python do Assured OSS usando um dos seguintes métodos:

Autenticar com o keyring do Python
Autenticar com uma chave de conta de serviço

As seções a seguir descrevem como configurar esses métodos de autenticação.

Autenticar com o keyring do Python

Para autenticar com o Artifact Registry usando Python, recomendamos usar o keyring do Python (em inglês). Para mais informações, consulte Autenticação com keyring e Ordem de pesquisa de credenciais.

Para configurar o keyring do Python para autenticação, faça o seguinte:

Instale a biblioteca keyring:
```
pip install keyring
```

Instale o back-end do Artifact Registry:

pip install keyrings.google-artifactregistry-auth

Liste os back-ends para confirmar a instalação:
```
keyring --list-backends
```
A lista precisa incluir o seguinte:
- ChainerBackend(priority:10)
- GooglePythonAuth(priority:9)
Para informações sobre como configurar as Application Default Credentials, consulte Configurar a autenticação.

Essa etapa garante que o auxiliar de credenciais do Assured OSS obtenha sua chave ao se conectar com os repositórios.

Autenticar com uma chave de conta de serviço

Autentique-se com uma chave de conta de serviço quando o aplicativo exigir autenticação com um nome de usuário e uma senha.

Observação: as chaves de conta de serviço podem causar problemas de segurança quando não são gerenciadas corretamente. Sempre que possível, escolha uma alternativa mais segura do que as chaves de conta de serviço. Se você precisar se autenticar com uma chave de conta de serviço, será responsável pela segurança da chave privada e por outras operações descritas em Práticas recomendadas para gerenciar chaves de contas de serviço. Se você não conseguiu criar uma chave de conta de serviço, é possível que a criação esteja desativada para sua organização. Para mais informações, consulte Gerenciar recursos da organização com segurança por padrão.

Se você adquiriu a chave de conta de serviço com uma fonte externa, valide-a antes do uso. Para mais informações, consulte Requisitos de segurança para credenciais de fontes externas.

Substitua o URL do repositório de pacotes https://us-python.pkg.dev/cloud-aoss/cloud-aoss-python/simple pelo URL https://_json_key_base64:$BASE64_KEY@us-python.pkg.dev/cloud-aoss/cloud-aoss-python/simple

Instalar pacotes

As instruções a seguir pressupõem que você está usando o PyPI e o requirements.txt para baixar e gerenciar suas dependências. Se você estiver usando outro processo de gerenciamento de dependências, siga etapas diferentes.

Instalar pacotes no Assured OSS

Para especificar os pacotes Python do Assured OSS que você quer baixar, crie dois arquivos requirements.txt. Os arquivos de exemplo são os seguintes:

requirements-google.txt

# Packages present in Google's Artifact Registry

urllib3==1.26.11 --hash=sha256:1cffe1aa066363a75c856f261c8fce62d87f7c40ce0f46453ea12bf652b12a13
jsonschema==4.13.0 --hash=sha256:29895bfe55b93b75552fbdd1e09aa0c82b7c1c9395d4f267e10c7d43cd31a74e

requirements-pypi.txt

# Packages present in Google's Artifact Registry are mentioned here so that pip
# downloads their dependencies from PyPI.

urllib3==1.26.11
jsonschema==4.13.0

# Below this comment, add any package version which you need but is NOT
# present in Google's Artifact Registry and therefore needs to be downloaded from
# PyPI.

Para fazer o download dos pacotes, execute os seguintes comandos:

Para fazer o download dos pacotes necessários que estão no Artifact Registry para o Assured OSS, execute o seguinte:
```
 pip install --require-hashes --requirement=requirements-google.txt \
     --index-url https://_json_key_base64:$BASE64_KEY@us-python.pkg.dev/cloud-aoss/cloud-aoss-python/simple -v \
     --no-deps
```
Considere o seguinte:
- --require-hashes é opcional. Se incluídos, os hashes serão especificados para todos os pacotes e para todas as versões de pacote no arquivo requirements.txt.
- -v é opcional. Se especificado, o comando vai gerar mais saída. Recomendamos fixar dependências com hashes SHA-256 no arquivo requirements.txt para garantir segurança e capacidade de reprodução.
Para baixar os pacotes necessários que não estão no Artifact Registry para o Assured OSS, execute o seguinte:
```
 pip install --requirement=requirements-pypi.txt --index-url https://pypi.org/simple -v
```
Esse comando também baixa as dependências ausentes dos pacotes que você baixou usando o comando anterior.

Acessar pacotes não disponíveis no repositório do Artifact Registry para o Assured OSS

O Assured OSS é pré-configurado com o Assured OSS como o repositório preferencial e repositórios públicos canônicos, como Maven Central ou PyPI, como repositórios secundários.

Para usar esse recurso (pré-lançamento), aponte para um único URL:

https://us-python.pkg.dev/cloud-aoss/python/simple

Listar todos os pacotes Python disponíveis no Assured OSS

Para usar uma API e receber uma lista de todos os pacotes Python no repositório do Artifact Registry, consulte Listar todos os pacotes Python disponíveis no Assured OSS.

Como gerar o arquivo `requirements-google.txt`

Nesta seção, você encontra mais informações sobre como gerar o arquivo requirements-google.txt necessário para baixar os pacotes do Python. Para fazer o download do hash e gerar o arquivo requirements-google.txt para seu ambiente, use uma das duas opções a seguir:

Use um script para gerar um único arquivo de requisitos para todos os artefatos.
Baixe um arquivo de requisitos separado para cada artefato.

Confira mais informações sobre essas opções nas seções a seguir.

Opção 1: usar um script para gerar um único arquivo de requisitos para todos os artefatos

Use o script generator.sh para gerar um único arquivo requirements-google.txt para todos os pacotes Python (com os hashes deles) disponíveis com o Assured OSS para o sistema operacional Linux. Os pacotes precisam atender a restrições como versão do Python, arquitetura da máquina e sistema operacional. Depois, exclua as versões de pacote que você não precisa e use o arquivo resultante.

O script generator.sh ajuda das seguintes duas maneiras:

Gera a lista mais recente de versões de pacotes do Python disponíveis com o Assured OSS que podem ser instaladas no seu sistema.
Gera o arquivo requirements-google.txt com todos os hashes.

O script necessário e o arquivo README.md estão disponíveis em um bucket do Cloud Storage (gs://cloud-aoss/utils/python-requirements-txt/v1.0), que pode ser baixado usando a Google Cloud CLI.

Para fazer o download do script e do arquivo README.md, siga estas etapas:

Autentique-se com a conta de serviço para acessar o bucket do Cloud Storage usando o seguinte comando:
```
gcloud auth activate-service-account --key-file KEY_FILE
```
Substitua KEY_FILE pelo caminho do arquivo que contém as credenciais da conta de serviço.
Faça o download do generator.sh para sua máquina usando o seguinte comando:
```
gcloud storage cp gs://cloud-aoss/utils/python-requirements-txt/v1.0/generator.sh PATH_TO_LOCAL_STORE --recursive
```
Substitua PATH_TO_LOCAL_STORE pelo caminho local em que você quer salvar o arquivo baixado.
Baixe o arquivo README.md usando o seguinte comando:
```
gcloud storage cp gs://cloud-aoss/utils/python-requirements-txt/v1.0/README.md PATH_TO_LOCAL_STORE --recursive
```
Substitua PATH_TO_LOCAL_STORE pelo caminho local em que você quer salvar o arquivo baixado. O arquivo README.md contém instruções sobre como usar o script.

Para executar o script, use os seguintes comandos:

Para gerar o arquivo requirements-google.txt, execute o seguinte comando:
```
 chmod +x generator.sh
 ./generator.sh
```
Para receber as informações do pacote em um arquivo CSV, execute o seguinte comando:
```
chmod +x generator.sh
./generator.sh -i
```

Opção 2: fazer o download do `requirements.txt` para cada artefato necessário

Também é possível baixar um arquivo requirements.txt separado (com o hash) para cada artefato do Python e combiná-los em um único arquivo requirements.txt.

Os hashes de artefato estão disponíveis em um bucket do Cloud Storage, que pode ser baixado usando a CLI gcloud. Os hashes de cada pacote e uma versão estão localizados no local do bucket do Cloud Storage gs://cloud-aoss/python/PACKAGE_NAME/VERSION.

Para fazer o download do arquivo requirements.txt, siga estas etapas:

Autentique-se com a conta de serviço para acessar o bucket do Cloud Storage usando o seguinte comando:
```
gcloud auth activate-service-account --key-file KEY_FILE
```
Substitua KEY_FILE pelo caminho do arquivo que contém as credenciais da conta de serviço.
Faça o download do requirements.txt de um pacote e uma versão específicos para sua máquina local usando o seguinte comando:
```
gcloud storage cp gs://cloud-aoss/python/PACKAGE_NAME/VERSION PATH_TO_LOCAL_STORE --recursive
```
Substitua:
- PACKAGE_NAME: o nome do pacote
- VERSION: a versão do pacote
- PATH_TO_LOCAL_STORE: o caminho local onde você quer baixar o arquivo.
Exemplo de comando:

gcloud storage cp gs://cloud-aoss/python/bleach/5.0.0 /tmp/bleach --recursive

Arquivo requirements.txt de amostra:
```
bleach==5.0.0 \
 --hash=sha256:6d286e765bfd3e309209cfa1d063e4d46afa966dea8cb97431c02b1e3067d812
```
O conteúdo de cada arquivo requirements.txt pode ser combinado em um único arquivo requirements-google.txt.