Provisionar recursos

Nesta página, explicamos como provisionar recursos para seus pipelines.

Sobre o provisionamento de recursos em Orquestração de Pipelines

A Orquestração de Pipelines usa uma abordagem de infraestrutura como código (IaC) para gerenciar Google Cloud os recursos usados pelos pipelines de dados, o que traz os seguintes benefícios:

  • Controle de versão. As mudanças de infraestrutura são rastreadas no Git.
  • Repetibilidade. Os ambientes podem ser recriados de forma confiável.
  • Colaboração. Os membros da equipe podem revisar e contribuir para as definições de infraestrutura.
  • Automation. Integra-se aos pipelines de CI/CD.
  • Opcionalidade e coexistência. A estrutura de provisionamento de recursos é opcional. Se você já usa o Terraform ou outras práticas de IaC estabelecidas para provisionamento de recursos, pode continuar fazendo isso. É possível gerenciar um subconjunto de recursos relevantes para um pipeline ou aplicativo específico, que podem coexistir com recursos gerenciados por outras ferramentas.

Em Orquestração de Pipelines, 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, você pode ter um ambiente de implantação para desenvolvimento e outro para produção.

Exemplo de configuração de ambiente de implantação. Os recursos provisionados são definidos no mapeamento resources.

environments:
  dev:
    project: example-dev-project
    region: us-central1
    variables:
      dataset_name: marketing_analytics_dev
    secrets:
      dts_api_key: "projects/example-dev-project/secrets/dev-dts-key/versions/latest"
    resources:
      - type: dataproc.cluster
        name: example-static-cluster-resource
        definition:
          clusterName: example-static-cluster

Ao implantar o pipeline, a Orquestração de Pipelines usa um modelo "criar ou atualizar" sem estado para provisionar os recursos definidos:

  • Se um recurso for definido, mas não existir, a Orquestração de Pipelines o criará.

  • Se um recurso existir:

    • (Padrão) Atualize a configuração do recurso para corresponder à definição.

    • Se você definir esse comportamento na configuração do recurso, a Orquestração de Pipelines poderá ignorar as mudanças ou recriar um recurso.

  • Se você excluir a definição de um recurso da configuração, isso não resultará na exclusão do recurso. Essa abordagem prioriza a segurança e evita a perda acidental de dados.

  • Se você renomear um recurso atual, a Orquestração de Pipelines criará um novo recurso com o novo nome e manterá o recurso original.

Recursos provisionados em comparação com perfis de recursos

Os perfis de recursos são arquivos de modelo que contêm a definição de um ou mais Google Cloud recursos. Eles são diferentes dos recursos provisionados e podem ser usados juntos:

  • Com recursos provisionados: em vez de definir a mesma configuração de recurso inline em cada ambiente de desenvolvimento no deployment.yaml, você pode defini-la uma vez em um perfil e fazer referência a ela. Os recursos provisionados oferecem suporte a uma ampla variedade de tipos de recursos que podem ser definidos em perfis de recursos.

  • Com ações de pipeline: é possível usar perfis de recursos em ações em que os recursos são provisionados durante uma ação. Ao usar um perfil de recurso em vez de especificar a configuração do recurso inline, você pode manter a configuração do recurso separada da ação do pipeline e reutilizar uma configuração para várias ações de pipeline. As ações de pipeline oferecem suporte a perfis de recursos apenas para recursos do Serviço Gerenciado para Apache Spark, por exemplo, ao executar ações de pipeline em um cluster efêmero.

Conferir os tipos de recursos disponíveis

Consulte Tipos de recursos.

Também é possível conferir todos os recursos disponíveis na CLI gcloud com o seguinte comando:

gcloud beta orchestration-pipelines resource-types list

Adicionar um novo recurso

