佈建資源

本頁說明如何為管道佈建資源。

關於 Orchestration Pipelines 中的資源佈建

自動化調度管道會採用基礎架構即程式碼 (IaC) 方法，管理資料管道使用的資源，可帶來下列優點：Google Cloud

  • 版本管控。基礎架構變更會透過 Git 追蹤。
  • 重複性。環境可以穩定地重新建立。
  • 協作：團隊成員可以審查及貢獻基礎架構定義。
  • 自動化：整合至 CI/CD 管道。
  • 選用性和共存性。資源佈建架構為選用項目。如果您已使用 Terraform 或其他成熟的 IaC 做法來佈建資源，可以繼續使用。您可以管理與特定管道或應用程式相關的資源子集，這些資源可能會與其他工具管理的資源共存。

在 Orchestration Pipelines 中，專案可有一或多個部署環境。每個部署環境的設定會定義如何部署屬於該環境的管道和資源。舉例來說，您可以為開發作業建立一個部署環境，並為實際工作環境建立另一個環境。

部署環境設定範例。佈建的資源定義於 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

部署管道時，Orchestration Pipelines 會使用無狀態的「建立或更新」模型，佈建您定義的資源：

  • 如果定義了資源，但該資源不存在，Orchestration Pipelines 會建立該資源。

  • 如果資源存在：

    • (預設) 更新資源的設定，使其符合定義。

    • 如果您在資源的設定中定義這項行為，Orchestration Pipelines 可以忽略變更或重新建立資源。

  • 從設定中刪除資源定義不會導致資源遭到刪除。這種做法以安全性為優先考量，可防止資料意外遺失。

  • 如果重新命名現有資源，Orchestration Pipelines 會建立新資源並使用新名稱，同時保留原始資源。

與資源設定檔相比，已佈建的資源

資源設定檔是範本檔案，內含一或多個Google Cloud 資源的定義。這類檔案與佈建的資源不同，但可以搭配使用：

  • 使用已佈建的資源：您不必在 deployment.yaml 的每個開發環境中，內嵌定義相同的資源設定，只要在設定檔中定義一次，然後參照即可。佈建的資源支援多種資源類型，可在資源設定檔中定義。

  • 使用管道動作：您可以在動作中使用資源設定檔，在動作期間佈建資源。使用資源設定檔而非內嵌指定資源設定，可將資源設定與管道動作分開，並為多個管道動作重複使用一項設定。管道動作僅支援 Managed Service for Apache Spark 資源的資源設定檔，例如在暫時性叢集中執行管道動作時。

查看可用的資源類型

請參閱「資源類型」。

您也可以使用下列指令，在 gcloud CLI 中查看所有可用資源：

gcloud beta orchestration-pipelines resource-types list

新增資源

如要在部署環境的設定中新增已佈建的資源，請按照下列方式新增定義：

  1. 在部署環境的設定中，將新項目新增至 environments.DEVELOPMENT_ENVIRONMENT.resources 清單。

  2. 指定下列鍵：

    • type：要佈建的 Google Cloud 資源類型。例如：bigquery.dataset、dataform.repository。您可以使用 gcloud CLI 指令查看可用的資源類型。

    • name：deployment.yaml 檔案中資源的邏輯名稱。

    • parent：指定需要父項資源的資源類型。請將父項資源的 name 設為值。

    • updateAction：指定偵測到資源設定變更時，必須採取哪項動作：

      • (預設) patch：更新已變更的資源屬性。

        更新作業只會修改資源設定 (YAML) 中指定的屬性，其他現有屬性則維持不變。舉例來說，您可以利用這項功能，只管理對管道執行作業而言重要的屬性，並保留手動設定的其他屬性。

        如果變更會影響不可變更的欄位，或資源不可變更，部署作業就會失敗。在這種情況下，建議您調整定義，只修改可變動的欄位。如果無法這麼做，可以將更新動作變更為 recreate。

      • skip：忽略變更，且不更新資源的設定。

        如果您想管理資源的存在狀態，但要使用其他方式 (例如手動) 進行設定變更和更新，建議使用這個選項。

      • recreate：如果偵測到任何變更，請刪除現有資源，然後根據目前資源的定義建立新資源。

        如果資源完全無法變更，或是變更的欄位無法就地更新，建議使用這個選項。

    • definition：資源規格，以對應形式反映資源 API 中的資源設定結構。

    • (選用) metadata：Orchestration Pipelines 專屬中繼資料。部分資源類型會使用中繼資料欄位，在Google Cloud 中設定資源。舉例來說，metadata.location 欄位可用於建立區域資源。

  3. 驗證及部署管道。部署管道時，Orchestration Pipelines 會佈建新資源。

範例：長時間執行的資源

這個範例說明如何新增長期執行的資源，在本例中為靜態 Managed Service for Apache Spark 叢集。佈建完成後，即可在管道動作中使用。如果管道使用持續性資源，建議採用這種一般做法。

以下範例會將名為 example-static-cluster 的靜態 Managed Service for Apache Spark 叢集新增至 dev 部署環境。資源定義是根據 Dataproc API 提供。

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

這個叢集可照常用於管道動作。與手動建立的叢集相比，使用量沒有差異。

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"

範例：Dataform 的自動建構和發布程序

這個範例示範 Dataform 的自動建構和發布程序。範例情境如下：

  1. Dataform 存放區透過 Developer Connect 連結至 GitHub 存放區。

  2. 將變更推送至 GitHub 存放區。

  3. 推送變更後，您就可以部署管道。

  4. Dataform 會從 GitHub 存放區提取程式碼、建立編譯結果，並準備執行。

  5. 然後使用工作流程設定，透過這個自動編譯的版本執行工作流程。

下列程式碼範例會在 dev 部署環境中，為 Dataform 存放區定義發布設定和工作流程設定：

  • gitCommitish: "{{ COMMIT_SHA }}" 行會將發布設定繫結至要部署的特定 Git 修訂版本。COMMIT_SHA 是 變數，會解析為已部署管道套件的修訂版本 SHA。
  • codeCompilationConfig.pipelineConfig.path 鍵會指向包含管道資產的子資料夾。這樣一來，您就能在單一存放區中保留多個 Dataform 管道。

  • 在 releaseConfig 的定義中將 releaseCompilationResult 設為 auto，會指示 Orchestration Pipelines 在建立或更新 releaseConfig 資源時，以新的 gitCommitish 觸發 Dataform 編譯：

    1. 架構會先 upsert (更新或建立) releaseConfig 資源，指向指定的提交。
    2. 然後，由於 auto 設定，系統會呼叫 Dataform API，根據該提交內容的程式碼建立新的編譯結果。
    3. releaseConfig 會再次更新，指向新建立的編譯結果 ID，讓該版本成為「正式」版本。
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

以下是管道動作範例，可使用建立的工作流程設定執行工作流程：

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