Instalar dependencias de Python

Cloud Composer 1 | Cloud Composer 2

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

Información sobre los paquetes de PyPI preinstalados y personalizados

Los paquetes de 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 que son específicos para 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 planeas actualizar a una versión posterior de Cloud Composer, puedes realizar una verificación de actualización. Esta verificación informa si los paquetes de PyPI personalizados del entorno tienen algún conflicto con los paquetes preinstalados en la imagen nueva de Cloud Composer.

Opciones para administrar paquetes de Python

Opción	Usar si
Instala desde PyPI	El paquete no tiene dependencias externas y no está en conflicto con las dependencias de Cloud Composer.
Realiza la instalación desde un repositorio privado	El paquete se aloja en un repositorio de paquetes privado disponible en Internet.
Realiza la instalación como una biblioteca local de Python	No se puede encontrar el paquete en el índice del paquete de Python y la biblioteca no tiene dependencias externas, como dist-packages.
Instala un complemento	El paquete proporciona una funcionalidad específica del complemento, como modificar la interfaz web de Airflow.
PythonVirtualenvOperator	No deseas que el paquete se instale para todos los trabajadores o la dependencia entra en conflicto con los paquetes preinstalados. El paquete se puede encontrar en el índice de paquetes de Python y no tiene dependencias externas.
KubernetesPodOperator	Necesitas dependencias externas que no se pueden 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 y, por lo general, debe considerarse solo si otras opciones no funcionan.

Antes de comenzar

• Debes tener una función que pueda activar las operaciones de actualización del entorno. Además, la cuenta de servicio del entorno debe tener una función que tenga suficientes permisos para realizar operaciones de actualización. Para obtener más información, consulta Control de acceso.
• Si tu entorno está protegido por un perímetro de Controles del servicio de VPC, antes de instalar dependencias de PyPI, debes otorgar identidades de usuario adicionales con acceso a los servicios que el perímetro de servicio protege y habilita 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 opcionales y especificadores de versión.
• Las actualizaciones de dependencias de PyPI generan imágenes de Docker en Artifact Registry. No modifiques ni borres las imágenes.
• Si un conflicto de dependencia hace que la actualización falle, tu entorno continuará ejecutándose con las dependencias existentes. Si la operación tiene éxito, puedes comenzar a usar las dependencias de Python recién instaladas en tus DAG.

Cómo ver la lista de paquetes

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

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.

Todos los paquetes

Para ver todos los paquetes (preinstalados y personalizados) en tu entorno, sigue estos pasos:

gcloud

El siguiente comando de la CLI de gcloud muestra el resultado del comando python -m pip list para un trabajador de Airflow en tu entorno.

Como alternativa, 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

Reemplaza lo siguiente:

• ENVIRONMENT_NAME por el nombre del entorno.
• LOCATION por la región donde se encuentra el entorno

Paquetes de PyPI personalizados

Console

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

   Ir a Entornos

2. En la lista de entornos, haga clic en el nombre de su 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)"

Reemplaza lo siguiente:

• ENVIRONMENT_NAME por el nombre del entorno.
• LOCATION por la región donde se encuentra el entorno

Instala un paquete desde PyPI

Se puede instalar un paquete desde el índice del paquete de Python si no tiene dependencias externas ni conflictos con los paquetes preinstalados.

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

Haz lo siguiente para agregar, actualizar o borrar las dependencias de Python de tu entorno:

Console

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

   Ir a Entornos

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

3. Ve a la pestaña Configuración del entorno.

4. Haga clic en Editar.

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

   Por ejemplo:

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

gcloud

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

• --update-pypi-packages-from-file reemplaza a todos los paquetes personalizados de PyPI personalizados con los paquetes especificados. Se quitarán los paquetes que no especifiques.
• --update-pypi-package actualiza o instala un paquete.
• --remove-pypi-packages quita los paquetes especificados.
• --clear-pypi-packages quita todos los paquetes.

Cómo instalar los requisitos desde un archivo

El archivo requirements.txt debe tener cada especificador de requisitos en una línea separada.

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

Reemplaza lo siguiente:

• ENVIRONMENT_NAME por el nombre del entorno.
• LOCATION por la región donde se encuentra el entorno

Instala 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

Reemplaza lo siguiente:

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

Ejemplo:

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

Quita paquetes

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

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

Reemplaza lo siguiente:

• ENVIRONMENT_NAME por el nombre del entorno.
• LOCATION por la región donde 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

Realiza una solicitud a la API de environments.patch.

En esta solicitud, realiza lo siguiente:

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

   • Usa la máscara config.softwareConfig.pypiPackages para reemplazar todos los paquetes existentes por los paquetes especificados. Se borrarán los paquetes que no especifiques.
   • Usa config.softwareConfig.envVariables.PACKAGE_NAME para agregar o actualizar un paquete específico. Para agregar o actualizar varios paquetes, especifica varias máscaras con comas.

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

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

   Reemplaza lo siguiente:

   • PACKAGE_NAME por el nombre del paquete
   • EXTRAS_AND_VERSION por la versión opcional y el especificador de extras. Para omitir versiones y extras, especifica un valor vacío.
   • Si deseas agregar más de un paquete, agrega 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 env_variables del bloque software_config especifica variables de entorno.

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

  config {

    software_config {

      env_variables = {
        VAR_NAME = "VAR_VALUE"
      }

    }
  }
}

