Eseguire il provisioning delle risorse

Questa pagina spiega come eseguire il provisioning delle risorse per le pipeline.

Informazioni sul provisioning delle risorse in Orchestration Pipelines

Orchestration Pipelines utilizza un approccio Infrastructure-as-Code (IaC) per gestire Google Cloud le risorse utilizzate dalle pipeline di dati, il che comporta i seguenti vantaggi:

  • Controllo della versione. Le modifiche all'infrastruttura vengono monitorate in Git.
  • Ripetibilità. È possibile ricreare gli ambienti in modo affidabile.
  • Collaborazione. I membri del team possono esaminare e contribuire alle definizioni dell'infrastruttura.
  • Automation. Si integra nelle pipeline CI/CD.
  • Opzionalità e coesistenza. Il framework di provisioning delle risorse è facoltativo. Se utilizzi già Terraform o altre pratiche IaC consolidate per il provisioning delle risorse, puoi continuare a farlo. Puoi gestire un sottoinsieme di risorse pertinenti a una pipeline o un'applicazione specifica, potenzialmente coesistenti con le risorse gestite da altri strumenti.

In Orchestration Pipelines, il progetto può avere uno o più ambienti di deployment. La configurazione di ogni ambiente di deployment definisce la modalità di deployment delle pipeline e delle risorse appartenenti a questo ambiente. Ad esempio, puoi avere un ambiente di deployment per lo sviluppo e un altro per la produzione.

Esempio di configurazione di un ambiente di deployment. Le risorse di cui è stato eseguito il provisioning sono definite nel mapping 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

Quando esegui il deployment della pipeline, Orchestration Pipelines utilizza un modello "crea o aggiorna" senza stato per eseguire il provisioning delle risorse che hai definito:

  • Se una risorsa è definita ma non esiste, Orchestration Pipelines la crea.

  • Se una risorsa esiste:

    • (Impostazione predefinita) Aggiorna la configurazione della risorsa in modo che corrisponda alla definizione.

    • Se definisci questo comportamento nella configurazione della risorsa, Orchestration Pipelines può ignorare le modifiche o ricreare una risorsa.

  • Se elimini la definizione di una risorsa dalla configurazione, la risorsa non viene eliminata. Questo approccio dà la priorità alla sicurezza e impedisce la perdita accidentale di dati.

  • Se rinomini una risorsa esistente, Orchestration Pipelines crea una nuova risorsa con il nuovo nome e mantiene la risorsa originale.

Risorse di cui è stato eseguito il provisioning rispetto ai profili delle risorse

I profili delle risorse sono file di modelli che contengono la definizione di una o più Google Cloud risorse. Sono diversi dalle risorse di cui è stato eseguito il provisioning e possono essere utilizzati insieme:

  • Con le risorse di cui è stato eseguito il provisioning: anziché definire la stessa configurazione delle risorse in linea all'interno di ogni ambiente di sviluppo in deployment.yaml, puoi definirla una volta in un profilo e poi farvi riferimento. Le risorse di cui è stato eseguito il provisioning supportano un'ampia gamma di tipi di risorse che possono essere definiti nei profili delle risorse.

  • Con le azioni della pipeline: puoi utilizzare i profili delle risorse nelle azioni in cui viene eseguito il provisioning delle risorse per la durata di un'azione. Utilizzando un profilo di risorse anziché specificare la configurazione della risorsa in linea, puoi mantenere la configurazione della risorsa separata dall'azione della pipeline e riutilizzare una configurazione per più azioni della pipeline. Le azioni della pipeline supportano i profili delle risorse solo per le risorse Managed Service for Apache Spark, ad esempio quando si eseguono azioni della pipeline in un cluster temporaneo.

Visualizzare i tipi di risorse disponibili

Consulta Tipi di risorse.

Puoi anche visualizzare tutte le risorse disponibili in gcloud CLI con il seguente comando:

gcloud beta orchestration-pipelines resource-types list

Aggiungere una nuova risorsa

