Implantar pipelines de orquestração

Nesta página, descrevemos o processo de criação de configurações de ambiente de implantação para seus pipelines de orquestração.

Sobre ambientes de implantação

Seu 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 esse ambiente 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 seus pipelines depois que eles são implantados. Na versão prévia, o único ambiente de execução de runner compatível é um ambiente do Airflow gerenciado que você atribuiu ao seu ambiente de implantação.

É possível especificar um bucket de artefatos para um ambiente de implantação. Esse bucket armazenará recursos de pipeline com controle de versões que o pipeline executa e resultados de algumas ações que são enviadas para o bucket de artefatos.

Sobre pacotes de pipelines

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 acompanhantes no pacote de uma versão específica são implantados juntos.
  • Há exatamente uma versão atual do pacote (a que foi implantada como a mais recente), enquanto as execuções individuais do pipeline que foram acionadas com a versão anterior do código continuam a execução sem interrupções.
  • Não é possível acionar manualmente o pipeline em versões diferentes da atual.
  • Se um pipeline for excluído de um pacote e a nova versão do pacote for implantada, o pipeline não será executado na nova versão, mas as execuções ativas anteriores continuarão.

Antes de começar

Inicializar o scaffolding do pacote de pipeline

O Orquestração de Pipelines fornece um comando da CLI gcloud para inicializar um scaffolding para pipelines de orquestração no seu repositório.

O scaffolding contém o seguinte:

  • orchestration-pipeline.yaml: um exemplo de definição de pipeline que contém uma programação, mas nenhuma ação definida.
  • deployment.yaml: um exemplo de configuração de implantação de pipeline que define como o pipeline precisa ser implantado. Contém a configuração do ambiente do executor, do bucket de artefatos e de outros recursos usados pelas ações do pipeline.
  • .github/workflows/validate.yaml: um exemplo de ação do GitHub que valida seu pipeline quando uma solicitação de envio para a ramificação main é criada.
  • .github/workflows/deploy.yaml: um exemplo de ação do GitHub que implanta seu pipeline quando você mescla mudanças na ramificação main do seu repositório do GitHub.

Para inicializar um pipeline de orquestração:

  1. Navegue até o diretório do repositório ou do projeto. O comando vai criar novos arquivos no diretório em que você o executa.

  2. Execute o seguinte comando da CLI gcloud:

    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

    Substitua:

    • PIPELINE_NAME: nome do pipeline inicial.
    • DEPLOYMENT_ENVIRONMENT: nome do ambiente de implantação inicial.
    • RUNNER_ENVIRONMENT: nome do ambiente de execução.
    • ARTIFACTS_BUCKET_NAME: um bucket do Cloud Storage que será usado para armazenar artefatos de ação do pipeline, sem o prefixo gs://.
    • PROJECT_ID: o ID do projeto de um projeto Google Cloud em que o ambiente do executor está localizado.
    • REGION: a região em que o ambiente do executor está localizado.

    • SERVICE_ACCOUNT: a conta de serviço que será predefinida como uma variável. Defina esse valor como a conta de serviço do ambiente do executor. É possível usar essa variável em definições de pipeline e perfis de recursos. Por exemplo, como um valor para o parâmetro impersonationChain em ações que usam uma cadeia de representação.

      Para conferir a conta de serviço do ambiente de execução, consulte os detalhes do ambiente. Na CLI gcloud, a conta de serviço do ambiente é fornecida na chave nodeConfig.serviceAccount.

    Exemplo:

    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

Adicionar configuração do ambiente do executor

O ambiente do executor é especificado na chave composer_environment de um ambiente de implantação. Se você usa vários ambientes de implantação, pode especificar um ambiente de execução separado para cada um deles.

O nome do ambiente do executor na chave composer_environment, junto com as chaves project e region na configuração do ambiente de desenvolvimento, especifica o ambiente do executor em que o pipeline é implantado.

O exemplo a seguir demonstra como adicionar um ambiente de execução com o nome example-runner-environment localizado na região us-central1, no projeto example-development-project:

environments:
  example-development-environment:
    project: "example-development-project"
    region: "us-central1"
    composer_environment: "example-runner-environment"
    ...
especificamente nesse ambiente de runner.

Ajustar a configuração do ambiente do executor

É possível configurar o ambiente do runner como qualquer outro ambiente do Serviço gerenciado para Apache Airflow:

Adicionar recursos de pipeline e configurar ações

Edite o arquivo de definição do pipeline para incluir ações e recursos do pipeline:

Exemplo de ação "Hello World"

Confira um exemplo de ação de pipeline minimalista: Você pode usar esse recurso para testar a configuração do ambiente de implantação.

  1. Adicione a seguinte ação ao seu pipeline de scaffolding, substituindo actions: []:

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

  2. Crie um novo subdiretório chamado scripts no seu repositório e salve o arquivo a seguir como /scripts/hello_world.py:

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

