Actualizar entornos

En esta página, se describe cómo actualizar tu entorno a una versión nueva de Airflow.

Acerca de las operaciones de actualización

En Managed Airflow (3ª gen.), no administras la versión de Managed Airflow de tu entorno:

• Managed Airflow actualiza automáticamente los componentes de infraestructura de tu entorno. Estos componentes se relacionan con la funcionalidad de Managed Airflow y no cambian la forma en que funciona Airflow ni cómo se ejecutan tus DAG de Airflow.
• Managed Airflow no actualiza automáticamente la versión y la compilación de Airflow, los componentes de Airflow ni los componentes estrechamente relacionados con las cargas de trabajo de Airflow. No se modifican cuando los componentes de la infraestructura se actualizan automáticamente.
• Puedes actualizar de forma manual a una nueva versión o compilación de Airflow.

Por ejemplo, puedes usar la misma versión y compilación de Airflow durante varios meses sin realizar ninguna actualización, y tu entorno seguirá recibiendo las actualizaciones, correcciones y mejoras más recientes de Managed Airflow de los componentes de la infraestructura del entorno. Cuando más adelante decidas cambiar a una nueva versión o compilación de Airflow, actualiza la versión de Airflow en tu entorno.

Acerca de la actualización de la versión de Airflow

Tu entorno cambia la versión o la compilación de Airflow de la siguiente manera:

• Tú controlas la versión (y la compilación) de Airflow de tu entorno. Puedes realizar la operación de actualización de la versión de Airflow cuando decidas cambiar tu entorno a una versión diferente de Airflow. Por ejemplo, esto puede suceder si la versión y la compilación actuales de Airflow ya no son compatibles.

• Managed Airflow vuelve a implementar los componentes de Airflow de tu entorno con la versión y la compilación de Airflow especificadas.

• Managed Airflow aplica los cambios de configuración de Airflow, como los paquetes de PyPI personalizados o las anulaciones de las opciones de configuración de Airflow, si tu entorno los tenía antes de la actualización.

• Managed Airflow actualiza la conexión airflow_db de Airflow para que apunte a la nueva base de datos de Cloud SQL.

Cambiar la versión de Airflow no modifica la forma en que te conectas a los recursos de tu entorno, como la URL del bucket de tu entorno o el servidor web de Airflow.

Acerca de las operaciones de actualización automática de la infraestructura

Managed Airflow ejecuta periódicamente operaciones de actualización automática de la infraestructura:

• Las operaciones de actualización automática de la infraestructura se ejecutan de forma periódica durante los períodos de mantenimiento especificados para el entorno.

• No es posible inhabilitar las actualizaciones automáticas de la infraestructura en Managed Airflow (3ª gen.). Puedes controlar los períodos en los que se pueden ejecutar las actualizaciones automáticas especificando períodos de mantenimiento personalizados para tu entorno.

• Esta operación es visible en la consola de Cloud de Confiance y en los registros del entorno, como cualquier otra operación de larga duración. Mientras se ejecuta la operación, no puedes iniciar otras operaciones a nivel del entorno (pero puedes seguir ejecutando DAG de Airflow).

• En algunos casos, las actualizaciones automáticas de la infraestructura pueden reiniciar los componentes de Airflow. Durante estos reinicios, los trabajadores de Airflow se finalizan de forma correcta con un período de gracia de 24 horas. Si tienes tareas que necesitan más de 24 horas para completarse, considera usar operadores diferibles. Una actualización puede provocar un breve período de falta de disponibilidad para los componentes de la infraestructura del entorno, como la supervisión del entorno.

Limitaciones de las operaciones de actualización y reversión

Las operaciones de actualización tienen las siguientes limitaciones:

• Las versiones de Managed Airflow se lanzan de forma gradual en todas las regiones compatibles con Managed Airflow durante varios días. Es posible que la versión más reciente de un lanzamiento en curso aún no esté disponible en tu región.

• En Managed Airflow (Gen 3), puedes revertir una actualización a una versión o compilación anterior de Airflow con las siguientes limitaciones:

  • Las reversiones se admiten para las actualizaciones realizadas desde las versiones de Airflow 3 o desde las versiones de Airflow 2 a partir de la compilación airflow-2.7.3-build.0.
  • Las reversiones se admiten para las actualizaciones realizadas a las versiones de destino airflow-2.11.1-build.20 o posteriores, airflow-3.2.2-build.7 o posteriores, y airflow-3.3.1-build.3 o posteriores.
  • Puedes iniciar la operación de reversión en un plazo de 30 días a partir de la actualización. Si la compilación de Airflow de destino ya pasó su fecha de finalización de la asistencia, aún es posible revertirla. Puedes realizar reversiones de versiones omitidas. Si actualizaste más de una vez en un plazo de 30 días, puedes volver a cualquier versión que hayas usado antes, siempre y cuando cumpla con las restricciones de elegibilidad.
  • El entorno se encuentra en un estado RUNNING cuando inicias la reversión.