Per aggiungere una nuova risorsa di cui è stato eseguito il provisioning alla configurazione dell'ambiente di deployment, aggiungi la relativa definizione come segue:

  1. Nella configurazione dell'ambiente di deployment, aggiungi un nuovo elemento all'elenco environments.DEVELOPMENT_ENVIRONMENT.resources.

  2. Specifica le seguenti chiavi:

    • type: il tipo di risorsa di cui eseguire il provisioning. Google Cloud Esempi: bigquery.dataset, dataform.repository. Puoi visualizzare i tipi di risorse disponibili utilizzando un comando gcloud CLI.

    • name: un nome logico per la risorsa all'interno del file deployment.yaml.

    • parent: specifica una risorsa padre per i tipi di risorse che ne richiedono una. Inserisci il name della risorsa padre come valore.

    • updateAction: specifica l'azione da intraprendere quando viene rilevata una modifica nella configurazione della risorsa:

      • (Impostazione predefinita) patch: aggiorna le proprietà della risorsa che sono state modificate.

        L'operazione di aggiornamento modifica solo le proprietà specificate nella configurazione della risorsa (YAML), lasciando invariate le altre proprietà esistenti. Puoi utilizzare questo comportamento, ad esempio, per gestire solo le proprietà importanti per l'esecuzione della pipeline e mantenere le altre proprietà configurate manualmente.

        Se le modifiche interessano campi non modificabili o la risorsa non è modificabile, il deployment non va a buon fine. In questi casi, ti consigliamo di modificare la definizione in modo da modificare solo i campi modificabili. Se non è possibile, puoi modificare l'azione di aggiornamento in recreate.

      • skip: ignora le modifiche e non aggiorna la configurazione della risorsa.

        Ti consigliamo di utilizzare questa opzione quando vuoi gestire l'esistenza della risorsa, ma eseguire le modifiche e gli aggiornamenti della configurazione utilizzando altri mezzi, ad esempio manualmente.

      • recreate: se vengono rilevate modifiche, elimina la risorsa esistente e poi creane una nuova in base alla definizione della risorsa corrente.

        Ti consigliamo di utilizzare questa opzione per le risorse completamente non modificabili o quando vengono apportate modifiche a campi che non possono essere aggiornati in loco.

    • definition: la specifica della risorsa, come mapping che riflette la struttura di configurazione della risorsa nell'API della risorsa.

    • (Facoltativo) metadata: metadati specifici di Orchestration Pipelines. Alcuni tipi di risorse utilizzano i campi dei metadati per configurare la risorsa in Google Cloud Ad esempio, il campo metadata.location può essere utilizzato per creare risorse zonali.

  3. Convalida ed esegui il deployment della pipeline. Orchestration Pipelines eseguirà il provisioning della nuova risorsa al momento del deployment della pipeline.

Esempio: risorse a lunga esecuzione

Questo esempio mostra come aggiungere una risorsa a lunga esecuzione, in questo caso un cluster Managed Service for Apache Spark statico. Una volta eseguito il provisioning, può essere utilizzato nelle azioni della pipeline. Ti consigliamo di utilizzare questo approccio generale quando le pipeline utilizzano risorse permanenti.

L'esempio seguente aggiunge un cluster Managed Service for Apache Spark statico denominato example-static-cluster all'ambiente di deployment dev. La definizione della risorsa viene fornita in base all'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

Questo cluster può essere utilizzato nelle azioni della pipeline come di consueto. Non c'è alcuna differenza nell'utilizzo rispetto, ad esempio, a un cluster creato 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"

Esempio: processo di build e rilascio automatico per Dataform

Questo esempio mostra un processo di build e rilascio automatico per Dataform. Nello scenario di esempio:

  1. Un repository Dataform è connesso a un repository GitHub tramite Developer Connect.

  2. Esegui il push delle modifiche nel repository GitHub.

  3. Dopo aver eseguito il push delle modifiche, esegui il deployment della pipeline.

  4. Dataform esegue il pull del codice dal repository GitHub, crea un risultato di compilazione e lo prepara per l'esecuzione.

  5. Viene quindi utilizzata una configurazione del flusso di lavoro per eseguire i flussi di lavoro con questa release compilata automaticamente.

L'esempio di codice seguente definisce un repository Dataform, una configurazione di release e una configurazione del flusso di lavoro per quest'ultimo nell'ambiente di deployment dev:

  • La riga gitCommitish: "{{ COMMIT_SHA }}" collega la configurazione della release al commit Git specifico di cui è stato eseguito il deployment. Il COMMIT_SHA è una variabile che viene risolta nell'SHA del commit del bundle della pipeline di cui è stato eseguito il deployment.
  • La chiave codeCompilationConfig.pipelineConfig.path rimanda a una sottocartella che contiene gli asset della pipeline. In questo modo, puoi conservare più pipeline Dataform in un singolo repository.

  • Se imposti releaseCompilationResult su auto nella definizione di releaseConfig, Orchestration Pipelines attiva una compilazione Dataform dopo la creazione o l'aggiornamento della risorsa releaseConfig con il nuovo gitCommitish:

    1. Il framework esegue prima l'upsert (aggiorna o crea) della risorsa releaseConfig in modo che rimandi al commit specificato.
    2. Poi, a causa dell'impostazione auto, chiama l'API Dataform per creare un nuovo risultato di compilazione in base al codice del commit.
    3. La releaseConfig viene aggiornata di nuovo in modo che rimandi all'ID del risultato di compilazione appena creato, rendendo questa versione quella "live".
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

Un esempio di azione della pipeline che esegue un flusso di lavoro con la configurazione del flusso di lavoro creata:

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