Gerenciar pipelines de orquestração

É possível gerenciar pipelines de orquestração implantados em ambientes de execução usando comandos da Google Cloud CLI.

Sobre ambientes de implantação

O projeto pode ter um ou mais ambientes de implantação. A configuração de cada ambiente de implantação define como os pipelines e recursos pertencentes a ele são implantados. Por exemplo, é possível ter um ambiente de implantação para desenvolvimento e outro para produção. Esses ambientes de implantação podem ter conjuntos separados de pipelines e ser executados em ambientes de execução diferentes.

Cada ambiente de implantação precisa ter um ambiente de execução. O Airflow gerenciado é o mecanismo de orquestração que executa os pipelines depois que eles são implantados. Um ambiente de execução é um ambiente do Airflow gerenciado que você atribuiu a o ambiente de implantação.

Sobre pacotes de pipeline

Os pipelines de orquestração são implantados em pacotes de pipeline. Um pacote de pipeline contém um ou mais pipelines e recursos de pipeline que compartilham um ciclo de implantação comum.

Cada pacote pode ter várias versões. Ao implantar um pacote, todos os pipelines e scripts que o acompanham no pacote de uma versão específica são implantados juntos. Se uma execução de pipeline for acionada, todos os pipelines e recursos de pipeline vão permanecer na versão do pacote usada para iniciar a execução, mesmo que você implante uma nova versão enquanto isso.

Conferir a lista de pipelines

gcloud

Para conferir a lista de pipelines de orquestração em um ambiente de implantação, execute o seguinte comando da Google Cloud CLI no diretório em que o arquivo deployment.yaml está localizado:

gcloud beta orchestration-pipelines list \
  --environment DEPLOYMENT_ENVIRONMENT \
  --bundle BUNDLE_NAME \
  --owner OWNER_NAME

Substitua:

  • DEPLOYMENT_ENVIRONMENT: lista os pipelines no ambiente de implantação especificado.

    Como alternativa, você pode executar esse comando para um ambiente de execução específico runner environment. Nesse caso, substitua o argumento --environment pelo argumento --runner e especifique o ID completo do recurso do ambiente de execução. Exemplo: //composer.googleapis.com/projects/example-project/locations/us-central1/environments/example-runner-environment.

  • (Opcional) BUNDLE_NAME: lista os pipelines que pertencem ao pacote especificado.

  • (Opcional) OWNER_NAME: se especificado, lista os pipelines que pertencem ao proprietário especificado.

Exemplo:

gcloud beta orchestration-pipelines list \
  --environment example-deployment-environment \
  --bundle example-pipeline-bundle \
  --owner example-pipeline-owner

Console

Para conferir a lista de pipelines de orquestração em um ambiente de implantação:

  1. No Google Cloud console, acesse a página Ambientes.

    Acessar "Ambientes"

  2. Na lista de ambientes, clique no nome do seu ambiente. A página Detalhes do ambiente é aberta.

  3. Acesse a guia Orquestração de Pipelines. A guia mostra a lista de todos os pipelines implantados no seu ambiente.

Conferir a descrição detalhada de um pipeline

gcloud

Para conferir a descrição de um pipeline específico, execute o seguinte comando na CLI gcloud:

gcloud beta orchestration-pipelines describe \
  --environment DEPLOYMENT_ENVIRONMENT \
  --bundle BUNDLE_NAME \
  --pipeline PIPELINE_NAME

Substitua:

  • DEPLOYMENT_ENVIRONMENT: ambiente de implantação do pipeline.

    Como alternativa, você pode executar esse comando para um ambiente de execução específico runner environment. Nesse caso, substitua o argumento --environment pelo argumento --runner e especifique o ID completo do recurso do ambiente de execução. Exemplo: //composer.googleapis.com/projects/example-project/locations/us-central1/environments/example-runner-environment.

  • BUNDLE_NAME: pacote a que o pipeline pertence.

  • PIPELINE_NAME: nome do pipeline.

Exemplo:

gcloud beta orchestration-pipelines list \
  --bundle example-pipeline-bundle \
  --pipeline example-pipeline \
  --environment example-deployment-environment

Console

  1. No Google Cloud console, acesse a página Ambientes.

    Acessar "Ambientes"

  2. Na lista de ambientes, clique no nome do seu ambiente. A página Detalhes do ambiente é aberta.

  3. Acesse a guia Pipelines de orquestração. A guia mostra a lista de todos os pipelines implantados no seu ambiente.

  4. Clique no nome do pipeline. A página Detalhes do pipeline é aberta:

    • A guia Detalhes mostra informações detalhadas sobre o pipeline, como ID, status e SHA de confirmação de origem.
    • A guia Gráfico mostra um gráfico que descreve as ações individuais do pipeline. Clique nos nós do gráfico para conferir informações detalhadas sobre cada ação.
    • A guia Origem YAML mostra a definição do pipeline.
    • A guia Histórico de execuções mostra o histórico e o status das execuções do pipeline.

