Administración de las dependencias de Python en requirements.txt - Amazon Managed Workflows para Apache Airflow
Pruebas de los DAG mediante la utilidad de la CLI de Amazon MWAAInstalación de dependencias de Python mediante el formato de archivo de requisitos PyPI.orgHabilitación de registros en la consola de Amazon MWAAVisualización de consultas de registros en la consola de registros de CloudWatchVisualización de los errores en la interfaz de usuario de Apache AirflowEjemplos de escenarios de requirements.txt

Administración de las dependencias de Python en requirements.txt

En esta página se describen las prácticas recomendadas para instalar y administrar las dependencias de Python en un archivo requirements.txt para entornos de Amazon Managed Workflows para Apache Airflow.

Pruebas de los DAG mediante la utilidad de la CLI de Amazon MWAA

  • La utilidad de la interfaz de la línea de comandos (CLI) replica entornos en Amazon Managed Workflows para Apache Airflow de forma local.

  • La CLI crea localmente una imagen de contenedor de Docker similar a una imagen de producción de Amazon MWAA. Esto le permite ejecutar un entorno local de Apache Airflow para desarrollar y probar los DAG, los complementos personalizados y las dependencias antes de implementarlos en Amazon MWAA.

  • Para ejecutar la CLI, consulte aws-mwaa-local-runner en GitHub.

Instalación de dependencias de Python mediante el formato de archivo de requisitos PyPI.org

En la siguiente sección se describen las distintas maneras de instalar las dependencias de Python según el archivo de requisitos Requirements file format de PyPi.org.

Opción uno: dependencias de Python desde el Índice de paquetes de Python

La siguiente sección describe cómo especificar las dependencias de Python desde el Python Package Index en un archivo requirements.txt.

Apache Airflow v2

  1. Hacer una prueba local. Añada bibliotecas adicionales de forma iterativa para encontrar la combinación adecuada de paquetes y sus versiones antes de crear un archivo requirements.txt. Para ejecutar la utilidad de la CLI de Amazon MWAA, consulte aws-mwaa-local-runner en GitHub.

  2. Revise los extras del paquete Apache Airflow. Para ver una lista de los paquetes instalados para Apache Airflow v2 en Amazon MWAA, consulte Amazon MWAA local runner en requirements.txt el sitio web de GitHub.

  3. Añada instrucciones respecto a las restricciones. Añada el archivo de restricciones para su entorno Apache Airflow v2 en la parte superior del archivo requirements.txt. Los archivos de restricciones de Apache Airflow especifican las versiones de proveedores disponibles en el momento de la publicación de Apache Airflow.

    A partir de la versión 2.7.2 de Apache Airflow, su archivo de requisitos debe incluir una instrucción --constraint. Si no proporciona ninguna restricción, Amazon MWAA especificará una para garantizar que los paquetes que figuran en sus requisitos sean compatibles con la versión de Apache Airflow que utilice.

    En el siguiente ejemplo, sustituya {environment-version} con el número de versión de su entorno y {Python-version} con la versión de Python compatible con su entorno.

    Para obtener información sobre la versión de Python compatible con su entorno de Apache Airflow, consulte Versiones de Apache Airflow. 

    --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-{Airflow-version}/constraints-{Python-version}.txt"

    Si el archivo de restricciones determina que el paquete xyz==1.0 no es compatible con otros paquetes en su entorno, pip3 install fallará para evitar que bibliotecas incompatibles se instalen en su entorno. En caso de error en la instalación de algún paquete, podrá ver los registros de errores de cada componente de Apache Airflow (el programador, el proceso de trabajo y el servidor web) en el flujo de registro correspondiente en los Registros de CloudWatch. Para más información sobre los tipos de registros, consulte Visualización registros en Amazon CloudWatch.

  4. Paquetes de Apache Airflow. Añada los extras del paquete y la versión (==). Esto ayuda a evitar que se instalen en su entorno paquetes del mismo nombre, pero de una versión diferente.

    apache-airflow[package-extra]==2.5.1

  5. Bibliotecas Python. Añada el nombre del paquete y la versión (==) al archivo requirements.txt. Esto permite evitar que se lleve a cabo una actualización futura de última hora de PyPi.org automáticamente.

    library == version
    ejemplo Boto3 y psycopg2-binary

    Este caso se proporciona como ejemplo. Las bibliotecas boto y psycopg2-binary vienen incluidas en la instalación base de Apache Airflow v2, por lo que no es necesario especificarlas en un archivo requirements.txt.

    boto3==1.17.54
