Esta página se ha traducido con Cloud Translation API.

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

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

Debe autenticarse en Artifact Registry cuando utilice una aplicación de terceros para conectarse a un repositorio.

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

Antes de empezar

Si el repositorio de destino no existe, crea un repositorio de paquetes de Python.
Comprueba que Python 3 esté instalado. Para obtener instrucciones de instalación, consulta elGoogle Cloud tutorial para configurar Python.
Verifica que la cuenta de usuario o de servicio que estás usando tenga los permisos necesarios para acceder al repositorio.
Instala Google Cloud CLI. Después de la instalación, inicializa la CLI de Google Cloud ejecutando el siguiente comando:
```
gcloud init
```
Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Nota: Si ya has instalado la CLI de gcloud, asegúrate de que tienes la versión más reciente ejecutando gcloud components update.
(Opcional) Configura los valores predeterminados de los comandos de gcloud CLI.

Información general

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

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

En las instrucciones de esta documentación se describe cómo configurar pip como el único índice de paquetes en el que pip busca paquetes. Te recomendamos que uses repositorios virtuales para buscar paquetes en tus paquetes privados de Artifact Registry y en los paquetes públicos de PyPI, en lugar de configurar varios índices de paquetes en el archivo de configuración de pip. La herramienta pip no busca índices de paquetes en ningún orden concreto, por lo que es posible que tus consumidores descarguen o instalen 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 upstream y, de esta forma, mitigar el riesgo de confusión de dependencias.

Autenticación con llavero

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

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

Orden de búsqueda de credenciales

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

Credenciales predeterminadas de la aplicación (ADC), 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 de Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine o las funciones de Cloud Run.
Credenciales proporcionadas por la CLI de Google Cloud, incluidas las credenciales de usuario del comando gcloud auth application-default login.

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

Configurar el llavero

Para configurar la autenticación con el backend del llavero de Artifact Registry, sigue estos pasos:

Instala la biblioteca keyring.
```
pip install keyring
```

Instala el backend de Artifact Registry.

pip install keyrings.google-artifactregistry-auth

