Configura la autenticación para repositorios de PyPI

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

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

La integración en los servicios de Google Cloud, como Cloud Build o Google Kubernetes Engine, no requiere autenticación. Sin embargo, debes verificar que las identidades que actúan en nombre de estos servicios tengan los permisos necesarios para acceder a los repositorios.

La administración de paquetes se encuentra en versión Alfa. Solo está disponible para los usuarios Alfa y es posible que no incluya todas las funciones disponibles para la administración de contenedores. Si deseas postularte para la versión Alfa, completa el formulario de registro. Si quieres obtener más información, consulta Requisitos para acceder a las funciones Alfa.

Antes de comenzar

  1. Verifica que hayas habilitado la API de Artifact Registry y que instalaste el SDK de Cloud. Consulta Habilita y, luego, inhabilita el servicio para obtener instrucciones.

    Se requiere la versión de 329.0.0 de la herramienta de línea de comandos de gcloud a fin de ejecutar comandos para los repositorios de PyPI. Para verificar la versión, usa el siguiente comando:

    gcloud version
    
  2. Si el repositorio de destino no existe, crea un repositorio de PyPI nuevo.

  3. Verifique que Python 3 esté instalado. Si deseas obtener instrucciones de instalación, consulta el instructivo para configurar Python en Google Cloud.

  4. Verifica que la cuenta de usuario o cuenta de servicio que uses tenga los permisos necesarios para acceder al repositorio.

  5. (Opcional) Configura valores predeterminados para los comandos de gcloud.

Descripción general

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

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

Cómo autenticar con llavero de claves

La biblioteca de llavero de claves de Python proporciona a las aplicaciones una forma de acceder a backends de llavero de claves, lo que significa que el sistema operativo y los almacenes de credenciales de terceros son los siguientes.

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

Orden de búsqueda de credenciales

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

  1. 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

  2. Credenciales que proporciona el SDK de Cloud, 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 prefieres subir contenido desde estos entornos mediante la cuenta de servicio predeterminada, debes modificar los permisos.

Configura el llavero de claves