• No puedes actualizar tu entorno si la base de datos de Airflow contiene más de 20 GB de datos. Durante una actualización, se muestra una advertencia si el tamaño de la base de datos de Airflow es superior a 20 GB. En este caso, realiza el mantenimiento de la base de datos para reducir su tamaño.

• Si usas el mecanismo de XCom para transferir archivos, asegúrate de usarlo de acuerdo con los lineamientos de Airflow. La transferencia de archivos grandes o de una gran cantidad de archivos con XCom afecta el rendimiento de la base de datos de Airflow y puede provocar fallas cuando se cargan instantáneas o se actualiza el entorno. Considera usar alternativas, como Cloud Storage, para transferir grandes volúmenes de datos.

Antes de comenzar

• Te recomendamos que crees una instantánea nueva del entorno para poder volver a crearlo en caso de que sea necesario.

• Tu cuenta debe tener un rol que pueda activar operaciones de actualización del entorno. Además, la cuenta de servicio del entorno debe tener un rol que tenga suficientes permisos para realizar operaciones de actualización. Para obtener más información, consulta Control de acceso.

Verifica que tu entorno esté actualizado

Managed Airflow muestra advertencias cuando la compilación de Airflow de tu entorno se acerca a la fecha de finalización de la asistencia. Puedes usar estas advertencias para mantener tu entorno compatible en todo momento.

Managed Airflow hace un seguimiento de la versión y la compilación de Airflow en las que se basa tu entorno. Cuando se acerque la fecha de finalización de la asistencia, podrás ver una advertencia en la lista de entornos y en la página Detalles del entorno.

Para verificar si tu entorno está actualizado, haz lo siguiente:

Ver actualizaciones sugeridas

Managed Airflow proporciona una lista de compilaciones de Airflow a las que puedes actualizar tu entorno.

Para ver las versiones de Managed Airflow sugeridas para una actualización, haz lo siguiente:

gcloud composer environments list-upgrades \
  ENVIRONMENT_NAME \
  --location LOCATION

gcloud composer environments list-upgrades example-environment \
  --location us-central1

// GET https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/imageVersions

Verifica si hay conflictos en los paquetes de PyPI

Puedes verificar si los paquetes de PyPI instalados en tu entorno tienen algún conflicto con los paquetes preinstalados en la nueva versión o compilación de Airflow.

Una verificación exitosa significa que no hay conflictos en las dependencias de paquetes de PyPI entre la versión actual y la especificada. Sin embargo, es posible que una operación de actualización no se realice correctamente por otros motivos.

gcloud composer environments check-upgrade \
  ENVIRONMENT_NAME \
  --location LOCATION \
  --airflow-version VERSION

gcloud composer environments check-upgrade example-environment \
  --location us-central1 \
  --airflow-version airflow-2.11.1-build.21

Waiting for [projects/example-project/locations/us-central1/environments/
example-environment] to be checked for PyPI package conflicts when upgrading
to composer-3-airflow-2.11.1-build.21. Operation [projects/example-project/locations/
us-central1/operations/04d0e8b2-...]...done.
...

Response:
'@type': type.googleapis.com/
google.cloud.orchestration.airflow.service.v1.CheckUpgradeResponse
buildLogUri: ...
containsPypiModulesConflict: CONFLICT
pypiConflictBuildLogExtract: |-
The Cloud Build image build failed: Build failed; check build logs for
details. Full log can be found at ...
Error details: tensorboard 2.2.2 has requirement
setuptools>=41.0.0, but you have setuptools 40.3.0.

{
  "imageVersion": "VERSION"
}

Verifica si hay conflictos con Managed Airflow (3ª gen.)

Managed Airflow (3ª gen.) es la versión principal más reciente de Managed Airflow. Puedes verificar si un entorno de Managed Airflow (2ª gen.) se puede actualizar a Managed Airflow (3ª gen.) con una verificación de actualización. La siguiente descripción se aplica a los entornos de Managed Airflow (2ª gen.).

Si bien no es posible migrar tu entorno de Managed Airflow (2ª gen.) a Managed Airflow (3ª gen.) in situ, puedes verificar si hay problemas de compatibilidad con una verificación de actualización. Te recomendamos que lo hagas antes de migrar a Managed Airflow (3ª gen.).