Validar pipelines

O comando de validação verifica a sintaxe e a correção de tipo dos arquivos de definição de pipeline e também realiza verificações semânticas para recursos como o projetoGoogle Cloud e o ambiente do Serviço gerenciado para Apache Airflow nos arquivos de configuração de implantação e de definição de pipeline.

Por padrão, a validação completa de todos os ambientes de implantação é realizada, incluindo o contato com ambientes de execução remota. É possível validar partes específicas da configuração de implantação com os seguintes parâmetros:

  • --mode: defina como syntax-only para não alcançar ambientes de execução remota. O padrão é full.
  • --environment: valida apenas um ambiente específico.
  • --pipeline-paths: lista separada por vírgulas de caminhos para arquivos de definição de pipeline a serem validados.
  • --substitutions e --substitutions-file: substitua parâmetros de configuração de implantação durante a validação.

É possível executar esse comando como uma verificação rápida antes de implantar versões locais do pipeline e como uma ação do GitHub como parte do fluxo de trabalho de CI/CD.

Execute o seguinte comando no repositório para validar os pipelines:

gcloud beta orchestration-pipelines validate

Implantar um pacote de pipeline

Nesta seção, descrevemos diferentes maneiras de implantar seus pipelines.

Orquestração de Pipelines oferece duas maneiras de implantar seus pacotes de pipeline. Essas abordagens foram projetadas para funcionar juntas durante diferentes estágios do fluxo de trabalho de desenvolvimento e lançamento:

  • Implante uma versão do pacote local: implante as versões atuais de recursos e definições de pipeline e a configuração de implantação. O novo ID do pacote será gerado automaticamente com base no nome do espaço de trabalho e no md5 dos arquivos no pacote.

    Esse tipo de implantação é destinado a fins de desenvolvimento. Também recomendamos criar uma configuração de implantação separada que implante os pipelines em um ambiente de execução de teste.

  • Implante as mudanças confirmadas: depois de confirmar mudanças nos recursos, nas definições e na configuração de implantação do pipeline, é possível implantar uma nova versão do pacote no ambiente de execução. O ID do novo pacote será vinculado ao SHA do commit do git no seu repositório.

    Esse tipo de implantação foi projetado para ser executado como parte do CI/CD, por exemplo, por uma ação do GitHub. Também é possível implantar mudanças confirmadas de um repositório Git local.

A Orquestração de Pipelines oferece várias maneiras de substituir parâmetros nos arquivos de definição de pipeline e configuração de implantação, o que pode ser útil ao implantar pipelines para desenvolvimento local e para comandos executados em ações do GitHub. Por exemplo, é possível substituir parâmetros usando o argumento --substitutions em comandos da CLI gcloud, ou definindo uma variável de ambiente ou obtendo o valor dos secrets do GitHub.

Executar comandos de implantação

Local

Para implantar uma versão do pacote 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 \
  --local

O exemplo de saída contém o nome e a versão do pacote de pipeline e o status da implantação:

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

...

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

--- Pipeline Deployment full details ---

...

Comprometido

Para implantar as mudanças, confirme se elas foram enviadas no repositório. Execute o seguinte comando na CLI gcloud:

gcloud beta orchestration-pipelines deploy \
  --environment DEPLOYMENT_ENVIRONMENT

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 nome e a versão do pacote de pipeline e o status da implantação:

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

...

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

--- Pipeline Deployment full details ---

...

Ação do GitHub

O scaffolding do pipeline tem dois exemplos de ações do GitHub que podem ajudar você a começar a implantar e validar seus pipelines usando uma ação do GitHub. Quando você faz upload desses arquivos para o GitHub, seu repositório é configurado com essas ações. Para informações sobre como configurar ações mais complexas do GitHub, consulte Como implantar com o GitHub Actions na documentação do GitHub.

Para usar o exemplo de ações do GitHub:

  1. Crie uma conta de serviço separada que vai executar comandos da CLI gcloud nas ações do GitHub.

  2. Atribua papéis que permitam executar comandos de implantação e validação a essa conta de serviço.

  3. Crie uma chave de conta de serviço para essa conta.

  4. Adicione o secret GCP_SA_KEY ao seu repositório do GitHub e defina o valor dele como a chave da conta de serviço criada. Para mais informações sobre como adicionar secrets, consulte Como usar secrets no GitHub Actions.

Configuração da implantação

Esta seção fornece configurações adicionais que podem ser aplicadas a um ambiente de implantação.

Adicionar ou remover outro pipeline

Para adicionar outro pipeline a um ambiente de implantação atual:

  1. Adicione um arquivo de definição de pipeline e recursos de pipeline ao repositório.
  2. Na configuração de implantação, adicione uma nova chave source com o valor apontando para o novo arquivo de definição de pipeline.

Exemplo:

environments:
  dev:

    ...

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

