Instalar dependencias de Python

Cloud Composer 3 | Cloud Composer 2 | Cloud Composer 1

En esta página se describe cómo instalar paquetes de Python en tu entorno de Cloud Composer.

Acerca de los paquetes de Cloud Composer

En esta sección se explica cómo funcionan los paquetes de PyPI en Cloud Composer.

Paquetes PyPI preinstalados y personalizados en imágenes de Cloud Composer

Las imágenes de Cloud Composer contienen paquetes PyPI preinstalados y personalizados.

• Los paquetes PyPI preinstalados son paquetes que se incluyen en la imagen de Cloud Composer de tu entorno. Cada imagen de Cloud Composer contiene paquetes de PyPI específicos de tu versión de Cloud Composer y Airflow.

• Los paquetes de PyPI personalizados son paquetes que puedes instalar en tu entorno además de los paquetes preinstalados.

Nota: Si tienes previsto actualizar tu entorno, puedes hacer una comprobación de la actualización. Esta comprobación indica si los paquetes PyPI personalizados de tu entorno tienen algún conflicto con los paquetes preinstalados en una imagen de Cloud Composer posterior.

Opciones para gestionar paquetes de PyPI en entornos de Cloud Composer

Opción	Úsala si
Instalar desde PyPI	La forma predeterminada de instalar paquetes en tu entorno
Instalar desde un repositorio con una dirección IP pública	El paquete está alojado en un repositorio de paquetes que no es PyPI. Este repositorio tiene una dirección IP pública
Instalar desde un repositorio de Artifact Registry	El paquete está alojado en un repositorio de Artifact Registry
Instalar desde un repositorio en la red de tu proyecto	Tu entorno no tiene acceso a Internet público. El paquete está alojado en un repositorio de paquetes de la red de tu proyecto.
Instalar como biblioteca local de Python	No se encuentra el paquete en PyPI y la biblioteca no tiene dependencias externas, como dist-packages.
Instalar un complemento	El paquete proporciona funciones específicas del complemento, como la modificación de la interfaz web de Airflow.
PythonVirtualenvOperator	No quieres que el paquete se instale en todos los trabajadores de Airflow o la dependencia entra en conflicto con los paquetes preinstalados. El paquete se puede encontrar en PyPI y no tiene dependencias externas.
KubernetesPodOperator y operadores de GKE	Necesitas dependencias externas que no se puedan instalar desde pip, como dist-packages, o que estén en un servidor pip interno. Esta opción requiere más configuración y mantenimiento. Solo debes tenerlo en cuenta si no funcionan otras opciones.

Antes de empezar

• Debes tener un rol que pueda activar operaciones de actualización del entorno. Además, la cuenta de servicio del entorno debe tener un rol con permisos suficientes para realizar operaciones de actualización.

  Importante: Cuando instalas paquetes de PyPI en tu entorno, Airflow ejecuta código Python del paquete instalado. Asegúrate de instalar paquetes de fuentes de confianza. Los usuarios con el permiso composer.environments.update pueden ejecutar código de Python en nombre de la cuenta de servicio del entorno al instalar paquetes en tu entorno. Para obtener más información, consulta Control de acceso.

• Si tu entorno está protegido por un perímetro de Controles de Servicio de VPC, antes de instalar las dependencias de PyPI, debes conceder identidades de usuario adicionales con acceso a los servicios que protege el perímetro de servicio y habilitar la compatibilidad con un repositorio privado de PyPI.

• Los requisitos deben seguir el formato especificado en PEP-508, donde cada requisito se especifica en minúsculas y consta del nombre del paquete con extras y especificadores de versión opcionales.

• Las actualizaciones de dependencias de PyPI generan imágenes Docker en Artifact Registry.

  Advertencia: No modifiques ni elimines las imágenes creadas por Cloud Composer en Artifact Registry ni el propio repositorio. No subas tus propias imágenes al repositorio. En su lugar, crea y mantén tu propio repositorio de imágenes (por ejemplo, para las imágenes que usa KubernetesPodOperator). No elimines este repositorio por tu cuenta. El repositorio se elimina después de que elimines tu entorno.

• Si un conflicto de dependencias provoca un error en la actualización, tu entorno seguirá funcionando con las dependencias que ya tenía. Si la operación se realiza correctamente, puedes empezar a usar las dependencias de Python recién instaladas en tus DAGs.

• PythonVirtualenvOperator no usa la configuración del archivo pip.conf de tu entorno. Si quieres usar dependencias específicas, como instalarlas desde un índice personalizado, transfiere los requisitos en el parámetro requirements como una lista de cadenas. Para obtener más información sobre el formato, consulta Requirements File Format (Formato de archivo de requisitos) en la documentación de pip.

