Implementa canalizaciones de organización

En esta página, se describe el proceso de creación de configuraciones de entornos de implementación para tus canalizaciones de orquestación.

Acerca de los entornos de implementación

Tu proyecto puede tener uno o más entornos de implementación. La configuración de cada entorno de implementación define cómo se implementan las canalizaciones y los recursos que pertenecen a este entorno. Por ejemplo, puedes tener un entorno de implementación para el desarrollo y otro para la producción. Estos entornos de implementación pueden tener conjuntos separados de canalizaciones y ejecutarse en diferentes entornos de ejecutores.

Cada entorno de implementación debe tener un entorno de ejecución. Managed Airflow es el motor de organización que ejecuta tus canalizaciones después de que se implementan. En la versión preliminar, el único entorno de ejecución compatible es un entorno de Managed Airflow que asignaste a tu entorno de implementación.

Puedes especificar un bucket de artefactos para un entorno de implementación. En este bucket, se almacenarán los recursos de canalización versionados que ejecuta la canalización y los resultados de algunas acciones que se generan en el bucket de artefactos.

Acerca de los paquetes de canalizaciones

Las canalizaciones de organización se implementan en paquetes de canalizaciones. Un paquete de canalización contiene una o más canalizaciones y activos de canalización que comparten un ciclo de implementación común.

Cada paquete puede tener varias versiones:

  • Cuando implementas un paquete, se implementan juntos todos los canalizaciones y los secuencias de comandos que acompañan al paquete de una versión específica.
  • Hay exactamente una versión actual del paquete (la que se implementó como la más reciente), mientras que las ejecuciones individuales de la canalización que se activaron con la versión anterior del código continuarán la ejecución sin interrupciones.
  • No puedes activar manualmente la canalización en versiones diferentes de la actual.
  • Si se borra una canalización de un paquete y se implementa la nueva versión del paquete, la canalización no se ejecutará en la nueva versión, pero continuarán las ejecuciones anteriores que se estén ejecutando de forma activa.

Antes de comenzar

Inicializa el andamiaje del paquete de la canalización

Orchestration Pipelines proporciona un comando de gcloud CLI para inicializar un andamiaje para las canalizaciones de orquestación en tu repositorio.

El andamiaje contiene lo siguiente:

  • orchestration-pipeline.yaml: Es un ejemplo de definición de canalización que contiene un programa, pero no acciones definidas.
  • deployment.yaml: Es un ejemplo de configuración de implementación de canalización que define cómo se debe implementar tu canalización. Contiene la configuración del entorno del ejecutor, el bucket de artefactos y cualquier otro recurso que usen las acciones de tu canalización.
  • .github/workflows/validate.yaml: Es un ejemplo de acción de GitHub que valida tu canalización cuando se crea una solicitud de extracción para la rama main.
  • .github/workflows/deploy.yaml: Es un ejemplo de acción de GitHub que implementa tu canalización cuando combinas cambios en la rama main de tu repositorio de GitHub.

Para inicializar una canalización de organización, haz lo siguiente:

  1. Navega al directorio de tu repositorio o proyecto. El comando creará archivos nuevos en el directorio en el que lo ejecutes.

  2. Ejecuta el siguiente comando de gcloud CLI:

    gcloud beta orchestration-pipelines init PIPELINE_NAME \
  --environment DEPLOYMENT_ENVIRONMENT \
  --composer-environment RUNNER_ENVIRONMENT \
  --artifacts-bucket ARTIFACTS_BUCKET_NAME \
  --project PROJECT_ID \
  --region REGION \
  --service-account SERVICE_ACCOUNT

    Reemplaza lo siguiente:

    • PIPELINE_NAME: Es el nombre de la canalización inicial.
    • DEPLOYMENT_ENVIRONMENT: Es el nombre del entorno de implementación inicial.
    • RUNNER_ENVIRONMENT: Es el nombre del entorno del ejecutor.
    • ARTIFACTS_BUCKET_NAME: Es un bucket de Cloud Storage que se usará para almacenar artefactos de acciones de la canalización, sin el prefijo gs://.
    • PROJECT_ID: Es el ID del proyecto de un Google Cloud proyecto en el que se encuentra el entorno del ejecutor.
    • REGION: Es la región en la que se encuentra el entorno del ejecutor.

    • SERVICE_ACCOUNT: Es la cuenta de servicio que se preestablecerá como una variable. Establece este valor en la cuenta de servicio del entorno del ejecutor. Puedes usar esta variable en las definiciones de canalizaciones y los perfiles de recursos. Por ejemplo, como valor para el parámetro impersonationChain en acciones que usan una cadena de suplantación.

      Puedes obtener la cuenta de servicio de tu entorno de ejecución consultando los detalles del entorno. En gcloud CLI, la cuenta de servicio del entorno se proporciona en la clave nodeConfig.serviceAccount.

    Ejemplo:

    gcloud beta orchestration-pipelines init example-pipeline \
  --environment development \
  --composer-environment production-runner-us-central1 \
  --artifacts-bucket production-artifacts \
  --project example-production-project \
  --region us-central1 \
  --service-account example-account@example-project.iam.gserviceaccount.com