Para verificar la compatibilidad con Managed Airflow (3ª gen.), realiza una verificación de actualización habitual de tu entorno de Managed Airflow (2ª gen.) y especifica una versión de Managed Airflow (3ª gen.) como destino.

Cada conflicto informado puede tener los siguientes tipos:

• Los informes de conflictos de BLOCKING indican elementos de configuración del entorno incompatibles que no se admiten en Managed Airflow (3ª gen.). Te recomendamos que resuelvas estos conflictos antes de iniciar una migración a Managed Airflow (3ª gen.).

• Los conflictos de NON_BLOCKING informan elementos de configuración del entorno que son diferentes en Managed Airflow (3ª gen.) y que podrían causar un comportamiento inesperado. Por ejemplo, los cambios de los valores predeterminados, como los períodos de mantenimiento predeterminados, se informan como conflictos no bloqueantes. Te recomendamos que verifiques si estos conflictos pueden causar problemas antes de iniciar el proceso de migración.

• Los conflictos de paquetes de PyPI también se informan como parte de esta verificación. Se informan por separado de los conflictos de configuración, de la misma manera que para una verificación de compatibilidad de paquetes de PyPI normal.

gcloud composer environments check-upgrade \
  ENVIRONMENT_NAME \
  --location LOCATION \
  --image-version COMPOSER_3_VERSION

gcloud composer environments check-upgrade example-environment \
  --location us-central1 \
  --image-version composer-3-airflow-2

...
- message: Error validating property [core]unit_test_mode. Overriding [core]
unit_test_mode is not permitted.
type: BLOCKING
- message: Environment variables [GOOGLE_CLOUD_PROJECT] may not be overridden.
type: BLOCKING
- message: You have to specify Worker CPUs to be 0.5, 1.0 or multiples of 2.0.
type: BLOCKING
- message: The environment uses a default maintenance window, which is
different in Composer 2 and Composer 3. Unless set to a custom value, the
maintenance window will be changed to a new default after the upgrade.
type: NON_BLOCKING
...

{
  "imageVersion": "COMPOSER_3_VERSION"
}

Actualiza tu entorno

Para actualizar tu entorno a una versión o compilación nueva de Airflow, haz lo siguiente:

gcloud composer environments update \
  ENVIRONMENT_NAME \
  --location LOCATION \
  --airflow-version VERSION

gcloud composer environments update \
  example-environment \
  --location us-central1 \
  --airflow-version airflow-2.11.1-build.21

// PATCH https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/environments/example-environment?updateMask=
// config.softwareConfig.imageVersion

  {
    "config": {
      "softwareConfig": {
        "imageVersion": "composer-3-airflow-2.11.1-build.21"
      }
    }
  }

  resource "google_composer_environment" "example" {
  provider = google-beta
  name = "ENVIRONMENT_NAME"
  region = "LOCATION"

  config {
    software_config {
      image_version = "VERSION"
    }
  }
}

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

  config {
    software_config {
      image_version = "airflow-2.11.1-build.21"
    }
  }
}

Revierte una actualización

Puedes revertir una actualización del entorno si encuentras un rendimiento degradado, errores de Airflow o problemas de compatibilidad con tus DAGs, complementos o dependencias.

Puedes revertir una actualización en un plazo de 30 días a partir de la operación de actualización si el entorno está en el estado RUNNING. Es posible revertir a versiones que alcanzaron su fecha de finalización de la asistencia. Para obtener más información, consulta Limitaciones de las operaciones de actualización y reversión.

Además de revertir una sola actualización, puedes hacer lo siguiente:

• Realiza varias reversiones sucesivas:

  Ejemplo: A > B > C > B > A (si la reversión a B y A cumple con las limitaciones).

• Realiza reversiones de omisión de versión:

  Ejemplo: A > B > C > A (si la reversión a A cumple con las limitaciones).

Durante una reversión, solo se revierte la compilación de Airflow del entorno a la versión especificada. Managed Airflow conserva los datos y el estado de tu entorno durante las reversiones:

• Archivos DAG y el historial de ejecución: Todas las definiciones de DAG, el historial de ejecuciones de DAG, los estados de las instancias de tareas y las XCom permanecen intactos en la base de datos de metadatos.

• Configuración del entorno: Se conservan las anulaciones de configuración de Airflow, las variables de entorno, los paquetes de PyPI personalizados y la configuración de escalamiento. Si usas requisitos de versión de paquetes de PyPI no estrictos para tus paquetes de PyPI personalizados, es posible que tu entorno tenga una versión de paquete diferente después de la reversión (esta versión seguirá cumpliendo con el requisito de versión especificado).

  Si cambiaste la configuración del entorno durante la actualización, como modificar las variables de entorno o ajustar los límites de recursos para los componentes de Airflow, estos cambios no se revierten. Si es necesario, puedes revertir los cambios de forma manual antes o después de la reversión.