Ver la lista de paquetes de PyPI

Puedes obtener la lista de paquetes de tu entorno en varios formatos.

Ver paquetes preinstalados

Para ver la lista de paquetes preinstalados de tu entorno, consulta la lista de paquetes de la imagen de Cloud Composer de tu entorno.

Ver todos los paquetes

Para ver todos los paquetes (tanto preinstalados como personalizados) de tu entorno, haz lo siguiente:

gcloud

El siguiente comando de gcloud CLI devuelve el resultado del comando python -m pip list para un trabajador de Airflow de tu entorno. Puedes usar el argumento --tree para obtener el resultado del comando python -m pipdeptree --warn.

gcloud beta composer environments list-packages \
    ENVIRONMENT_NAME \
    --location LOCATION

Sustituye:

• ENVIRONMENT_NAME con el nombre del entorno.
• LOCATION con la región en la que se encuentra el entorno.

Ver paquetes PyPI personalizados

Consola

1. En la Google Cloud consola, ve a la página Entornos.

   Ir a Entornos

2. En la lista de entornos, haz clic en el nombre del entorno. Se abrirá la página Detalles del entorno.

3. Ve a la pestaña Paquetes de PyPI.

gcloud

gcloud composer environments describe ENVIRONMENT_NAME \
  --location LOCATION \
  --format="value(config.softwareConfig.pypiPackages)"

Sustituye:

• ENVIRONMENT_NAME con el nombre del entorno.
• LOCATION con la región en la que se encuentra el entorno.

Instalar paquetes personalizados en un entorno de Cloud Composer

En esta sección se describen diferentes métodos para instalar paquetes personalizados en tu entorno.

Instalar paquetes de PyPI

Un paquete se puede instalar desde el índice de paquetes de Python si no tiene dependencias externas o conflictos con paquetes preinstalados.

Nota: Puedes flexibilizar las restricciones de versión de los paquetes PyPI personalizados instalados. Por ejemplo, en lugar de especificar una versión como ==1.0.1, especifícala como >=1.0.1.

Para añadir, actualizar o eliminar las dependencias de Python de tu entorno, sigue estos pasos:

Consola

1. En la Google Cloud consola, ve a la página Entornos.

   Ir a Entornos

2. En la lista de entornos, haz clic en el nombre del entorno. Se abrirá la página Detalles del entorno.

3. Ve a la pestaña Paquetes de PyPI.

4. Haz clic en Editar.

5. Haz clic en Añadir paquete.

6. En la sección Paquetes de PyPI, especifica los nombres de los paquetes, con especificadores de versión y extras opcionales.

   Por ejemplo:

   • scikit-learn
   • scipy, >=0.13.3
   • nltk, [machine_learning]

7. Haz clic en Guardar.

gcloud

La CLI de gcloud tiene varios argumentos para trabajar con paquetes de PyPI personalizados:

• --update-pypi-packages-from-file sustituye todos los paquetes de PyPI personalizados que ya tengas por los paquetes especificados. Los paquetes que no especifiques se eliminarán.
• --update-pypi-package actualiza o instala un paquete.
• --remove-pypi-packages elimina los paquetes especificados.
• --clear-pypi-packages elimina todos los paquetes.

Instalar requisitos desde un archivo

El archivo requirements.txt debe tener cada especificador de requisito en una línea independiente.

Por ejemplo:

scipy>=0.13.3
scikit-learn
nltk[machine_learning]

Actualiza tu entorno y especifica el archivo requirements.txt en el argumento --update-pypi-packages-from-file.

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --update-pypi-packages-from-file requirements.txt

Sustituye:

• ENVIRONMENT_NAME con el nombre del entorno.
• LOCATION con la región en la que se encuentra el entorno.

Instalar un paquete

Actualiza tu entorno y especifica el paquete, la versión y los extras en el argumento --update-pypi-package.

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --update-pypi-package PACKAGE_NAMEEXTRAS_AND_VERSION

Sustituye:

• ENVIRONMENT_NAME con el nombre del entorno.
• LOCATION con la región en la que se encuentra el entorno.
• PACKAGE_NAME con el nombre del paquete.
• EXTRAS_AND_VERSION con el especificador opcional de versión y extras. Para omitir versiones y extras, especifica un valor vacío.

Nota: En función de tu entorno de ejecución, puede que tengas que aplicar un formato de escape a caracteres especiales, como >. Para evitar posibles problemas, ponga el nombre del paquete y la versión entre comillas. Por ejemplo: "scipy>=0.13.0".

Ejemplo:

gcloud composer environments update example-environment \
    --location us-central1 \
    --update-pypi-package "scipy>=0.13.3"

Eliminar paquetes

Actualiza tu entorno y especifica los paquetes que quieras eliminar en el argumento --remove-pypi-packages:

gcloud composer environments update ENVIRONMENT_NAME \
    --location LOCATION \
     --remove-pypi-packages PACKAGE_NAMES

Sustituye:

• ENVIRONMENT_NAME con el nombre del entorno.
• LOCATION con la región en la que se encuentra el entorno.
• PACKAGE_NAMES con una lista de paquetes separados por comas.

Ejemplo:

gcloud composer environments update example-environment \
    --location us-central1 \
    --remove-pypi-packages scipy,scikit-learn

API

Crea una solicitud de la API environments.patch.

En esta solicitud:

1. En el parámetro updateMask, especifica la máscara:

   • Usa la máscara config.softwareConfig.pypiPackages para sustituir todos los paquetes por los paquetes especificados. Se eliminan los paquetes que no especifiques.
   • Usa config.softwareConfig.envVariables.PACKAGE_NAME para añadir o actualizar un paquete específico. Para añadir o actualizar varios paquetes, especifica varias máscaras separadas por comas.

2. En el cuerpo de la solicitud, especifica los paquetes y los valores de las versiones y los extras:

   {
     "config": {
       "softwareConfig": {
         "pypiPackages": {
           "PACKAGE_NAME": "EXTRAS_AND_VERSION"
         }
       }
     }
   }
   

   Sustituye:

   • PACKAGE_NAME con el nombre del paquete.
   • EXTRAS_AND_VERSION con el especificador opcional de versión y extras. Para omitir versiones y extras, especifica un valor vacío.
   • Para añadir más de un paquete, añade entradas adicionales para los paquetes en pypiPackages.

Ejemplo:

// PATCH https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/environments/example-environment?updateMask=
// config.softwareConfig.pypiPackages.EXAMPLE_PACKAGE,
// config.softwareConfig.pypiPackages.ANOTHER_PACKAGE
{
  "config": {
    "softwareConfig": {
      "pypiPackages": {
        "EXAMPLE_PACKAGE": "",
        "ANOTHER_PACKAGE": ">=1.10.3"
      }
    }
  }
}

Terraform

El bloque pypi_packages del bloque software_config especifica los paquetes.

resource "google_composer_environment" "example" {
  name = "ENVIRONMENT_NAME"
  region = "LOCATION"

  config {

    software_config {

      pypi_packages = {
          PACKAGE_NAME = "EXTRAS_AND_VERSION"
      }

    }
  }
}

Sustituye:

• ENVIRONMENT_NAME con el nombre del entorno.
• LOCATION con la región en la que se encuentra el entorno.
• PACKAGE_NAME con el nombre del paquete.
• EXTRAS_AND_VERSION con el especificador opcional de versión y extras. Para omitir versiones y extras, especifica un valor vacío.
• Para añadir más de un paquete, añade entradas adicionales para los paquetes en pypi_packages.

Ejemplo:

resource "google_composer_environment" "example" {
  name = "example-environment"
  region = "us-central1"

  config {

    software_config {
      pypi_packages = {
          scipy = ">=1.10.3"
          scikit-learn = ""
          nltk = "[machine_learning]"
      }
    }
  }
}

Instalar paquetes desde un repositorio público

Puedes instalar paquetes alojados en otros repositorios que tengan una dirección IP pública.

Los paquetes deben estar configurados correctamente para que la herramienta pip predeterminada pueda instalarlos.

Nota: Cloud Composer no admite la personalización de pip y no resuelve las dependencias ni los conflictos de paquetes fuera de los mecanismos de resolución que proporciona la herramienta pip predeterminada.

Para instalar desde un repositorio de paquetes que tenga una dirección pública, sigue estos pasos:

1. Crea un archivo pip.conf e incluye la siguiente información en él, si procede:

   • URL del repositorio (en el parámetro index-url)
   • Credenciales de acceso al repositorio
   • Opciones de instalación de pip no predeterminadas

   Ejemplo:

   [global]
   index-url=https://example.com/
   

2. (Opcional) En algunos casos, puede que quieras obtener paquetes de varios repositorios. Por ejemplo, si el repositorio público contiene algunos paquetes específicos que quieres instalar y quieres instalar todos los demás paquetes de PyPI:

   1. Configura un repositorio virtual de Artifact Registry.
   2. Añade la configuración de varios repositorios (incluido PyPI, si es necesario) y define el orden en el que pip busca en los repositorios.
   3. Especifique la URL del repositorio virtual en el parámetro index-url.

