Configura la autenticación en los repositorios de paquetes de Artifact Registry para Python

En esta página, se describe cómo configurar la autenticación con un repositorio de paquetes de Python de Artifact Registry.

Debes autenticarte en Artifact Registry cuando uses una aplicación de terceros para conectarte a un repositorio.

No es necesario que configures la autenticación para los entornos de ejecución de Cloud Build o Google Cloud, como Google Kubernetes Engine y Cloud Run, pero debes verificar que estén configurados los permisos necesarios.

Antes de comenzar

Si el repositorio de destino no existe, crea un repositorio de paquetes de Python nuevo.
Verifica que Python 3 esté instalado. Si deseas obtener instrucciones de instalación, consulta el instructivo para configurar Python de Google Cloud.
Verifica que la cuenta de usuario o de servicio que usas tenga los permisos necesarios para acceder al repositorio.
Instala Google Cloud CLI y, luego, inicializa la ejecución del siguiente comando:
```
gcloud init
```
Nota: Si ya instalaste la CLI de gcloud, asegúrate de que tienes la versión más reciente mediante la ejecución de gcloud components update.
(Opcional) Configura los valores predeterminados para gcloud CLI de gcloud.

Descripción general

Artifact Registry admite los siguientes métodos de autenticación.

Biblioteca de llavero de claves de Python (recomendada): Artifact Registry proporciona un backend de llavero de claves para almacenar las credenciales y conectarse a los repositorios de Artifact Registry.
Autenticación mediante contraseña: Usa esta opción cuando no puedas usar el llavero de claves y necesites una opción que admita la autenticación básica de contraseñas.

En las instrucciones de esta documentación, se describe la configuración de pip como el único índice de paquetes que pip busca para los paquetes. Recomendamos usar repositorios virtuales para buscar paquetes en tus paquetes privados en Artifact Registry y paquetes públicos de PyPI, en lugar de configurar varios índices de paquetes en el archivo de configuración pip. La herramienta pip no busca índices de paquetes en ningún orden en particular, por lo que tus consumidores podrían descargar o instalar por error un paquete público con el mismo nombre que uno de tus paquetes privados. Los repositorios virtuales te permiten configurar prioridades para las fuentes ascendentes a fin de mitigar este riesgo de confusión de dependencias.

Autentica con llavero de claves

La biblioteca de llavero de claves de Python proporciona a las aplicaciones una forma de acceder a los backends de llavero de claves, es decir, los almacenes de credenciales del sistema operativo y de terceros.

Artifact Registry proporciona el backend de llavero de claves keyrings.google-artifactregistry-auth para controlar la autenticación con repositorios de Artifact Registry.

Orden de búsqueda de credenciales

Cuando usas el backend del llavero de claves de Artifact Registry, las credenciales no se almacenan en el proyecto de Python. En su lugar, Artifact Registry busca las credenciales en el siguiente orden:

Las credenciales predeterminadas de la aplicación (ADC), que es una estrategia que busca credenciales en el siguiente orden:
1. Credenciales definidas en la variable de entorno GOOGLE_APPLICATION_CREDENTIALS
2. Credenciales que proporciona la cuenta de servicio predeterminada para Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine o Cloud Functions
Las credenciales que proporciona Google Cloud CLI, incluidas las credenciales de usuario del comando gcloud auth application-default login.

La variable GOOGLE_APPLICATION_CREDENTIALS hace que la cuenta sea explícita para la autenticación, lo que facilita la solución de problemas. Si no usas la variable, verifica que las cuentas que ADC pueda usar tengan los permisos necesarios. Por ejemplo, la cuenta de servicio predeterminada para las VM de Compute Engine, los nodos de Google Kubernetes Engine y las revisiones de Cloud Run tienen acceso de solo lectura a los repositorios. Si deseas subir datos desde estos entornos con la cuenta de servicio predeterminada, debes modificar los permisos.

Configura el llavero de claves

Sigue estos pasos para configurar la autenticación con el backend del llavero de claves de Artifact Registry:

Instala la biblioteca de llavero de claves.
```
pip install keyring
```

Instala el backend de Artifact Registry.

pip install keyrings.google-artifactregistry-auth

