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 recursosGoogle Cloud usados pelos seus pipelines de dados, o que traz os seguintes benefícios:

  • Controle de versão. As mudanças na infraestrutura são rastreadas no Git.
  • Repetibilidade: os ambientes podem ser recriados de maneira confiável.
  • Colaboração. Os participantes da equipe podem revisar e contribuir com as definições de infraestrutura.
  • Automation. Integração aos pipelines de CI/CD.
  • Opcionalidade e coexistência: o framework 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, coexistindo potencialmente 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 ele são implantados. Por exemplo, você pode ter um ambiente de implantação para desenvolvimento e outro para produção.

Exemplo de uma 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, o Orquestração de Pipelines usa um modelo sem estado de "criar ou atualizar" 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) Atualiza 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 vai resultar na exclusão do recurso. Essa abordagem prioriza a segurança e evita a perda acidental de dados.

  • Se você renomear um recurso existente, a Orquestração de Pipelines cria um novo recurso com o novo nome e mantém 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 recursos doGoogle Cloud . Eles são diferentes dos recursos provisionados e podem ser usados em conjunto com eles:

  • Com recursos provisionados: em vez de definir a mesma configuração de recurso inline em cada ambiente de desenvolvimento no deployment.yaml, é possível definir uma vez em um perfil e fazer referência a ele. 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 a ação. Ao usar um perfil de recurso em vez de especificar a configuração do recurso inline, é possível manter a configuração separada da ação do pipeline e reutilizar uma configuração para várias ações de pipeline. As ações de pipeline só aceitam perfis de recursos para recursos do Serviço Gerenciado para Apache Spark, por exemplo, ao executar ações de pipeline em um cluster efêmero.

Ver 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 comando a seguir:

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 dele da seguinte maneira:

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

  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 deve ser tomada quando uma mudança é detectada na configuração do recurso:

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

        A operação de atualização só modifica as propriedades especificadas na configuração (YAML) do recurso, deixando outras propriedades inalteradas. Você pode 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 vai 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 forem detectadas mudanças, 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 emGoogle Cloud . Por exemplo, o campo metadata.location pode ser usado para criar recursos zonais.

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

Exemplo: recursos de longa duração

Este exemplo demonstra a adição de um recurso de longa duração, neste 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 seus pipelines utilizam recursos persistentes.

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 exemplo de cenário:

  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 forem enviadas, implante o pipeline.

  4. O Dataform extrai o código do repositório do GitHub, cria um resultado de compilação e o deixa pronto 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. COMMIT_SHA é uma variável que é resolvida para o SHA do commit do pacote de pipeline implantado.
  • A chave codeCompilationConfig.pipelineConfig.path aponta para uma subpasta que contém recursos de pipeline. Assim, é 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 é criado ou atualizado com o novo gitCommitish:

    1. O framework primeiro faz um upsert (atualiza ou cria) o recurso releaseConfig 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 desse commit.
    3. O releaseConfig é atualizado novamente para apontar para o ID do resultado da 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 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