Cloud Composer 1 | Cloud Composer 2 | Cloud Composer 3
En esta página, se describe cómo instalar paquetes de Python para tu entorno de Cloud Composer.
Información acerca de los paquetes de PyPI preinstalados y personalizados en imágenes de Cloud Composer
Las imágenes de Cloud Composer contienen 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 personalizados de PyPI son paquetes que puedes instalar en tu entorno, además de los paquetes preinstalados.
Opciones para administrar paquetes de PyPI para entornos de Cloud Composer
Opción | Usar si |
---|---|
Instalación desde PyPI | La forma predeterminada de instalar paquetes en tu entorno |
Instalar desde un repositorio con una dirección IP pública | El paquete se aloja 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 |
Realiza la instalación desde un repositorio en la red de tu proyecto | Tu entorno no tiene acceso a la Internet pública. El paquete se aloja en un repositorio de paquetes en la red de tu proyecto. |
Instala como una biblioteca local de Python |
No se puede encontrar el paquete en PyPI, y la biblioteca no tiene dependencias externas, como dist-packages . |
Cómo instalar un complemento | El paquete proporciona funcionalidad específica del complemento, como la modificación de la interfaz web de Airflow. |
PythonVirtualenvOperator | No quieres que el paquete se instale para todos los trabajadores de Airflow o que la dependencia entre en conflicto con paquetes preinstalados. El paquete se puede encontrar en el 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. Considéralo 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 habilitar la compatibilidad con un repositorio de PyPI privado.
- Los requisitos deben seguir el formato especificado en PEP-508, en el que cada requisito se especifica en minúsculas y consta del nombre del paquete con extras opcionales y especificadores de versión.
Las actualizaciones de dependencia de PyPI generan imágenes de Docker en Artifact Registry.
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.
Visualiza la lista de paquetes de PyPI
Puedes obtener la lista de paquetes para 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 (preinstalados y personalizados) en tu entorno, haz lo siguiente:
gcloud
El siguiente comando de gcloud CLI muestra el resultado del comando python -m pip list
para un trabajador de Airflow en 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
Reemplaza lo siguiente:
ENVIRONMENT_NAME
por el nombre del entorno.LOCATION
por la región en la que se encuentra el entorno
Ver paquetes de PyPI personalizados
Consola
En la consola de Google Cloud, ve a la página Entornos.
En la lista de entornos, haz clic en el nombre de tu entorno. Se abrirá la página Detalles del entorno.
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 en la que se encuentra el entorno
Instala paquetes personalizados en un entorno de Cloud Composer
En esta sección, se describen diferentes métodos para instalar paquetes personalizados en tu entorno.
Instala paquetes desde PyPI
Un paquete se puede instalar desde el índice de paquetes de Python si no tiene dependencias externas o si hay conflictos con paquetes preinstalados.
Haz lo siguiente para agregar, actualizar o borrar las dependencias de Python de tu entorno:
Consola
En la consola de Google Cloud, ve a la página Entornos.
En la lista de entornos, haz clic en el nombre de tu entorno. Se abrirá la página Detalles del entorno.
Ve a la pestaña Paquetes de PyPI.
Haz clic en Editar.
Haz clic en Agregar paquete.
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]
Haz clic en Guardar.
gcloud
Gcloud CLI tiene varios acuerdos para trabajar con paquetes de PyPI personalizados:
--update-pypi-packages-from-file
reemplaza todos los paquetes de PyPI personalizados existentes por los paquetes especificados. Se quitan los paquetes que no especificas.--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 en la que se encuentra el entorno
Instala un paquete
Actualiza tu entorno y especifica el paquete, la versión y los elementos adicionales 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 en la que se encuentra el entornoPACKAGE_NAME
por el nombre del paqueteEXTRAS_AND_VERSION
con 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"
Cómo quitar paquetes
Actualiza tu entorno y especifica los paquetes que quieres 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 en la que se encuentra el entornoPACKAGE_NAMES
por una lista de paquetes separada 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:
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.
- Usa la máscara
En el cuerpo de la solicitud, especifica los 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 paqueteEXTRAS_AND_VERSION
con 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 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
en el bloque software_config
especifica paquetes.
resource "google_composer_environment" "example" {
name = "ENVIRONMENT_NAME"
region = "LOCATION"
config {
software_config {
pypi_packages = {
PACKAGE_NAME = "EXTRAS_AND_VERSION"
}
}
}
}
Reemplaza lo siguiente:
ENVIRONMENT_NAME
por el nombre del entorno.LOCATION
por la región en la que se encuentra el entornoPACKAGE_NAME
por el nombre del paqueteEXTRAS_AND_VERSION
con 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 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]"
}
}
}
}
Instala 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 de forma correcta para que la herramienta predeterminada de pip
pueda instalarlo.
Para instalar desde un repositorio de paquetes que tiene una dirección pública, sigue estos pasos:
Crea un archivo pip.conf y, luego, incluye la siguiente información en el archivo, si corresponde:
- URL del repositorio (en el parámetro
index-url
) - Credenciales de acceso del repositorio
- Opciones de instalación no predeterminadas de
pip
Ejemplo:
[global] index-url=https://example.com/
- URL del repositorio (en el parámetro
En algunos casos, es posible que desees recuperar paquetes de varios repositorios, como cuando el repositorio público contiene algunos paquetes específicos que deseas instalar, y quieres instalar todos los demás paquetes de PyPI:
- Configura un repositorio virtual de Artifact Registry.
- Agrega una configuración para varios repositorios (incluido PyPI, si es necesario)
y define el orden en el que
pip
los busca. - Especifica la URL del repositorio virtual en el parámetro
index-url
.
Sube el archivo pip.conf a la carpeta
/config/pip/
en el bucket de tu entorno.Instala los paquetes con uno de los métodos disponibles.
Instala paquetes desde un repositorio de Artifact Registry
Puedes almacenar paquetes en un repositorio de Artifact Registry en tu proyecto y configurar tu entorno para instalarlo desde él.
Configura roles y permisos:
La cuenta de servicio de tu entorno debe tener la función
iam.serviceAccountUser
.Asegúrate de que la cuenta de servicio de Cloud Build tenga permisos de lectura desde tu repositorio de Artifact Registry.
Si tu entorno tiene acceso restringido a otros servicios en tu proyecto, por ejemplo, si usas los Controles del servicio de VPC, haz lo siguiente:
Asigna permisos para acceder a tu repositorio de Artifact Registry a la cuenta de servicio del entorno en lugar de la cuenta de servicio de Cloud Build.
Asegúrate de que la conectividad al repositorio de Artifact Registry esté configurada en tu proyecto.
Para instalar paquetes personalizados de PyPI desde un repositorio de Artifact Registry, sigue estos pasos:
Crea un archivo pip.conf y, luego, incluye la siguiente información en el archivo, si corresponde:
- URL del repositorio de Artifact Registry (en el parámetro
index-url
) - Credenciales de acceso del repositorio
- Opciones de instalación no predeterminadas de
pip
Para un repositorio de Artifact Registry, agrega
/simple/
a la URL del repositorio:[global] index-url = https://us-central1-python.pkg.dev/example-project/example-repository/simple/
- URL del repositorio de Artifact Registry (en el parámetro
En algunos casos, es posible que quieras recuperar paquetes de varios repositorios, como cuando tu repositorio de Artifact Registry contiene algunos paquetes específicos que deseas instalar, y quieres instalar todos los demás paquetes de PyPI:
- Configura un repositorio virtual de Artifact Registry.
- Agrega una configuración para varios repositorios (incluido PyPI, si es necesario)
y define el orden en el que
pip
los busca. - Especifica la URL del repositorio virtual en el parámetro
index-url
.
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 los paquetes con uno de los métodos disponibles.
Instala 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 roles y permisos:
La cuenta de servicio para tu entorno de Cloud Composer debe tener la función
iam.serviceAccountUser
.Si instalas paquetes de PyPI personalizados desde un repositorio en la red de tu proyecto y este repositorio no tiene una dirección IP pública, ocurre lo siguiente:
Asigna permisos para acceder a este repositorio a la cuenta de servicio del entorno.
Asegúrate de que la conectividad a este repositorio esté configurada en tu proyecto.
Sigue estos pasos para instalar paquetes desde un repositorio privado alojado en la red de tu proyecto:
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 no predeterminadas de
pip
Ejemplo:
[global] index-url=https://192.0.2.10/
En algunos casos, es posible que desees recuperar paquetes de varios repositorios, como cuando el repositorio privado contiene algunos paquetes específicos que deseas instalar, y quieres instalar todos los demás paquetes de PyPI:
- Configura un repositorio virtual de Artifact Registry.
- Agrega una configuración para varios repositorios (incluido PyPI, si es necesario)
y define el orden en el que
pip
los busca. - Especifica la URL del repositorio virtual en el parámetro
index-url
.
Sube el 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 los paquetes con uno de los métodos disponibles.
Instala una biblioteca local de Python
Para instalar una biblioteca interna o local de Python, sigue estos pasos:
Coloca las dependencias dentro de 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
Importa la dependencia desde el archivo de definición de DAG.
Por ejemplo:
Usa paquetes que dependan 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 como una imagen de compilación personalizada. Si experimentas paquetes que fallan durante la instalación debido a una dependencia del sistema no satisfecha, usa esta opción.
Sube las bibliotecas de objetos compartidos al bucket de tu entorno. Si tus paquetes de PyPI se instalaron correctamente, pero fallan en el tiempo de ejecución, usa esta opción.
- Busca de forma manual las bibliotecas de objetos compartidos para la dependencia de PyPI (un archivo .so).
- Sube las bibliotecas de objetos compartidos a la carpeta
/plugins
en el bucket de tu entorno. - Configura la siguiente variable de entorno:
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/airflow/gcs/plugins
Instala paquetes en entornos de IP privados
En esta sección, se explica cómo instalar paquetes en entornos de IP privadas.
Según cómo configures tu proyecto, es posible que tu entorno no tenga acceso a la Internet pública.
Entorno de IP privada con acceso público a Internet
Si tu entorno de IP privada puede acceder a la Internet pública, puedes instalar paquetes mediante opciones para entornos de IP públicas:
- Instalar desde PyPI. En este caso, no se requiere ninguna configuración especial. Sigue el procedimiento que se describe en Instala un paquete desde PyPI.
- Instalar desde un repositorio con una dirección IP pública. Sigue el procedimiento que se describe en Instala 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 la Internet pública, puedes instalar paquetes de una de las siguientes maneras:
- Usa un repositorio de PyPI privado alojado en la red de tu proyecto.
- Usa una VM de servidor proxy en la red de tu proyecto para conectarte a un repositorio de PyPI en la Internet pública. Especifica la dirección del proxy en el archivo
/config/pip/pip.conf
del bucket de tu entorno. - Usa un repositorio de Artifact Registry como la única fuente
de paquetes. Para hacerlo, vuelve 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 de VPC, puedes habilitar la instalación de paquetes desde repositorios en la Internet pública mediante la configuración de Cloud NAT.
- Coloca las dependencias de Python en la carpeta
/dags
del bucket de tu entorno para instalarlas como bibliotecas locales. Es posible que esta no sea una buena opción si el árbol de dependencias es grande.
Instala en un entorno de IP privada con restricciones de ubicación de recursos
Mantener el proyecto en línea con los requisitos de la restricción de ubicación de recursos prohíbe el uso de algunas herramientas. En particular, Cloud Build no se puede usar para instalar paquetes, lo que evita el acceso directo a repositorios en la Internet pública.
Para instalar dependencias de Python en un entorno de este tipo, sigue las instrucciones para entornos de IP privadas sin acceso a Internet.
Instala una dependencia de Python en un entorno de IP privada 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 instalar paquetes, lo que evita el acceso directo a repositorios en la Internet pública.
Si deseas instalar dependencias de Python para un entorno de IP privada dentro de un perímetro, sigue las instrucciones para entornos de IP privadas sin acceso a Internet.
¿Qué sigue?
- Soluciona problemas relacionados con la instalación de paquetes
- Solución de problemas de actualizaciones y mejoras