Para remover um pipeline:

  1. Na configuração da implantação, remova a chave source do pipeline.
  2. Remova o arquivo de definição do pipeline e os recursos do pipeline para o repositório.
  3. Implante a nova versão do pipeline. O pipeline não estará presente na nova versão do pacote.

Adicionar outro ambiente de implantação

Para adicionar outro ambiente de implantação:

  1. Na configuração de implantação, adicione uma nova chave ao mapeamento environments.
  2. Verifique se a configuração de implantação e as definições de pipeline usam variáveis e variáveis de configuração de implantação para executar ações de pipeline que exigem diferenciação entre recursos do Google Cloudque pertencem a cada ambiente.

Exemplo:

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"

Variáveis, secrets e substituição

Depois de definir variáveis na configuração de implantação, você pode usá-las em definições de pipeline e perfis de recursos.

Adicionar variáveis personalizadas

É possível adicionar suas próprias variáveis à chave variables na configuração de implantação:

  1. No ambiente de configuração da implantação, adicione a chave variables.
  2. Adicione um mapeamento de nomes e valores de variáveis.
  3. Para extrair o valor da variável nas definições de pipeline e nos perfis de recursos, coloque o nome da variável entre chaves duplas: {{ example_variable }}.

O exemplo a seguir define as mesmas variáveis em dois ambientes de implantação.

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

Confira a seguir um perfil de recurso do Serviço Gerenciado para Apache Spark que lê essas variáveis. As ações no arquivo de definição do pipeline (example-pipeline.yaml) podem usar o mesmo perfil de recurso, e não é necessário ajustá-las entre ambientes de produção e desenvolvimento.

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

Acessar parâmetros de configuração de implantação

Alguns parâmetros da configuração de implantação também estão disponíveis como variáveis:

  • project
  • region
  • composer_environment
  • COMMIT_SHA: o SHA do commit atual do repositório Git. É possível usar essa variável, por exemplo, substituindo o valor dela ao implantar uma versão do pacote de pipeline local. Dessa forma, as ações que dependem do valor SHA do commit ainda vão operar no conteúdo correto do arquivo.

No exemplo a seguir, a definição do pipeline define padrões para ações com base nos parâmetros de configuração de implantação project e region.

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

Acessar secrets do GitHub Actions

É possível usar secrets do GitHub nos arquivos de configuração de implantação e definição de pipeline. Quando um pipeline é implantado por uma ação do GitHub, os valores desses secrets são transmitidos para as definições de pipeline e para a configuração de implantação.

Para criar um secret que será acessível durante a implantação:

  1. No GitHub, adicione um secret com o prefixo DEPLOY_VAR_. Exemplo: DEPLOY_VAR_API_KEY.

    Para mais informações sobre como criar segredos, consulte Usar segredos no GitHub Actions na documentação do GitHub.

  2. Adicione a mesma variável de ambiente ao fluxo de trabalho do GitHub. Leia o valor dessa variável dos secrets do GitHub.

    Exemplo:

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

    steps:

    ...

    Para mais informações sobre como adicionar variáveis de ambiente aos fluxos de trabalho, consulte Armazenar informações em variáveis na documentação do GitHub.

  3. Use o nome da variável (sem o prefixo DEPLOY_VAR_) nos arquivos de definição do pipeline e na configuração de implantação. Por exemplo: {{ API_KEY }}.

  4. (Opcional) Para implantar uma versão local de um pipeline que usa secrets do GitHub, você pode substituir as variáveis de ambiente DEPLOY_VAR_* do secret usando parâmetros de linha de comando ou definindo-as no ambiente em que você executa comandos de implantação.

Substituir variáveis por parâmetros de linha de comando

Os comandos de implantação da CLI gcloud são compatíveis com o argumento --substitutions, que pode ser usado para substituir ou definir variáveis para as definições de pipeline e a configuração de implantação.

Para substituir variáveis usando parâmetros de linha de comando, forneça a lista de variáveis e os valores delas na linha de comando:

Exemplo:

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

Como alternativa, você pode armazenar substituições em um arquivo YAML e especificá-lo no argumento --substitutions-file:

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

No arquivo de substituições, forneça um mapeamento de variáveis: 

VARIABLE_NAME_1: value_1
VARIABLE_NAME_2: value_2

É possível usar o nome da variável nos arquivos de definição de pipeline e na configuração de implantação. Exemplo: {{ VARIABLE_NAME_1 }}.

Fornecer e substituir variáveis por variáveis de ambiente

As definições de pipeline e a configuração de implantação podem usar variáveis de ambiente com o prefixo DEPLOY_VAR_.

  1. Defina uma variável de ambiente:

    export DEPLOY_VAR_VARIABLE_NAME_1=value_1

  2. É possível usar o nome da variável (sem o prefixo DEPLOY_VAR_) nos arquivos de definição de pipeline e na configuração de implantação. Por exemplo: {{ VARIABLE_NAME_1 }}.

A seguir