Agrega la configuración del entorno del ejecutor

El entorno del ejecutor se especifica en la clave composer_environment de un entorno de implementación. Si usas varios entornos de implementación, puedes especificar un entorno de ejecución independiente para cada uno.

El nombre del entorno del ejecutor en la clave composer_environment junto con las claves project y region en la configuración del entorno de desarrollo especifican el entorno del ejecutor en el que se implementa la canalización.

En el siguiente ejemplo, se muestra cómo agregar un entorno de ejecución con el nombre example-runner-environment ubicado en la región us-central1, en el proyecto example-development-project:

environments:
  example-development-environment:
    project: "example-development-project"
    region: "us-central1"
    composer_environment: "example-runner-environment"
    ...

Ajusta la configuración del entorno del ejecutor

Puedes configurar tu entorno de ejecución como cualquier otro entorno de Managed Service para Apache Airflow:

Agrega los recursos de tu canalización y configura las acciones

Edita el archivo de definición de tu canalización para incluir acciones y recursos de canalización:

Ejemplo de acción de Hello World

A continuación, se muestra un ejemplo de una acción de canalización minimalista. Puedes usarlo para probar la configuración del entorno de implementación.

  1. Agrega la siguiente acción a tu canalización de andamiaje y reemplaza actions: []:

    actions:
  - python:
      name: "hello_world_script_run"
      executionTimeout: "30m"
      mainFilePath: "scripts/hello_world.py"
      pythonCallable: "main"
      engine:
        local: {}

  2. Crea un subdirectorio nuevo llamado scripts en tu repositorio y guarda el siguiente archivo como /scripts/hello_world.py:

    def main():
  print("Hello, World!")

Valida canalizaciones

El comando de validación verifica la sintaxis y la corrección del tipo de los archivos de definición de la canalización, y también realiza verificaciones semánticas para recursos como el proyectoGoogle Cloud y el entorno de Managed Service para Apache Airflow en los archivos de configuración de implementación y de definición de la canalización.

De forma predeterminada, se realiza la validación completa de todos los entornos de implementación, incluido el contacto con los entornos de ejecutores remotos. Puedes validar partes específicas de la configuración de tu implementación con los siguientes parámetros:

  • --mode: Se establece en syntax-only para no acceder a los entornos de ejecutores remotos. El valor predeterminado es full.
  • --environment: Valida solo un entorno específico.
  • --pipeline-paths: Es una lista separada por comas de las rutas de acceso a los archivos de definición de la canalización que se validarán.
  • --substitutions y --substitutions-file: Parámetros de configuración de la implementación de sustitución durante la validación.

Puedes ejecutar este comando como una verificación rápida antes de implementar versiones locales de la canalización y como una acción de GitHub como parte de tu flujo de trabajo de CI/CD.

Ejecuta el siguiente comando en tu repositorio para validar tus canalizaciones:

gcloud beta orchestration-pipelines validate

Implementa un paquete de canalización

En esta sección, se describen diferentes formas de implementar tus canalizaciones.