boto==2.49.0
botocore==1.20.54
psycopg2-binary==2.8.6

    Si un paquete se especifica sin versión, Amazon MWAA instalará la última versión del paquete que encuentre en PyPi.org. Esta versión puede entrar en conflicto con otros paquetes de su requirements.txt.

Apache Airflow v1

  1. Hacer una prueba local. Añada bibliotecas adicionales de forma iterativa para encontrar la combinación adecuada de paquetes y sus versiones antes de crear un archivo requirements.txt. Para ejecutar la utilidad de la CLI de Amazon MWAA, consulte aws-mwaa-local-runner en GitHub.

  2. Revise los extras del paquete Airflow. Consulte la lista de paquetes disponibles para la versión 1.10.12 de Apache Airflow en https://raw.githubusercontent.com/apache/airflow/constraints-1.10.12/constraints-3.7.txt.

  3. Añada el archivo de restricciones. Añada el archivo de restricciones de Apache Airflow v1.10.12 al principio del archivo requirements.txt. Si el archivo de restricciones determina que el paquete xyz==1.0 no es compatible con otros paquetes de su entorno, pip3 install no podrá impedir que se instalen bibliotecas incompatibles en su entorno.

    --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-1.10.12/constraints-3.7.txt"

  4. Paquetes de Apache Airflow v1.10.12. Añada los extras del paquete Airflow y la versión Apache Airflow v1.10.12 (==). Esto ayuda a evitar que se instalen en su entorno paquetes del mismo nombre, pero de una versión diferente.

    apache-airflow[package]==1.10.12
    ejemplo Secure Shell (SSH)

    El siguiente archivo requirements.txt de ejemplo instala SSH para Apache Airflow v1.10.12. 

    apache-airflow[ssh]==1.10.12

  5. Bibliotecas Python. Añada el nombre del paquete y la versión (==) al archivo requirements.txt. Esto permite evitar que se lleve a cabo una actualización futura de última hora de PyPi.org automáticamente.

    library == version
    ejemplo Boto3

    El siguiente archivo requirements.txt de ejemplo instala la biblioteca Boto3 para Apache Airflow v1.10.12.

    boto3 == 1.17.4

    Si un paquete se especifica sin versión, Amazon MWAA instalará la última versión del paquete que encuentre en PyPi.org. Esta versión puede entrar en conflicto con otros paquetes de su requirements.txt.

Opción dos: archivos wheels de Python (.whl)

El formato wheel de Python es un tipo de paquete diseñado para enviar bibliotecas con artefactos compilados. Los paquetes wheel presentan varias ventajas si se utilizan como método para instalar dependencias en Amazon MWAA:

  • Instalación más rápida: los archivos WHL se copian en el contenedor como un único ZIP y se instalan de forma local, sin necesidad de descargarlos uno por uno.

  • Menos conflictos: se puede determinar con antelación la compatibilidad de las versiones de los paquetes. De esta manera, no es necesario que pip elabore de forma recurrente versiones compatibles.

  • Mayor resiliencia: si las bibliotecas se alojan externamente, es posible que los requisitos posteriores cambien con el tiempo, lo que provocará que las versiones sean incompatibles entre los contenedores de un entorno de Amazon MWAA. Al no depender de una fuente externa para las dependencias, todos los contenedores tienen las mismas bibliotecas, independientemente de cuándo se instancie cada contenedor.

Recomendamos seguir los métodos que se indican a continuación para instalar las dependencias de Python en su requirements.txt desde un archivo wheel de Python (.whl).

Uso del archivo plugins.zip en un bucket de Amazon S3