• Registros y supervisión: Se conservan los registros de ejecución de tareas almacenados en Cloud Logging y el historial de métricas en Cloud Monitoring.

Las actualizaciones del esquema de la base de datos de Airflow (migraciones de Alembic) se revierten de forma automática para que coincidan con el esquema de la versión de Airflow de destino. Para obtener la lista de migraciones de bases de datos que están presentes en cada versión de Airflow, consulta Migraciones de bases de datos de Airflow en la documentación de Airflow. Durante una operación de reversión, se revierten todas las migraciones enumeradas entre la versión actual de Airflow y la versión de destino de Airflow.

Busca la versión que usaste anteriormente.

Para encontrar la versión que usaste anteriormente, sigue estos pasos:

gcloud composer operations list \
--locations LOCATION \
--filter='metadata.resource ~ "environments/ENVIRONMENT_NAME$" (metadata.operationType=UPDATE OR metadata.operationType=CREATE)'

┌──────────────────────────────────────┬───────────────┬─────────────┬──────────────────────────────┬───────────┬─────────────────────────────┐
│                 UUID                 │      TYPE     │   LOCATION  │      TARGET_ENVIRONMENT      │   STATE   │         CREATE_TIME         │
├──────────────────────────────────────┼───────────────┼─────────────┼──────────────────────────────┼───────────┼─────────────────────────────┤
│ 71c3d5c9-5b26-4a98-8b19-7f62e9f4ed51 │ UPDATE        │ us-central1 │ example-environment          │ SUCCEEDED │ 2026-10-15T11:18:32.084039Z │
│ 63da3be2-3acf-4fb4-986a-90552a6df8b3 │ UPDATE        │ us-central1 │ example-environment          │ SUCCEEDED │ 2026-08-15T10:56:10.628514Z │
│ 4ebc18a9-25bb-4325-b4c9-0957c67c078b │ UPDATE        │ us-central1 │ example-environment          │ SUCCEEDED │ 2026-06-09T11:30:50.922080Z │
│ 8618f807-abb4-4fc8-9f5b-9353079f6e79 │ UPDATE        │ us-central1 │ example-environment          │ SUCCEEDED │ 2026-05-31T06:57:27.816925Z │
│ 22022864-0fa5-4d1b-92c6-c3f382b43a35 │ UPDATE        │ us-central1 │ example-environment          │ SUCCEEDED │ 2025-11-17T11:52:36.923698Z │
│ ec5bf071-e6c6-4760-b3c9-4a117cb08f7b │ CREATE        │ us-central1 │ example-environment          │ SUCCEEDED │ 2025-11-17T11:17:58.133979Z │
└──────────────────────────────────────┴───────────────┴─────────────┴──────────────────────────────┴───────────┴─────────────────────────────┘

gcloud composer operations describe OPERATION_UUID \
  --location LOCATION \
  --format="value(response.config.softwareConfig.imageVersion)"

Ejecuta la operación de reversión

Para revertir tu entorno a una compilación o versión anterior de Airflow, haz lo siguiente:

gcloud composer environments update \
  ENVIRONMENT_NAME \
  --location LOCATION \
  --airflow-version VERSION

gcloud composer environments update \
  example-environment \
  --location us-central1 \
  --airflow-version airflow-2.11.1-build.21

// PATCH https://composer.googleapis.com/v1/projects/example-project/
// locations/us-central1/environments/example-environment?updateMask=
// config.softwareConfig.imageVersion

  {
    "config": {
      "softwareConfig": {
        "imageVersion": "composer-3-airflow-2.11.1-build.21"
      }
    }
  }

  resource "google_composer_environment" "example" {
  provider = google-beta
  name = "ENVIRONMENT_NAME"
  region = "LOCATION"

  config {
    software_config {
      image_version = "VERSION"
    }
  }
}

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

  config {
    software_config {
      image_version = "airflow-2.11.1-build.21"
    }
  }
}

Si una operación de reversión falla durante la ejecución, Managed Airflow intenta restablecer automáticamente el entorno a su estado anterior a la operación, que es la versión y la compilación de Airflow que se usaron antes de que se iniciara la reversión. Revisa el mensaje de error de la operación y los registros en Cloud Logging para obtener detalles sobre la solución de problemas.

¿Qué sigue?

• Soluciona problemas de actualizaciones y mejoras
• Lista de versiones
• Control de versiones de Managed Airflow
• Actualización de entornos