Las Canalizaciones de organización admiten dos formas de implementar tus paquetes de canalizaciones. Estos enfoques están diseñados para funcionar en conjunto durante las diferentes etapas del flujo de trabajo de desarrollo y lanzamiento:

  • Implementa una versión del paquete local: Implementa las versiones actuales de los recursos de la canalización, las definiciones de la canalización y la configuración de la implementación. El nuevo ID del paquete se generará automáticamente en función del nombre del espacio de trabajo y el MD5 de los archivos del paquete.

    Este tipo de implementación está destinado a fines de desarrollo. También recomendamos crear una configuración de implementación independiente que implemente las canalizaciones en un entorno de ejecución de etapa de pruebas.

  • Implementa los cambios confirmados: Después de confirmar los cambios en los recursos, las definiciones y la configuración de implementación de la canalización, puedes implementar una versión nueva del paquete de la canalización en el entorno del ejecutor. El ID del nuevo paquete se vinculará al SHA de la confirmación de Git en tu repositorio.

    Este tipo de implementación está diseñado para ejecutarse como parte de la CI/CD, por ejemplo, a través de una acción de GitHub. También puedes implementar los cambios confirmados desde un repositorio de Git local.

Las canalizaciones de organización admiten varias formas de sustituir parámetros en los archivos de configuración de implementación y definición de canalización, lo que puede ser útil cuando implementas canalizaciones para el desarrollo local y para los comandos que se ejecutan en las acciones de GitHub. Por ejemplo, puedes sustituir parámetros con el argumento --substitutions en los comandos de la gcloud CLI, configurar una variable de entorno o bien obtener el valor de los secretos de GitHub.

Ejecuta comandos de implementación

Local

Para implementar una versión del paquete local, usa el argumento --local:

gcloud beta orchestration-pipelines deploy \
  --environment DEPLOYMENT_ENVIRONMENT \
  --local

Reemplaza lo siguiente:

  • DEPLOYMENT_ENVIRONMENT: Es el entorno de implementación de la canalización.

Ejemplo:

gcloud beta orchestration-pipelines deploy \
  --environment example-deployment-environment \
  --local

El ejemplo de salida contiene el nombre y la versión del paquete de la canalización, y el estado de la implementación:

Bundle ID: bundle-local-example-orchestrationpipelines
Version ID: local-14776d43ebba

...

--- Pipeline Deployment Status ---
Pipeline 'example-pipeline': [OK] (Status: HEALTHY)

--- Pipeline Deployment full details ---

...

Confirmada

Para implementar los cambios, asegúrate de que se hayan confirmado en tu repositorio. Ejecuta el siguiente comando en gcloud CLI:

gcloud beta orchestration-pipelines deploy \
  --environment DEPLOYMENT_ENVIRONMENT

Reemplaza lo siguiente:

  • DEPLOYMENT_ENVIRONMENT: Es el entorno de implementación de la canalización.

Ejemplo:

gcloud beta orchestration-pipelines deploy \
  --environment example-deployment-environment

El ejemplo de salida contiene el nombre y la versión del paquete de la canalización, y el estado de la implementación:

Bundle ID: bundle-local-example-orchestrationpipelines
Version ID: local-14776d43ebba

...

--- Pipeline Deployment Status ---
Pipeline 'example-pipeline': [OK] (Status: HEALTHY)

--- Pipeline Deployment full details ---

...

Acción de GitHub

El andamiaje de la canalización tiene dos acciones de GitHub de ejemplo que pueden ayudarte a comenzar a implementar y validar tus canalizaciones a través de una acción de GitHub. Cuando subes estos archivos a GitHub, tu repositorio se configura con estas acciones. Para obtener información sobre cómo configurar acciones de GitHub más complejas, consulta Implementación con GitHub Actions en la documentación de GitHub.

Para usar las acciones de GitHub de ejemplo, haz lo siguiente:

  1. Crea una cuenta de servicio independiente que ejecutará los comandos de gcloud CLI desde las acciones de GitHub.

  2. Asigna roles que permitan ejecutar comandos de implementación y validación en esta cuenta de servicio.

  3. Crea una clave de cuenta de servicio para esta cuenta de servicio.

  4. Agrega el secreto GCP_SA_KEY a tu repositorio de GitHub y establece su valor en la clave de la cuenta de servicio creada. Para obtener más información sobre cómo agregar secretos, consulta Uso de secretos en GitHub Actions.