Para adicionar um novo recurso provisionado à configuração do ambiente de implantação, adicione a definição da seguinte maneira:

  1. Na configuração do ambiente de implantação, adicione um novo item à environments.DEVELOPMENT_ENVIRONMENT.resources lista.

  2. Especifique as seguintes chaves:

    • type: o tipo de Google Cloud recurso a ser provisionado. Exemplos: bigquery.dataset, dataform.repository. É possível conferir os tipos de recursos disponíveis usando um comando da CLI gcloud.

    • name: um nome lógico para o recurso no arquivo deployment.yaml.

    • parent: especifica um recurso pai para tipos de recursos que exigem um. Coloque o name do recurso pai como o valor.

    • updateAction: especifica qual ação precisa ser realizada quando uma mudança é detectada na configuração do recurso:

      • (Padrão) patch: atualiza as propriedades do recurso que foram alteradas.

        A operação de atualização modifica apenas as propriedades especificadas na configuração do recurso (YAML), deixando outras propriedades inalteradas. É possível usar esse comportamento, por exemplo, para gerenciar apenas as propriedades importantes para a execução do pipeline e manter outras propriedades configuradas manualmente.

        Se as mudanças afetarem campos imutáveis ou o recurso for imutável, a implantação falhará. Nesses casos, recomendamos ajustar a definição para modificar apenas campos mutáveis. Se isso não for possível, mude a ação de atualização para recreate.

      • skip: ignora as mudanças e não atualiza a configuração do recurso.

        Recomendamos usar essa opção quando você quiser gerenciar a existência do recurso, mas realizar as mudanças e atualizações de configuração usando outros meios, por exemplo, manualmente.

      • recreate: se alguma mudança for detectada, exclua o recurso atual e crie um novo com base na definição do recurso atual.

        Recomendamos usar essa opção para recursos totalmente imutáveis ou quando as mudanças são feitas em campos que não podem ser atualizados no local.

    • definition: especificação do recurso, como um mapeamento que reflete a estrutura de configuração do recurso na API dele.

    • (Opcional) metadata: metadados específicos dos pipelines de orquestração. Alguns tipos de recursos usam campos de metadados para configurar o recurso em Google Cloud Por exemplo, o metadata.location campo pode ser usado para criar recursos zonais.

  3. Valide e implante o pipeline. Orquestração de Pipelines vai provisionar o novo recurso quando o pipeline for implantado.

Exemplo: recursos de longa duração

Este exemplo demonstra como adicionar um recurso de longa duração, nesse caso, um cluster estático do Serviço Gerenciado para Apache Spark. Depois de provisionado, ele pode ser usado em ações de pipeline. Recomendamos usar essa abordagem geral quando os pipelines usam recursos permanentes.

O exemplo a seguir adiciona um cluster estático do Serviço Gerenciado para Apache Spark chamado example-static-cluster ao ambiente de implantação dev. A definição do recurso é fornecida com base na API Dataproc.

environments:
  dev:
    project: "example-project"
    region: "us-central1"
    # A runner environment for executing pipeline actions
    composer_environment: "example-runner-environment"

    resources:
      - type: dataproc.cluster
        name: example-static-cluster
        updateAction: patch
        definition:
          config:
            masterConfig:
              numInstances: 1
              machineTypeUri: n1-standard-4
            workerConfig:
              numInstances: 3
              machineTypeUri: n1-standard-4

Esse cluster pode ser usado em ações de pipeline normalmente. Não há diferença no uso em comparação com, por exemplo, um cluster criado manualmente.

modelVersion: "1.0"
pipelineId: "example-dataproc-pipeline"
...
actions:
  - pyspark:
      name: "run-pyspark-with-pyfiles-on-existing-cluster"
      engine:
        dataprocOnGce:
          existingCluster:
            clusterName: "example-static-cluster"
            location: {{ region }}
            projectId: {{ project }}
      mainFilePath: "scripts/my_spark_job_with_pyfiles.py"
      pyFiles:
        - "scripts/lib1.py"

Exemplo: processo automatizado de build e lançamento para o Dataform

Este exemplo demonstra um processo automatizado de build e lançamento para o Dataform. No cenário de exemplo:

  1. Um repositório do Dataform é conectado a um repositório do GitHub pelo Developer Connect.

  2. Você envia as mudanças para o repositório do GitHub.

  3. Depois que as mudanças são enviadas, você implanta o pipeline.

  4. O Dataform extrai o código do repositório do GitHub, cria um resultado de compilação e o prepara para execução.

  5. Uma configuração de fluxo de trabalho é usada para executar fluxos de trabalho com essa versão compilada automaticamente.