3. Determina el URI del bucket de tu entorno.

4. Sube el archivo pip.conf a la carpeta /config/pip/ del segmento de tu entorno.

5. Instala paquetes con uno de los métodos disponibles.

Instalar paquetes desde un repositorio de Artifact Registry

Puedes almacenar paquetes en un repositorio de Artifact Registry de tu proyecto y configurar tu entorno para instalarlos desde allí.

Nota: Si usas Controles de Servicio de VPC, puedes crear un repositorio de PyPI de Artifact Registry en modo VPC. En este caso, sigue el procedimiento para repositorios privados al asignar permisos.

Configura los roles y los permisos:

1. Asegúrate de que la cuenta de servicio de Cloud Build tenga permisos para leer tu repositorio de Artifact Registry.

2. Concede permisos adicionales para instalar paquetes de repositorios de Artifact Registry a la cuenta de servicio de tu entorno, tal como se describe en Control de acceso.

3. Si tu entorno tiene restringido el acceso a otros servicios de tu proyecto (por ejemplo, si usas Controles de Servicio de VPC):

   1. Asigna permisos para acceder a tu repositorio de Artifact Registry a la cuenta de servicio del entorno en lugar de a la cuenta de servicio de Cloud Build.

   2. Asegúrate de que la conectividad al repositorio de Artifact Registry esté configurada en tu proyecto.

Para instalar paquetes de PyPI personalizados desde un repositorio de Artifact Registry, sigue estos pasos:

1. Crea un archivo pip.conf e incluye la siguiente información en el archivo, si procede:

   • URL del repositorio de Artifact Registry (en el parámetro index-url)
   • Credenciales de acceso al repositorio
   • Opciones de instalación de pip no predeterminadas

   En el caso de un repositorio de Artifact Registry, añade /simple/ a la URL del repositorio:

   [global]
   index-url = https://us-central1-python.pkg.dev/example-project/example-repository/simple/
   

2. (Opcional) En algunos casos, puede que quieras obtener paquetes de varios repositorios, por ejemplo, si tu repositorio de Artifact Registry contiene algunos paquetes específicos que quieres instalar y quieres instalar todos los demás paquetes de PyPI:

   1. Configura un repositorio virtual de Artifact Registry.
   2. Añade la configuración de varios repositorios (incluido PyPI, si es necesario) y define el orden en el que pip busca en los repositorios.
   3. Especifique la URL del repositorio virtual en el parámetro index-url.

3. Sube este archivo pip.conf a la carpeta /config/pip/ del segmento de tu entorno. Por ejemplo: gs://us-central1-example-bucket/config/pip/pip.conf.

4. Instala paquetes con uno de los métodos disponibles.

Instalar paquetes desde un repositorio privado

Puedes alojar un repositorio privado en la red de tu proyecto y configurar tu entorno para instalar paquetes de Python desde él.

Configura los roles y los permisos:

1. Si instalas paquetes PyPI personalizados desde un repositorio de la red de tu proyecto y este repositorio no tiene una dirección IP pública, haz lo siguiente:

   1. Asigna permisos para acceder a este repositorio a la cuenta de servicio del entorno.

   2. Asegúrate de que la conectividad a este repositorio esté configurada en tu proyecto.

2. Concede permisos adicionales a la cuenta de servicio de tu entorno para instalar paquetes de repositorios privados, tal como se describe en Control de acceso.

Para instalar paquetes desde un repositorio privado alojado en la red de tu proyecto, sigue estos pasos:

1. Crea un archivo pip.conf e incluye la siguiente información en el archivo, si procede:

   • Dirección IP del repositorio en la red de tu proyecto
   • Credenciales de acceso al repositorio
   • Opciones de instalación de pip no predeterminadas

   Ejemplo:

   [global]
   index-url=https://192.0.2.10/
   

2. (Opcional) En algunos casos, puede que quieras obtener paquetes de varios repositorios, por ejemplo, cuando el repositorio privado contenga algunos paquetes específicos que quieras instalar y quieras instalar todos los demás paquetes de PyPI:

   1. Configura un repositorio virtual de Artifact Registry.
   2. Añade la configuración de varios repositorios (incluido PyPI, si es necesario) y define el orden en el que pip busca en los repositorios.
   3. Especifique la URL del repositorio virtual en el parámetro index-url.

3. Sube el archivo pip.conf a la carpeta /config/pip/ del segmento de tu entorno. Por ejemplo: gs://us-central1-example-bucket/config/pip/pip.conf.

4. Instala paquetes con uno de los métodos disponibles.

Instalar una biblioteca de Python local