El programador, los procesos de trabajo y el servidor web de Apache Airflow (en el caso de Apache Airflow v2.2.2 y las versiones posteriores) buscan complementos personalizados durante el inicio en el contenedor de Fargate administrado por AWS para su entorno en /usr/local/airflow/plugins/*. Este proceso comienza antes del pip3 install -r requirements.txt de Amazon MWAA para las dependencias de Python y del inicio del servicio Apache Airflow. Se puede utilizar un archivo plugins.zip con todos aquellos archivos que no quiera que vayan cambiando continuamente durante la ejecución del entorno, o con aquellos a los que no quiera permitir que accedan los usuarios que escriben DAG. Por ejemplo, archivos wheel de la biblioteca Python, archivos PEM de certificados y archivos YAML de configuración.

En la siguiente sección se describe cómo instalar wheels del archivo plugins.zip de su bucket de Amazon S3.

  1. Descargue los archivos WHL necesarios. Puede utilizar pip download con su requirements.txt actual en el local-runner de Amazon MWAA o en otro contenedor de Amazon Linux 2 para resolver y descargar los archivos wheel de Python necesarios. 

    $ pip3 download -r "$AIRFLOW_HOME/dags/requirements.txt" -d "$AIRFLOW_HOME/plugins"
$ cd "$AIRFLOW_HOME/plugins"
$ zip "$AIRFLOW_HOME/plugins.zip" *

  2. Especifique la ruta en su requirements.txt. Especifique el directorio de complementos al principio de su archivo requirements.txt con --find-links e indique a pip que instale desde otras fuentes con --no-index, tal y como se muestra a continuación. 

    --find-links /usr/local/airflow/plugins
--no-index
    ejemplo Ejemplo de wheel en el archivo requirements.txt

    En el siguiente ejemplo, se supone que ha cargado el wheel en un archivo plugins.zip en la raíz de su bucket de Amazon S3. Por ejemplo:

    --find-links /usr/local/airflow/plugins
--no-index

numpy

    Amazon MWAA extrae el wheel numpy-1.20.1-cp37-cp37m-manylinux1_x86_64.whl de la carpeta de plugins y lo instala en su entorno.

Uso de archivos WHL alojados en una URL

En la siguiente sección se describe cómo instalar un archivo wheel alojado en una URL. La URL debe ser de acceso público o se debe poder acceder a ella desde la VPC de Amazon personalizada que especificó para su entorno de Amazon MWAA.

  • Indique una URL. Indique la URL en la que se encuentra el archivo wheel en su requirements.txt.

    ejemplo archivo wheel en una URL pública

    En el siguiente ejemplo, se puede ver cómo se descarga un archivo wheel de un sitio web público.

    --find-links https://files.pythonhosted.org/packages/
--no-index

    Amazon MWAA obtiene el archivo wheel de la URL que había especificado y lo instala en su entorno.

    nota

    No se puede acceder a las URL desde servidores web privados que requieran instalar requisitos en Amazon MWAA v2.2.2 y versiones posteriores.

Creación de archivos WHL a partir de DAG

Si dispone de un servidor web privado con Apache Airflow v2.2.2 o versiones posteriores y no puede instalar los requisitos porque su entorno no tiene acceso a repositorios externos, puede usar el siguiente DAG para tomar sus requisitos actuales de Amazon MWAA y empaquetarlos en Amazon S3: 

from airflow import DAG
from airflow.operators.bash_operator import BashOperator
from airflow.utils.dates import days_ago

S3_BUCKET = 'my-s3-bucket'
S3_KEY = 'backup/plugins_whl.zip' 

with DAG(dag_id="create_whl_file", schedule_interval=None, catchup=False, start_date=days_ago(1)) as dag:
    cli_command = BashOperator(
        task_id="bash_command",
        bash_command=f"mkdir /tmp/whls;pip3 download -r /usr/local/airflow/requirements/requirements.txt -d /tmp/whls;zip -j /tmp/plugins.zip /tmp/whls/*;aws s3 cp /tmp/plugins.zip s3://{S3_BUCKET}/{S3_KEY}"
    )

Después de ejecutar el DAG, utilice este nuevo archivo como su plugins.zip de Amazon MWAA. Si lo desea, puede empaquetarlo con otros complementos. A continuación, actualice su requirements.txt que comienza por --find-links /usr/local/airflow/plugins y --no-index sin agregar --constraint.

Esto le permitirá utilizar las mismas bibliotecas sin conexión.

Opción tres: dependencias de Python alojadas en un repositorio privado conforme con PyPI/PEP-503

En la siguiente sección se describe cómo instalar un elemento adicional de Apache Airflow alojado en una URL privada con autenticación.

  1. Añada su nombre de usuario y contraseña como Opciones de configuración de Airflow. Por ejemplo:

    • foo.user : YOUR_USER_NAME

    • foo.pass : YOUR_PASSWORD

  2. Cree su archivo requirements.txt. Sustituya los marcadores de posición del ejemplo que sigue por su URL privada e introduzca el nombre de usuario y la contraseña que haya añadido como Opciones de configuración de Airflow. Por ejemplo:

    --index-url https://${AIRFLOW__FOO__USER}:${AIRFLOW__FOO__PASS}@my.privatepypi.com

  3. En caso aplicable, añada las bibliotecas adicionales a su archivo requirements.txt. Por ejemplo:

    --index-url https://${AIRFLOW__FOO__USER}:${AIRFLOW__FOO__PASS}@my.privatepypi.com
my-private-package==1.2.3

Habilitación de registros en la consola de Amazon MWAA

El rol de ejecución de su entorno de Amazon MWAA necesita permiso para enviar los registros a los Registros de Amazon CloudWatch. Para actualizar los permisos de un rol de ejecución, consulte Rol de ejecución de Amazon MWAA.

Puede habilitar los registros de Apache Airflow en los niveles INFO, WARNING, ERROR o CRITICAL. A elegir un nivel de registro, Amazon MWAA envía los registros correspondientes a ese nivel y a todos los niveles de gravedad superiores. Por ejemplo, si habilita los registros en el nivel INFO, Amazon MWAA envía los registros del nivel INFO, así como los registros de los niveles WARNING, ERROR y CRITICAL a los Registros de CloudWatch. Recomendamos habilitar los registros de Apache Airflow en el nivel INFO para que el programador pueda ver los registros recibidos para el archivo requirements.txt.

Esta imagen muestra cómo habilitar los registros en el nivel INFO.

Visualización de consultas de registros en la consola de registros de CloudWatch

Consulte los registros de Apache Airflow correspondientes al programador encargado de programar sus flujos de trabajo y de analizar su carpeta de dags. En los pasos que siguen se describe cómo abrir el grupo de registro del programador en la consola de Amazon MWAA y cómo ver los registros de Apache Airflow en la consola de Registros de CloudWatch.

Pasos para ver los registros de un requirements.txt

  1. Abra la página Entornos en la consola de Amazon MWAA.

  2. Seleccione un entorno.

  3. Elija el Grupo de registro del programador de Airflow en el panel de Monitorización.

  4. Seleccione el registro requirements_install_ip en los flujos de registro.

  5. Debería ver la lista de paquetes que se hayan instalado en el entorno en /usr/local/airflow/.local/bin. Por ejemplo:

    Collecting appdirs==1.4.4 (from -r /usr/local/airflow/.local/bin (line 1))
Downloading https://files.pythonhosted.org/packages/3b/00/2344469e2084fb28kjdsfiuyweb47389789vxbmnbjhsdgf5463acd6cf5e3db69324/appdirs-1.4.4-py2.py3-none-any.whl  
Collecting astroid==2.4.2 (from -r /usr/local/airflow/.local/bin (line 2))

  6. Consulte la lista de paquetes y compruebe si se produjo algún error en alguno de ellos durante la instalación. Si algo ha ido mal, es posible que aparezca un error similar al siguiente:

    2021-03-05T14:34:42.731-07:00
No matching distribution found for LibraryName==1.0.0 (from -r /usr/local/airflow/.local/bin (line 4))
No matching distribution found for LibraryName==1.0.0 (from -r /usr/local/airflow/.local/bin (line 4))

Visualización de los errores en la interfaz de usuario de Apache Airflow

Es posible que también quiera comprobar su interfaz de usuario de Apache Airflow para averiguar si algún error puede estar relacionado con otro problema. El error más común que puede producirse con Apache Airflow en Amazon MWAA es:

Broken DAG: No module named x

Si ve este error en la interfaz de usuario de Apache Airflow, es probable que falte una dependencia obligatoria en su archivo requirements.txt.

Inicio de sesión en Apache Airflow

Necesita permisos de Política de acceso a la interfaz de usuario de Apache Airflow: AmazonMWAAWebServerAccess para su cuenta de AWS en AWS Identity and Access Management (IAM) para ver la interfaz de usuario de Apache Airflow.

Pasos para acceder a la interfaz de usuario de Apache Airflow

  1. Abra la página Entornos en la consola de Amazon MWAA.

  2. Seleccione un entorno.

  3. Elija Abrir interfaz de usuario de Airflow.

Ejemplos de escenarios de requirements.txt

Puede mezclar y combinar diferentes formatos en su requirements.txt. En el siguiente ejemplo se utiliza una combinación de las distintas formas de instalar elementos adicionales.

ejemplo Ejemplo de elementos adicionales en PyPI.org y en una URL pública

Utilice la opción --index-url al especificar paquetes de PyPI.org y cuando se especifiquen paquetes en una URL pública, como en el caso de las URL de repositorios personalizados que cumplen con el PEP 503.

aws-batch == 0.6
phoenix-letter >= 0.3
    
--index-url http://dist.repoze.org/zope2/2.10/simple
    zopelib