O exemplo de código a seguir define um repositório do Dataform, uma configuração de lançamento e uma configuração de fluxo de trabalho para ele no ambiente de implantação dev:

  • A linha gitCommitish: "{{ COMMIT_SHA }}" vincula a configuração de lançamento ao commit específico do Git que está sendo implantado. O COMMIT_SHA é uma variável que é resolvida para o SHA de commit do pacote de pipeline implantado.
  • A chave codeCompilationConfig.pipelineConfig.path aponta para uma subpasta que contém recursos de pipeline. Dessa forma, é possível manter vários pipelines do Dataform em um único repositório.

  • Definir releaseCompilationResult como auto na definição do releaseConfig instrui a Orquestração de Pipelines a acionar uma compilação do Dataform depois que o recurso releaseConfig for criado ou atualizado com o novo gitCommitish:

    1. A estrutura primeiro upserta (atualiza ou cria) o releaseConfig recurso para apontar para o commit especificado.
    2. Em seguida, devido à configuração auto, ele chama a API Dataform para criar um novo resultado de compilação com base no código nesse commit.
    3. O releaseConfig é atualizado novamente para apontar para o ID do resultado de compilação recém-criado, tornando essa versão a "ativa".
environments:
  dev:
    project: example-project
    region: us-central1
    composer_environment: example-runner-environment
    artifact_storage:
      bucket: example-bucket
      path_prefix: initialized-artifact-bucket
    pipelines:
      - source: initialized-pipeline.yaml
      - source: dataform_local_pipeline.yaml
      - source: dataform_service_pipeline.yaml
    resources:
      - name: {{ repository_name }}
        type: dataform.repository
        definition:
          labels:
            bigquery-deployment: preview
      - type: dataform.repository.releaseConfig
        name: subfolder-release
        parent: {{ repository_name }}
        definition:
          gitCommitish: {{ COMMIT_SHA }}
          releaseCompilationResult: auto
          codeCompilationConfig:
            pipelineConfig:
              pipelineType: DATAFORM
              path: weather_dataform
      - type: dataform.repository.workflowConfig
        name: {{ workflow_config_name }}
        parent: {{ repository_name }}
        definition:
          releaseConfig: subfolder-release
          invocationConfig:
            serviceAccount: {{ service_account }}
    variables:
      service_account: example-account@example-project.iam.gserviceaccount.com
      network_uri: projects/example-project/global/networks/default
      subnetwork_uri: projects/example-project/regions/us-central1/subnetworks/default
      region: us-central1
      repository_name: weather-aggregation-repo
      workflow_config_name: updated-subfolder-workflow

Um exemplo de ação de pipeline que executa um fluxo de trabalho com a configuração de fluxo de trabalho criada:

modelVersion: '1.0'
pipelineId: dataform_service_pipeline
description: Updated run Dataform pipeline via Dataform Service
runner: airflow
owner: data-eng-team

defaults:
  projectId: {{ project }}
  location: {{ region }}
  executionConfig:
    retries: 1

actions:
  - pipeline:
      name: run_dataform_service
      framework:
        dataform:
          dataformService:
            location: {{ region }}
            projectId: {{ project }}
            repositoryId: {{ repository_name }}
            workflowInvocation:
              workflowConfig: projects/{{ project }}/locations/{{ region }}/repositories/{{
                repository_name }}/workflowConfigs/{{ workflow_config_name }}
  - python:
      name: fibonacci_python
      mainFilePath: scripts/fibonacci.py
      pythonCallable: fibonacciTen
      engine:
        local: {}
  - sql:
      name: dummy_bq_query
      engine:
        bigquery:
          location: {{ region }}
      query:
        inline: 'SELECT COUNT(*) FROM `{{ project }}.weather_data.sensor_readings`'
tags:
  - job:datacloud:vscode