Para configurar la autenticación con el backend del llavero de claves de Artifact Registry, haz lo siguiente:

  1. En la versión 21.1 de pip, se cambió el comportamiento para consultar el llavero de claves a las credenciales. Para asegurarte de que usas una versión de pip que puede autenticarse con repositorios de Artifact Registry, haz lo siguiente:

    1. Verifica tu versión de pip.

      pip --version
      
    2. Si estás usando la versión 21.1 o una posterior, instala la versión 21.0.1.

      python -m pip install pip==21.0.1
      
  2. Instala la biblioteca de llavero de claves.

    pip install keyring
    
  3. Instala el backend de Artifact Registry.

    pip install keyrings.google-artifactregistry-auth
    
  4. Enumera los backends para confirmar la instalación.

    keyring --list-backends
    

    La lista debe incluir

    • ChainerBackend(priority:10)
    • GooglePyPIAuth(priority: 9)
  5. Ejecuta el siguiente comando para imprimir la configuración del repositorio a fin de agregarla a tu proyecto de Python.

    gcloud alpha artifacts print-settings pypi [--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.
  6. Agrega la siguiente configuración al archivo .pypirc. La ubicación predeterminada es para el archivo de configuración pip por usuario:

    • Linux y MacOS: $HOME/.pypirc
    • Windows: %USERPROFILE%\.pypirc
    [distutils]
    index-servers =
        PYPI-REPO-ID
    
    [PYPI-REPO-ID]
    repository: https://LOCATION-pypi.pkg.dev/PROJECT/REPOSITORY/
    

    Reemplaza los siguientes valores:

    • PYPI-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.
  7. Edita el archivo de configuración de pip para incluir la siguiente configuración en la sección [global]. La ubicación predeterminada es para el archivo de configuración pip por usuario:

    • Linux: $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 configurar pip a fin de que solo busque un repositorio especificado de Artifact Registry, agrega el repositorio con la sección [global] de la configuración index-url:

    [global]
    index-url = https://LOCATION-pypi.pkg.dev/PROJECT/REPOSITORY/simple/
    

    Si deseas configurar pip para que busque pypi.org y otros índices de paquetes configurados, usa la configuración extra-index-url en la sección [global]. Si tu configuración incluye varios índices de paquetes, pip busca pypi.org y cualquier otro índice de paquete configurado y elige la versión más reciente del paquete.

    [global]
    extra-index-url = https://LOCATION-pypi.pkg.dev/PROJECT/REPOSITORY/simple/
    

    La string /simple/ al final de la ruta del repositorio indica que el repositorio implementa la API de repositorio simple de Python.

Ahora, tu entorno de Python está configurado para autenticarse con Artifact Registry.

Cómo autenticar claves con credenciales de usuario

Una vez que configuraste el llavero de claves, puedes usarlo con tus credenciales de usuario en gcloud. Accede al SDK de Cloud antes de conectarte a un repositorio de PyPI.

Ejecuta el siguiente comando:

gcloud auth login

Cómo autenticar claves con credenciales de cuenta de servicio

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

  1. Crea una cuenta de servicio o elige una cuenta de servicio existente que uses para la automatización.
  2. Otorga la función de registro de artefactos adecuada a la cuenta de servicio para proporcionar acceso al repositorio.
  3. Utiliza 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 gcloud

      Antes de conectarte a un repositorio, accede como la cuenta de servicio. Evita esta opción si te conectas a repositorios de VM de Compute Engine, ya que Artifact Registry busca las credenciales de la cuenta de servicio de VM antes de las credenciales en gcloud.

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

    Reemplaza KEY-FILE con 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 una 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:

  1. 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

  2. Otorga la función de registro de artefactos adecuada a la cuenta de servicio para proporcionar acceso al repositorio.

  3. Ejecuta el siguiente comando para imprimir la configuración del repositorio a fin de agregarla a tu proyecto de Python.

    gcloud alpha artifacts print-settings pypi [--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.
  4. Agrega la siguiente configuración al archivo .pypirc. La ubicación predeterminada es para el archivo de configuración pip por usuario:

    • Linux y MacOS: $HOME/.pypirc
    • Windows: %USERPROFILE%\.pypirc
    [distutils]
    index-servers =
        PYPI-REPO-ID
    
    [PYPI-REPO-ID]
    repository: https://LOCATION-pypi.pkg.dev/PROJECT/REPOSITORY/
    username: _json_key_base64
    password: KEY
    

    Reemplaza los siguientes valores:

    • PYPI-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 privada en el archivo de claves de tu cuenta de servicio.
  5. Edita el archivo de configuración de pip para incluir la siguiente configuración en la sección [global]. La ubicación predeterminada es para el archivo de configuración pip por usuario:

    • Linux: $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 configurar pip a fin de que solo busque un repositorio especificado de Artifact Registry, agrega la siguiente configuración a la sección [global]:

    [global]
    index-url = https://_json_key_base64:KEY@LOCATION-pypi.pkg.dev/PROJECT/REPOSITORY/simple/
    

    Si deseas configurar pip para que también busque pypi.org, agrega la siguiente configuración a la sección [global]. No hay un orden de búsqueda específico, por lo que las herramientas como pip y Twin pueden buscar pypi.org primero o último. Te recomendamos que uses nombres únicos para los paquetes privados que almacenes en tu repositorio de Artifact Registry.

    [global]
    extra-index-url = https://_json_key_base64:KEY@LOCATION-pypi.pkg.dev/PROJECT/REPOSITORY/simple/
    
    • KEY la clave privada en el archivo de claves de tu cuenta de servicio
    • La string /simple/ al final de la ruta del repositorio indica que el repositorio implementa la API de repositorio simple de Python.

¿Qué sigue?