Muestra una lista de backends para confirmar la instalación.
```
keyring --list-backends
```
La lista debe incluir
- ChainerBackend(priority:10)
- GooglePythonAuth(priority: 9)
Ejecuta el siguiente comando para imprimir la configuración del repositorio que se agregará a tu proyecto de Python.
```
gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION
```
Reemplaza los siguientes valores:
- PROJECT es el ID del proyecto. Si se omite esta marca, se usa el proyecto predeterminado o actual.
- REPOSITORY es el ID del repositorio. Si configuraste un repositorio predeterminado de Artifact Registry, se usa cuando se omite esta marca del comando.
- LOCATION es la ubicación regional o multirregional del repositorio.
Agrega la siguiente configuración al archivo .pypirc. La ubicación predeterminada es la siguiente:
- Linux y macOS: $HOME/.pypirc
- Windows: %USERPROFILE%\.pypirc
```
[distutils]
index-servers =
    PYTHON-REPO-ID

[PYTHON-REPO-ID]
repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/
```
Reemplaza los siguientes valores:
- PYTHON-REPO-ID es un ID para el repositorio al que puedes hacer referencia con herramientas como Twine.
- PROJECT es el ID del proyecto. Si se omite esta marca, se usa el proyecto predeterminado o actual.
- REPOSITORY es el ID del repositorio. Si configuraste un repositorio predeterminado de Artifact Registry, se usa cuando se omite esta marca del comando.
- LOCATION es la ubicación regional o multirregional del repositorio.
Agrega tu repositorio al archivo de configuración de pip. La ubicación del archivo depende de si deseas actualizar el archivo por usuario o el archivo específico de un entorno virtual que usas.

Para el archivo asociado con el usuario de tu sistema operativo, haz lo siguiente:
- Unix: $HOME/.config/pip/pip.conf o $HOME/.pip/pip.conf
- macOS: /Library/Application Support/pip/pip.conf o $HOME/.config/pip/pip.conf
- Windows: %APPDATA%\pip\pip.ini o %USERPROFILE%\pip\pip.ini
Para entornos virtuales:
- Unix y macOS: $VIRTUAL_ENV/pip.conf
- Windows: %VIRTUAL_ENV%\pip.ini
Si deseas configurar pip para que solo busque en tu repositorio, usa la configuración index-url y asegúrate de que no haya otros índices de paquetes configurados con el parámetro extra-index-url.
```
[global]
index-url = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/
```
La cadena /simple/ al final de la ruta del repositorio indica que el repositorio implementa la API de Simple Repository de Python.

Tu entorno de Python ahora está configurado para autenticarse con Artifact Registry.

Autenticación mediante llavero de claves con credenciales de usuario

Después de configurar el llavero de claves, puedes usarlo con tus credenciales de usuario en gcloud CLI. Accede a Google Cloud CLI antes de conectarte a un repositorio de paquetes de Python.

Ejecuta el siguiente comando:

gcloud auth login

Autenticación mediante llavero de claves con credenciales de cuenta de servicio

Después de configurar el llavero de claves, puedes configurar una cuenta de servicio para la autenticación.

Crea una cuenta de servicio o elige una existente que uses para la automatización.
Otorga el rol de Artifact Registry específico a la cuenta de servicio para proporcionar acceso al repositorio.
Usa una de las siguientes opciones para autenticar con tu cuenta de servicio:
- Credenciales predeterminadas de la aplicación (recomendado)
  
  Asigna la ubicación del archivo de claves de la cuenta de servicio a la variable GOOGLE_APPLICATION_CREDENTIALS para que el auxiliar de credenciales de Artifact Registry pueda obtener tu clave cuando se conecta con repositorios.
```
export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
```
- Credenciales de la CLI de gcloud
  
  Antes de conectarte a un repositorio, accede como la cuenta de servicio. Evita esta opción si te conectas a repositorios desde VM de Compute Engine, ya que Artifact Registry encuentra las credenciales de la cuenta de servicio de la VM antes que las credenciales en gcloud CLI.
```
gcloud auth activate-service-account --key-file=KEY-FILE
```
Reemplaza KEY-FILE por la ruta de acceso al archivo de claves de la cuenta de servicio.

Autentica con una clave de cuenta de servicio

Usa este enfoque cuando necesites autenticación con un nombre de usuario y contraseña.