Para instalar una biblioteca de Python interna o local, sigue estos pasos:

1. Coloca las dependencias en un subdirectorio de la carpeta dags/ del segmento de tu entorno. Para importar un módulo de un subdirectorio, cada subdirectorio de la ruta del módulo debe contener un archivo de marcador de paquete __init__.py.

   En el siguiente ejemplo, la dependencia es coin_module.py:

   dags/
     use_local_deps.py  # A DAG file.
     dependencies/
       __init__.py
       coin_module.py
   

2. Importa la dependencia del archivo de definición del DAG.

   Por ejemplo:

from dependencies import coin_module

Nota: Se produce un error de importación si falta un archivo __init__.py. Los nombres de directorios y archivos deben ser identificadores de Python válidos.

Usar paquetes que dependan de bibliotecas de objetos compartidos

Algunos paquetes de PyPI dependen de bibliotecas a nivel de sistema. Aunque Cloud Composer no admite bibliotecas del sistema, puedes usar las siguientes opciones:

• Usa KubernetesPodOperator. Define la imagen del operador como una imagen de compilación personalizada. Usa esta opción si los paquetes fallan durante la instalación debido a una dependencia del sistema no satisfecha.

• Sube las bibliotecas de objetos compartidos al contenedor de tu entorno. Si tus paquetes de PyPI se han instalado correctamente, pero fallan en el tiempo de ejecución, usa esta opción.

  1. Busca manualmente las bibliotecas de objetos compartidos de la dependencia de PyPI (un archivo .so).
  2. Sube las bibliotecas de objetos compartidos a la carpeta /plugins del bucket de tu entorno.
  3. Define la siguiente variable de entorno: LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/airflow/gcs/plugins

Nota: Los archivos de las carpetas plugins/ se sincronizan con el sistema de archivos local. Subir archivos .so grandes puede afectar al rendimiento de tu entorno y del servidor web de Airflow.

Instalar paquetes en entornos de IP privada

En función de cómo configures tu proyecto, es posible que tu entorno no tenga acceso a Internet público.

Entorno de IP privada con acceso a Internet público

Si tu entorno de IP privada puede acceder a Internet público, puedes instalar paquetes con las opciones para entornos de IP pública:

• Instalar desde PyPI. En este caso, no es necesario realizar ninguna configuración especial. Sigue el procedimiento descrito en Instalar un paquete de PyPI.
• Instalar desde un repositorio con una dirección IP pública. Sigue el procedimiento descrito en Instalar un paquete desde un repositorio privado.
• Instala desde un repositorio de PyPI privado alojado en la red de tu proyecto.

Entorno de IP privada sin acceso a Internet

Si tu entorno de IP privada no tiene acceso a Internet público, puedes instalar paquetes de una de las siguientes formas:

• Usa un repositorio PyPI privado alojado en la red de tu proyecto.
• Usa una máquina virtual de servidor proxy en la red de tu proyecto para conectarte a un repositorio de PyPI en la red de Internet pública. Especifique la dirección del proxy en el archivo /config/pip/pip.conf del bucket de su entorno.
• Usa un repositorio de Artifact Registry como única fuente de paquetes. Para ello, vuelva a definir el parámetro index-url como se describe.
• Si tu política de seguridad permite el acceso a direcciones IP externas desde tu red VPC, puedes habilitar la instalación de paquetes desde repositorios en Internet público configurando Cloud NAT.
• Coloca las dependencias de Python en la carpeta /dags del bucket de tu entorno para instalarlas como bibliotecas locales. Puede que no sea una buena opción si el árbol de dependencias es grande.

Instalar en un entorno de IP privada con restricciones de ubicación de recursos

Si tu proyecto cumple los requisitos de la restricción de ubicaciones de recursos, no podrás usar algunas herramientas. En concreto, Cloud Build no se puede usar para instalar paquetes, lo que impide el acceso directo a repositorios en la red pública de Internet.

Para instalar las dependencias de Python en un entorno de este tipo, sigue las instrucciones para entornos de IP privada sin acceso a Internet.

Instalar una dependencia de Python en un entorno de IP privada en un perímetro de Controles de Servicio de VPC

Si proteges tu proyecto con un perímetro de Controles de Servicio de VPC, se aplicarán más restricciones de seguridad. En concreto, Cloud Build no se puede usar para instalar paquetes, lo que impide el acceso directo a repositorios en la red pública de Internet.

Para instalar las dependencias de Python en un entorno de IP privada dentro de un perímetro, sigue las instrucciones para entornos de IP privada sin acceso a Internet.

Siguientes pasos

• Solucionar problemas de instalación de paquetes
• Solucionar problemas de actualizaciones