Configuración de implementación

En esta sección, se proporciona información sobre la configuración adicional que puedes aplicar a un entorno de implementación.

Cómo agregar o quitar otra canalización

Para agregar otra canalización a un entorno de implementación existente, haz lo siguiente:

  1. Agrega un archivo de definición de canalización y recursos de canalización al repositorio.
  2. En la configuración de la implementación, agrega una clave source nueva con el valor que apunta al nuevo archivo de definición de la canalización.

Ejemplo:

environments:
  dev:

    ...

    pipelines:
      - source: example-pipeline.yaml
      - source: another-pipeline.yaml

Para quitar una canalización, haz lo siguiente:

  1. En la configuración de la implementación, quita la clave source de la canalización.
  2. Quita el archivo de definición de la canalización y los recursos de la canalización del repositorio.
  3. Implementa la nueva versión de la canalización. La canalización no estará presente en la nueva versión del paquete.

Agregar otro entorno de implementación

Para agregar otro entorno de implementación, haz lo siguiente:

  1. En la configuración de implementación, agrega una clave nueva a la asignación de environments.
  2. Asegúrate de que tu configuración de implementación y las definiciones de canalización usen variables y variables de configuración de implementación para ejecutar acciones de canalización que requieran diferenciar entre los recursos de Google Cloudque pertenecen a cada entorno.

Ejemplo:

environments:

  example-development-environment:
    project: "example-development-project"
    region: "us-central1"
    composer_environment: "development-runner-us-central1"
    ...
    variables:
      service_account: "another-service-account@example-development-project.iam.gserviceaccount.com"
    ...

  example-production-environment:
    project: "example-production-project"
    region: "us-central1"
    composer_environment: "production-runner-us-central1"
    ...
    variables:
      service_account: "example-account@example-project.iam.gserviceaccount.com"

Variables, secretos y sustitución

Después de definir variables en la configuración de la implementación, puedes usarlas en las definiciones de canalizaciones y los perfiles de recursos.

Agrega variables personalizadas

Puedes agregar tus propias variables a la clave variables en la configuración de implementación:

  1. En el entorno de configuración de la implementación, agrega la clave variables.
  2. Agrega una asignación de nombres y valores de variables.
  3. Para obtener el valor de la variable en las definiciones de tu canalización y los perfiles de recursos, encierra el nombre de la variable entre llaves dobles: {{ example_variable }}.

En el siguiente ejemplo, se establecen las mismas variables en dos entornos de implementación.

environments:
  example-development-environment:
    project: "example-development-project"
    region: "us-central1"
    composer_environment: "development-runner-us-central1"
    artifact_storage:
      bucket: "development-artifacts"
      path_prefix: pipelines
    pipelines:
      - source: example-pipeline.yaml
    variables:
      service_account: "another-service-account@example-development-project.iam.gserviceaccount.com"
      network_uri: projects/example-development-project/global/networks/default

  example-production-environment:
    project: "example-production-project"
    region: "us-central1"
    composer_environment: "production-runner-us-central1"
    artifact_storage:
      bucket: "production-artifacts"
      path_prefix: pipelines
    pipelines:
      - source: example-pipeline.yaml
    variables:
      service_account: "example-account@example-project.iam.gserviceaccount.com"
      network_uri: projects/example-production-project/global/networks/vpc-main

A continuación, se muestra un perfil de recursos de Managed Service para Apache Spark que lee estas variables. Las acciones en el archivo de definición de tu canalización (example-pipeline.yaml) pueden usar el mismo perfil de recursos, y no es necesario que las ajustes entre los entornos de producción y desarrollo.

profileId: serverless-standard
type: dataproc.session
definition:
  environmentConfig:
    execution_config:
      service_account: "{{ service_account }}"
      network_uri: "{{ network_uri }}"

Cómo acceder a los parámetros de configuración de la implementación