Lista los back-ends 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 quieres añadir a tu proyecto de Python.
```
gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION
```
Sustituye los siguientes valores:
- PROJECT es el ID del proyecto. Si se omite esta marca, se usará el proyecto predeterminado o el actual.
- REPOSITORY es el ID del repositorio. Si has configurado un repositorio predeterminado de Artifact Registry, se usará cuando se omita esta marca en el comando.
- LOCATION es la ubicación regional o multirregional del repositorio.
Añade los siguientes ajustes al archivo .pypirc. La ubicación predeterminada es:
- 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/
```
Sustituye los siguientes valores:
- PYTHON-REPO-ID es un ID del repositorio que puedes consultar con herramientas como Twine.
- PROJECT es el ID del proyecto. Si se omite esta marca, se usará el proyecto predeterminado o el actual.
- REPOSITORY es el ID del repositorio. Si has configurado un repositorio predeterminado de Artifact Registry, se usará cuando se omita esta marca en el comando.
- LOCATION es la ubicación regional o multirregional del repositorio.
Añade tu repositorio al archivo de configuración de pip. La ubicación del archivo depende de si quieres actualizar el archivo por usuario o el archivo específico del entorno virtual que estés usando.

En el archivo asociado al usuario de tu sistema operativo:
- 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
En entornos virtuales:
- Unix y macOS: $VIRTUAL_ENV/pip.conf
- Windows: %VIRTUAL_ENV%\pip.ini
Para configurar pip de forma que solo busque en tu repositorio, usa el ajuste index-url y asegúrate de que no haya otros índices de paquetes configurados con el ajuste 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 repositorio simple de Python.

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

Autenticación de llavero con credenciales de usuario

Una vez que hayas configurado el llavero, podrás usarlo con tus credenciales de usuario en gcloud CLI. Inicia sesión en Google Cloud CLI antes de conectarte a un repositorio de paquetes de Python.

Ejecuta el siguiente comando:

gcloud auth login

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

Una vez que hayas configurado el llavero de claves, podrás configurar una cuenta de servicio para la autenticación.

Crea una cuenta de servicio o elige una que ya tengas y que uses para la automatización.
Concede el rol de Artifact Registry específico a la cuenta de servicio para proporcionar acceso al repositorio.
Usa una de las siguientes opciones para autenticarte con tu cuenta de servicio:
- Credenciales de aplicación predeterminadas (recomendado)
  
  Asigna la ubicación del archivo de clave de cuenta de servicio a la variable GOOGLE_APPLICATION_CREDENTIALS para que el asistente de credenciales de Artifact Registry pueda obtener tu clave al conectarse con los repositorios.
```
export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
```
- Credenciales de la CLI de gcloud
  
  Antes de conectarte a un repositorio, inicia sesión como cuenta de servicio. Evita esta opción si te conectas a repositorios desde máquinas virtuales de Compute Engine, ya que Artifact Registry encuentra las credenciales de la cuenta de servicio de la máquina virtual antes que las credenciales de la CLI de gcloud.
```
gcloud auth activate-service-account --key-file=KEY-FILE
```
Sustituye KEY-FILE por la ruta al archivo de clave de la cuenta de servicio.

Autenticarse con una clave de cuenta de servicio

Usa este método cuando necesites autenticarte con un nombre de usuario y una contraseña.

Las claves de cuenta de servicio son credenciales de larga duración. Sigue estas directrices para limitar el acceso a tus repositorios:

Te recomendamos que uses una cuenta de servicio específica para interactuar con los repositorios.
Asigna el rol de Artifact Registry mínimo que requiere la cuenta de servicio. Por ejemplo, asigna el rol 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, concede acceso a nivel de repositorio en lugar de a nivel de proyecto.
Sigue las prácticas recomendadas para gestionar las credenciales.

Para configurar la autenticación, sigue estos pasos:

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

Necesitarás la ubicación del archivo de clave de cuenta de servicio para configurar la autenticación con Artifact Registry. En el caso de las cuentas que ya tengas, puedes ver las claves y crear otras en la página Cuentas de servicio.

Ir a la página Cuentas de servicio

Nota: Las claves de las cuentas de servicio suponen un riesgo para la seguridad si no se gestionan adecuadamente. Siempre que sea posible, deberías elegir una alternativa más segura a las claves de cuentas de servicio. Si debes autenticarte con una clave de cuenta de servicio, eres responsable de la seguridad de la clave privada y de otras operaciones descritas en las prácticas recomendadas para gestionar las claves de cuentas de servicio. Si no puedes crear una clave de cuenta de servicio, es posible que la creación de claves de cuenta de servicio esté inhabilitada en tu organización. Para obtener más información, consulta el artículo sobre gestionar recursos de organización seguros de forma predeterminada.
Si has obtenido la clave de cuenta de servicio de una fuente externa, debes validarla antes de usarla. Para obtener más información, consulta los requisitos de seguridad de las credenciales de fuentes externas.
Concede el rol de Artifact Registry adecuado a la cuenta de servicio para proporcionar acceso al repositorio.
Ejecuta el siguiente comando para imprimir la configuración del repositorio que quieres añadir a tu proyecto de Python.
```
gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --json-key=KEY-FILE
```
Sustituye los siguientes valores:
- PROJECT es el ID del proyecto. Si se omite esta marca, se usará el proyecto predeterminado o el actual.
- REPOSITORY es el ID del repositorio. Si has configurado un repositorio predeterminado de Artifact Registry, se usará cuando se omita esta marca en el comando.
- LOCATION es la ubicación regional o multirregional del repositorio.
- KEY-FILE es la ruta al archivo JSON de la cuenta de servicio key file.
Añade los siguientes ajustes al archivo .pypirc. La ubicación predeterminada del archivo de configuración de pip por usuario es:
- 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
```
Sustituye los siguientes valores:
- PYTHON-REPO-ID es un ID del repositorio que puedes consultar con herramientas como Twine.
- PROJECT es el ID del proyecto. Si se omite esta marca, se usará el proyecto predeterminado o el actual.
- REPOSITORY es el ID del repositorio. Si has configurado un repositorio predeterminado de Artifact Registry, se usará cuando se omita esta marca en el comando.
- LOCATION es la ubicación regional o multirregional del repositorio.
- KEY es la clave codificada en base64 del archivo de clave de tu cuenta de servicio.
Añade tu repositorio al archivo de configuración de pip. La ubicación del archivo de configuración de pip depende de si quieres actualizar el archivo por usuario o el archivo específico de un entorno virtual que estés usando.

En el archivo asociado al usuario de tu sistema operativo:
- 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
En entornos virtuales:
- Unix y macOS: $VIRTUAL_ENV/pip.conf
- Windows: %VIRTUAL_ENV%\pip.ini
Añade 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 la clave privada del archivo de clave de tu cuenta de servicio.
- La cadena /simple/ al final de la ruta del repositorio indica que el repositorio implementa la API de repositorio simple de Python.