Las claves de la cuenta de servicio son credenciales de larga duración. Usa los siguientes lineamientos para limitar el acceso a tus repositorios:

Considera usar una cuenta de servicio dedicada para interactuar con los repositorios.
Otorga la función mínima de Artifact Registry que requiera la cuenta de servicio. Por ejemplo, asigna la función de lector de Artifact Registry a una cuenta de servicio que solo descargue artefactos.
Si los grupos de tu organización requieren diferentes niveles de acceso a repositorios específicos, otorga acceso a nivel de repositorio en lugar de a nivel de proyecto.
Sigue las prácticas recomendadas para administrar credenciales.

Para configurar la autenticación, sigue estos pasos:

Crea una cuenta de servicio que actúe en nombre de tu aplicación o elige una cuenta de servicio existente que uses para la automatización.

Necesitarás la ubicación del archivo de claves de la cuenta de servicio para configurar la autenticación con Artifact Registry. En las cuentas existentes, puedes ver claves y crear claves nuevas en la página Cuentas de servicio.

Ir a la página Cuentas de servicio

Nota: Las claves de cuenta de servicio son un riesgo de seguridad si no se administran de forma adecuada. Debes elegir una alternativa más segura a las claves de la cuenta de servicio siempre que sea posible. Si te debes autenticar con una clave de cuenta de servicio, eres responsable de la seguridad de la clave privada y de otras operaciones que se describen en Prácticas recomendadas para administrar claves de cuenta de servicio. Si no se te permite crear una clave de cuenta de servicio, es posible que la creación de claves de cuentas de servicio esté inhabilitada para tu organización. Para obtener más información, consulta Administra los recursos de la organización con seguridad de forma predeterminada.
Otorga la función adecuada de Artifact Registry a la cuenta de servicio para proporcionar acceso al repositorio.
Ejecuta el siguiente comando para imprimir la configuración del repositorio que se agregará a tu proyecto de Python.
```
gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --json-key=KEY-FILE
```
Reemplaza los siguientes valores:
- PROJECT es el ID del proyecto. Si se omite esta marca, se usa el proyecto predeterminado o actual.
- REPOSITORY es el ID del repositorio. Si configuraste un repositorio predeterminado de Artifact Registry, se usa cuando se omite esta marca del comando.
- LOCATION es la ubicación regional o multirregional del repositorio.
- KEY-FILE es la ruta al archivo de claves JSON de la cuenta de servicio.
Agrega la siguiente configuración al archivo .pypirc. La ubicación predeterminada es la siguiente para el archivo de configuración pip por usuario:
- Linux y 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
```
Reemplaza los siguientes valores:
- PYTHON-REPO-ID es un ID para el repositorio al que puedes hacer referencia con herramientas como Twine.
- PROJECT es el ID del proyecto. Si se omite esta marca, se usa el proyecto predeterminado o actual.
- REPOSITORY es el ID del repositorio. Si configuraste un repositorio predeterminado de Artifact Registry, se usa cuando se omite esta marca del comando.
- LOCATION es la ubicación regional o multirregional del repositorio.
- KEY es la clave codificada en base64 en el archivo de claves de tu cuenta de servicio.
Agrega tu repositorio al archivo de configuración de pip. La ubicación del archivo de configuración de pip depende de si deseas actualizar el archivo por usuario o el archivo específico de un entorno virtual que usas.

Para el archivo asociado con el usuario de tu sistema operativo, haz lo siguiente:
- Unix: $HOME/.config/pip/pip.conf o $HOME/.pip/pip.conf
- macOS: /Library/Application Support/pip/pip.conf o $HOME/.config/pip/pip.conf
- Windows: %APPDATA%\pip\pip.ini o %USERPROFILE%\pip\pip.ini
Para entornos virtuales:
- Unix y macOS: $VIRTUAL_ENV/pip.conf
- Windows: %VIRTUAL_ENV%\pip.ini
Agrega la siguiente línea al archivo de configuración de pip:
```
[global]
index-url = https://_json_key_base64:KEY@LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/
```
- KEY es la clave privada en el archivo de claves de tu cuenta de servicio.
- La cadena /simple/ al final de la ruta del repositorio indica que el repositorio implementa la API de Simple Repository de Python.