Implantar um pacote de pipeline

Esse comando implanta pacotes de pipeline e recursos de pipeline de acordo com a configuração de implantação fornecida. Verifique se você já configurou a implantação do pipeline antes de executar esse comando.

Para implantar um pacote de pipeline em um ambiente de implantação:

  • Implante as mudanças confirmadas: depois de confirmar as mudanças nos recursos de pipeline, nas definições de pipeline e na configuração de implantação, você pode implantar uma nova versão do pacote de pipeline no ambiente de execução. O ID do novo pacote será vinculado à confirmação no seu repositório. Esse tipo de implantação geralmente é executado como parte da CI/CD. Por exemplo, pelo fluxo de trabalho do GitHub Actions.
  • Implante uma versão do pacote local: implante as versões atuais dos recursos de pipeline, das definições de pipeline e da configuração de implantação. O novo ID do pacote será marcado como uma implantação local. Esse tipo de implantação é destinado a fins de desenvolvimento.

Para implantar as mudanças confirmadas, execute o seguinte comando na CLI gcloud:

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

Para implantar uma versão local, use o argumento --local:

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

Substitua:

  • DEPLOYMENT_ENVIRONMENT: ambiente de implantação do pipeline.

Exemplo:

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

O exemplo de saída contém o status da implantação.

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

--- Pipeline Deployment full details ---
...

Acionar uma execução manual de um pipeline

É possível acionar uma execução manual de um pipeline de orquestração específico:

  • O pacote de pipeline já precisa estar implantado antes de ser acionado.

  • Só é possível acionar a versão implantada mais recente do pipeline no pacote. Depois que a execução é acionada, os pipelines sempre executam todas as tarefas na versão do pacote com que foi iniciado, mesmo que você faça o upload de uma versão mais recente do código enquanto isso.

Para acionar uma execução manual, execute o seguinte comando na CLI gcloud:

gcloud beta orchestration-pipelines trigger \
  --environment DEPLOYMENT_ENVIRONMENT \
  --bundle BUNDLE_NAME \
  --pipeline PIPELINE_NAME

Substitua:

  • DEPLOYMENT_ENVIRONMENT: ambiente de implantação do pipeline.

    Como alternativa, você pode executar esse comando para um ambiente de execução específico runner environment. Nesse caso, substitua o argumento --environment pelo argumento --runner e especifique o ID completo do recurso do ambiente de execução. Exemplo: //composer.googleapis.com/projects/example-project/locations/us-central1/environments/example-runner-environment.

  • BUNDLE_NAME: pacote a que o pipeline pertence.

  • PIPELINE_NAME: nome do pipeline.

Exemplo:

gcloud beta orchestration-pipelines trigger \
  --environment example-deployment-environment \
  --bundle example-pipeline-bundle \
  --pipeline example-pipeline

Listar o histórico de execuções de um pipeline

gcloud

Para conferir o histórico de execuções de um único pipeline de orquestração, incluindo execuções em todas as versões anteriores do pipeline, execute o seguinte comando na CLI gcloud:

gcloud beta orchestration-pipelines runs list \
  --environment DEPLOYMENT_ENVIRONMENT \
  --bundle BUNDLE_NAME \
  --pipeline PIPELINE_NAME

Substitua:

  • DEPLOYMENT_ENVIRONMENT: ambiente de implantação em que o pipeline está localizado.

    Como alternativa, você pode executar esse comando para um ambiente de execução específico runner environment. Nesse caso, substitua o argumento --environment pelo argumento --runner e especifique o ID completo do recurso do ambiente de execução. Exemplo: //composer.googleapis.com/projects/example-project/locations/us-central1/environments/example-runner-environment.

  • BUNDLE_NAME: pacote a que o pipeline pertence.

  • PIPELINE_NAME: nome do pipeline.

Exemplo:

gcloud beta orchestration-pipelines runs list \
  --environment example-deployment-environment \
  --bundle example-pipeline-bundle \
  --pipeline example-pipeline

Console

  1. No Google Cloud console, acesse a página Ambientes.

    Acessar "Ambientes"

  2. Na lista de ambientes, clique no nome do seu ambiente. A página Detalhes do ambiente é aberta.

  3. Acesse a guia Orquestração de Pipelines. A guia mostra a lista de todos os pipelines implantados no seu ambiente.

  4. Clique no nome do pipeline. A página Detalhes do pipeline é aberta.

  5. Acesse a guia Histórico de execuções. A guia mostra o histórico e o status das execuções do pipeline.

  6. Clique em um ID de execução do DAG para acessar a página de detalhes da execução do DAG.

Listar detalhes da execução do pipeline

Para conferir os detalhes de uma única execução de pipeline de orquestração, execute o seguinte comando na CLI gcloud:

gcloud beta orchestration-pipelines runs describe \
  --environment DEPLOYMENT_ENVIRONMENT \
  --bundle BUNDLE_NAME \
  --pipeline PIPELINE_NAME \
  --run-id RUN_ID

Substitua:

  • DEPLOYMENT_ENVIRONMENT: ambiente de implantação em que o pipeline está localizado.

    Como alternativa, você pode executar esse comando para um ambiente de execução específico runner environment. Nesse caso, substitua o argumento --environment pelo argumento --runner e especifique o ID completo do recurso do ambiente de execução. Exemplo: //composer.googleapis.com/projects/example-project/locations/us-central1/environments/example-runner-environment.

  • BUNDLE_NAME: pacote a que o pipeline pertence.

  • PIPELINE_NAME: nome do pipeline.

  • RUN_ID: o identificador da execução do pipeline. É possível receber esse ID em a lista de execuções.

Exemplo:

gcloud beta orchestration-pipelines runs describe \
  --environment example-deployment-environment \
  --bundle example-pipeline-bundle \
  --pipeline example-pipeline \
  --run-id scheduled__2026-04-20T02:00:00+00:00

Exemplo de saída:

pipelineRuns:
- actions:
  - end_date: '2026-04-21T02:02:31.947672Z'
    execution_date: '2026-04-20T02:00:00Z'
    max_retries: 1
    metadata:
      airflow_dag_id: example-pipeline-bundle__v__33816e2690e93d03ee7b67d16765d9825549636c__example-pipeline
      airflow_task_instances:
      - end_date: '2026-04-21T02:02:31.947672Z'
        execution_date: '2026-04-20T02:00:00Z'
        max_retries: 1
        name: new_pyspark_task_1775735209136
        start_date: '2026-04-21T02:00:17.256040Z'
        state: SUCCEEDED
        try_number: 1
    name: new_pyspark_task_1775735209136
    start_date: '2026-04-21T02:00:17.256040Z'
    state: SUCCEEDED
    try_number: 1
  bundle_id: example-pipeline-bundle
  end_date: '2026-04-21T02:02:32.455241Z'
  execution_date: '2026-04-20T02:00:00Z'
  metadata:
    airflow_dag_id: example-pipeline-bundle__v__33816e2690e93d03ee7b67d16765d9825549636c__example-pipeline
  pipeline_id: example-pipeline
  pipeline_run_id: scheduled__2026-04-20T02:00:00+00:00
  start_date: '2026-04-21T02:00:00.952825Z'
  state: SUCCEEDED
  type: SCHEDULED
  version: 33816e2690e93d03ee7b67d16765d9825549636c

Pausar execuções programadas de pipeline

Depois de pausado, o pipeline não será executado na programação. É possível acionar uma execução manual do pipeline para esses pipelines. Isso vai manter o pipeline pausado e criar uma execução manual fora da programação. Reative o pipeline para ativar a programação.

Para pausar todas as execuções programadas de pipeline, execute o seguinte comando na CLI gcloud:

gcloud beta orchestration-pipelines pause \
  --environment DEPLOYMENT_ENVIRONMENT \
  --bundle BUNDLE_NAME \
  --pipeline PIPELINE_NAME \

Substitua:

  • DEPLOYMENT_ENVIRONMENT: ambiente de implantação em que o pipeline está localizado.

    Como alternativa, você pode executar esse comando para um ambiente de execução específico runner environment. Nesse caso, substitua o argumento --environment pelo argumento --runner e especifique o ID completo do recurso do ambiente de execução. Exemplo: //composer.googleapis.com/projects/example-project/locations/us-central1/environments/example-runner-environment.

  • BUNDLE_NAME: pacote a que o pipeline pertence.

  • PIPELINE_NAME: nome do pipeline.

Exemplo:

gcloud beta orchestration-pipelines pause \
  --environment example-deployment-environment \
  --bundle example-pipeline-bundle \
  --pipeline example-pipeline

Reativar execuções programadas de pipeline

Para reativar as execuções programadas de pipeline, execute o seguinte comando na CLI gcloud:

gcloud beta orchestration-pipelines unpause \
  --environment DEPLOYMENT_ENVIRONMENT \
  --bundle BUNDLE_NAME \
  --pipeline PIPELINE_NAME \

Substitua:

  • DEPLOYMENT_ENVIRONMENT: ambiente de implantação em que o pipeline está localizado.

    Como alternativa, você pode executar esse comando para um ambiente de execução específico runner environment. Nesse caso, substitua o argumento --environment pelo argumento --runner e especifique o ID completo do recurso do ambiente de execução. Exemplo: //composer.googleapis.com/projects/example-project/locations/us-central1/environments/example-runner-environment.

  • BUNDLE_NAME: pacote a que o pipeline pertence.

  • PIPELINE_NAME: nome do pipeline.