Algunos parámetros de la configuración de implementación también están disponibles como variables:

  • project
  • region
  • composer_environment
  • COMMIT_SHA: Es el SHA de la confirmación actual del repositorio de Git. Puedes usar esta variable, por ejemplo, sustituyendo su valor cuando implementes una versión local del paquete de la canalización. De esta manera, las acciones que dependen del valor SHA de la confirmación seguirán operando con el contenido de archivo correcto.

En el siguiente ejemplo, la definición de la canalización establece valores predeterminados para las acciones de la canalización según los parámetros de configuración de la implementación project y region.

pipelineId: example-pipeline
description: Example pipeline
runner: 'airflow'
owner: 'data-eng-team'
modelVersion: '1.0'
defaults:
  projectId: {{ project }}
  location: {{ region }}
  executionConfig:
    retries: 1

Accede a los secretos de la acción de GitHub

Puedes usar secretos de GitHub en los archivos de configuración de implementación y definición de tu canalización. Cuando se implementa una canalización a través de una acción de GitHub, los valores de estos secretos se pasan tanto a las definiciones de la canalización como a la configuración de implementación.

Para crear un secreto al que se podrá acceder durante la implementación, haz lo siguiente:

  1. En GitHub, agrega un secreto con el prefijo DEPLOY_VAR_. Ejemplo: DEPLOY_VAR_API_KEY.

    Para obtener más información sobre cómo crear secretos, consulta Uso de secretos en GitHub Actions en la documentación de GitHub.

  2. Agrega la misma variable de entorno a tu flujo de trabajo de GitHub. Lee el valor de esta variable de los secretos de GitHub.

    Ejemplo:

    jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      DEPLOY_VAR_API_KEY: ${{ secrets.API_KEY }}

    steps:

    ...

    Para obtener más información sobre cómo agregar variables de entorno a los flujos de trabajo, consulta Almacena información en variables en la documentación de GitHub.

  3. Usa el nombre de la variable (sin el prefijo DEPLOY_VAR_) en los archivos de definición de la canalización y en la configuración de la implementación. Ejemplo: {{ API_KEY }}.

  4. (Opcional) Para implementar una versión local de una canalización que usa secretos de GitHub, puedes sustituir las variables de entorno DEPLOY_VAR_* del secreto a través de parámetros de la línea de comandos o definiéndolas en el entorno en el que ejecutas los comandos de implementación.

Sustituye variables a través de parámetros de la línea de comandos

Los comandos de implementación de la CLI de gcloud admiten el argumento --substitutions, que puedes usar para anular o establecer variables para las definiciones de tu canalización y la configuración de implementación.

Para sustituir variables a través de parámetros de la línea de comandos, proporciona la lista de variables y sus valores en la línea de comandos:

Ejemplo:

gcloud beta orchestration-pipelines deploy \
  --environment example-deployment-environment \
  --local \
  --substitutions=VARIABLE_NAME_1=value_1,VARIABLE_NAME_2=value_2

Como alternativa, puedes almacenar sustituciones en un archivo YAML y especificarlo en el argumento --substitutions-file:

gcloud beta orchestration-pipelines deploy \
  --environment example-deployment-environment \
  --local \
  --substitutions-file=substitutions.yaml

En el archivo de sustituciones, proporciona una asignación de variables: 

VARIABLE_NAME_1: value_1
VARIABLE_NAME_2: value_2

Puedes usar el nombre de la variable en tus archivos de definición de canalización y en la configuración de implementación. Ejemplo: {{ VARIABLE_NAME_1 }}.

Proporciona y sustituye variables a través de variables de entorno

Tus definiciones de canalización y tu configuración de implementación pueden usar variables de entorno que tengan el prefijo DEPLOY_VAR_.

  1. Establece una variable de entorno:

    export DEPLOY_VAR_VARIABLE_NAME_1=value_1

  2. Puedes usar el nombre de la variable (sin el prefijo DEPLOY_VAR_) en los archivos de definición de la canalización y en la configuración de implementación. Ejemplo: {{ VARIABLE_NAME_1 }}.

¿Qué sigue?