Reemplaza lo siguiente:

• ENVIRONMENT_NAME por el nombre del entorno.
• LOCATION por la región donde se encuentra el entorno
• VAR_NAME por el nombre de la variable de entorno.
• VAR_VALUE por el valor de la variable de entorno.
• Si deseas agregar más de una variable, agrega entradas adicionales para variables a env_variables.

Ejemplo:

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

  config {

      env_variables = {
        EXAMPLE_VARIABLE = "True"
        ANOTHER_VARIABLE = "test"
      }

  }
}

Instala desde un repositorio privado

Puedes instalar paquetes alojados en repositorios de paquetes disponibles en la Internet pública.

Los paquetes deben estar configurados correctamente, de modo que la herramienta predeterminada pip pueda instalarlo.

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

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

1. Crea un archivo pip.conf y, luego, incluye la siguiente información en el archivo, si corresponde:

   • URL del repositorio
   • Credenciales de acceso del repositorio
   • Opciones de instalación de pip no predeterminadas

   Ejemplo:

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

2. Sube este archivo pip.conf a la carpeta /config/pip/ en el bucket de tu entorno. Por ejemplo: gs://us-central1-example-bucket/config/pip/pip.conf

Instalar en un entorno de IP privada

Un entorno de IP privada restringe el acceso a la Internet pública, por lo que la instalación de dependencias de Python puede requerir pasos adicionales.

Cuando se instalan dependencias desde un repositorio de PyPI, no se requiere ninguna configuración especial. Sigue el procedimiento que se describe en Instala un paquete desde PyPI. También puedes solicitar paquetes desde un repositorio privado con una dirección pública.

Como alternativa, puedes alojar un repositorio privado de PyPI en tu red de proyecto. Cuando instalas dependencias, Cloud Composer ejecuta la operación dentro del clúster que aloja tu entorno sin acceder a ninguna dirección IP pública a través de Cloud Build.

Para instalar paquetes desde un repositorio privado alojado en la red de tu proyecto:

1. La cuenta de servicio de tu entorno de Cloud Composer debe tener la función iam.serviceAccountUser.

2. Crea un archivo pip.conf y, luego, incluye la siguiente información en el archivo, si corresponde:

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

   Ejemplo:

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

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

Instala en un entorno de IP privado con restricciones de ubicación de recursos

Mantener tu proyecto conforme a los requisitos de restricción de ubicación de recursos prohíbe el uso de algunas herramientas. En particular, Cloud Build no se puede usar para la instalación de paquetes, lo que evita el acceso directo a los repositorios en la Internet pública.

Para instalar dependencias de Python en un entorno de este tipo, sigue las instrucciones de un entorno de IP privada con un perímetro de controles del servicio de VPC.

Instala una dependencia de Python en un entorno de IP privado en un perímetro de Controles del servicio de VPC

Proteger tu proyecto con un perímetro de los Controles del servicio de VPC genera más restricciones de seguridad. En particular, Cloud Build no se puede usar para la instalación de paquetes, lo que evita el acceso directo a los repositorios en la Internet pública.

A fin de instalar dependencias de Python para un entorno de IP privada dentro de un perímetro, puedes hacer lo siguiente:

• Usa un repositorio de PyPI privado alojado en tu red de VPC.
• Usa una VM de servidor proxy en tu red de VPC para conectarte a un repositorio de PyPI en la Internet pública. Especifica la dirección de proxy en el archivo /config/pip/pip.conf en el bucket de tu entorno.
• Si tu política de seguridad permite el acceso a la red de VPC desde direcciones IP externas, puedes habilitar esta opción mediante la configuración de Cloud NAT.
• Coloca las dependencias de Python en la carpeta dags, en el bucket de Cloud Storage para instalarlas como bibliotecas locales. Es posible que esta no sea una buena opción si el árbol de dependencias es grande.

Instalar una biblioteca local de Python

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

1. Coloca las dependencias en un subdirectorio en la carpeta dags/ del bucket de tu entorno. Para importar un módulo desde 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 desde el archivo de definición de DAG.

   Por ejemplo:

composer/workflows/use_local_deps.py

Ver en GitHub Comentarios

from dependencies import coin_module

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

Usa paquetes que dependen de bibliotecas de objetos compartidos

Algunos paquetes de PyPI dependen de las bibliotecas a nivel del sistema. Si bien Cloud Composer no es compatible con las bibliotecas del sistema, puedes usar las siguientes opciones:

• Utiliza KubernetesPodOperator. Configura la imagen del operador en una imagen de compilación personalizada. Si experimentas paquetes que fallan durante la instalación debido a una dependencia no alcanzada del sistema, usa esta opción.

• Sube las bibliotecas de objetos compartidos al bucket de tu entorno. Si tus paquetes de PyPI se instalaron con éxito, pero fallan en el entorno de ejecución, usa esta opción.

  1. Busca de forma manual las bibliotecas de objetos compartidos para la dependencia de PyPI (un archivo .so).
  2. Sube las bibliotecas de objetos compartidos a la carpeta /plugins del bucket de tu entorno.
  3. Configura 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 el rendimiento de tu entorno y del servidor web de Airflow.

¿Qué sigue?

• Cómo solucionar problemas de instalación de paquetes
• Cómo solucionar problemas de actualizaciones