Aprovisiona recursos

En esta página, se explica cómo aprovisionar recursos para tus canalizaciones.

Acerca del aprovisionamiento de recursos en las canalizaciones de organización

Las canalizaciones de organización usan un enfoque de infraestructura como código (IaC) para administrar los recursos deGoogle Cloud que usan tus canalizaciones de datos, lo que brinda los siguientes beneficios:

  • Control de versiones. Los cambios en la infraestructura se registran en Git.
  • Repetibilidad Los entornos se pueden volver a crear de forma confiable.
  • Colaboración Los miembros del equipo pueden revisar las definiciones de infraestructura y contribuir a ellas.
  • Automatización: Se integra en canalizaciones de CI/CD.
  • Opcionalidad y coexistencia: El framework de aprovisionamiento de recursos es opcional. Si ya usas Terraform o otras prácticas establecidas de IaC para el aprovisionamiento de recursos, puedes seguir haciéndolo. Puedes administrar un subconjunto de recursos relevantes para una canalización o aplicación específica, que pueden coexistir con recursos administrados por otras herramientas.

En las Canalizaciones de organización, tu proyecto puede tener uno o más entornos de implementación. La configuración de cada entorno de implementación define cómo se implementan las canalizaciones y los recursos que pertenecen a este entorno. Por ejemplo, puedes tener un entorno de implementación para el desarrollo y otro para la producción.

Ejemplo de una configuración del entorno de implementación. Los recursos aprovisionados se definen en la asignación 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

Cuando implementas tu canalización, Canalizaciones de organización usa un modelo sin estado de "crear o actualizar" para aprovisionar los recursos que definiste:

  • Si se define un recurso, pero no existe, las canalizaciones de organización lo crean.

  • Si existe un recurso, haz lo siguiente:

    • (Predeterminado) Actualiza la configuración del recurso para que coincida con la definición.

    • Si defines este comportamiento en la configuración del recurso, las Canalizaciones de organización pueden ignorar los cambios o volver a crear un recurso.

  • Si borras la definición de un recurso de la configuración, no se borrará el recurso. Este enfoque prioriza la seguridad y evita la pérdida accidental de datos.

  • Si cambias el nombre de un recurso existente, Canalizaciones de organización crea un recurso nuevo con el nombre nuevo y conserva el recurso original.

Comparación entre los recursos aprovisionados y los perfiles de recursos

Los perfiles de recursos son archivos de plantilla que contienen la definición de uno o más recursos deGoogle Cloud . Son diferentes de los recursos aprovisionados y se pueden usar junto con ellos:

  • Con recursos aprovisionados: En lugar de definir la misma configuración de recursos intercalada en cada entorno de desarrollo de tu deployment.yaml, puedes definirla una vez en un perfil y, luego, hacer referencia a ella. Los recursos aprovisionados admiten una amplia variedad de tipos de recursos que se pueden definir en los perfiles de recursos.

  • Con acciones de canalización: Puedes usar perfiles de recursos en acciones en las que se aprovisionan recursos durante la duración de una acción. Si usas un perfil de recursos en lugar de especificar la configuración del recurso de forma intercalada, puedes mantener la configuración del recurso separada de la acción de la canalización y reutilizar una configuración para varias acciones de la canalización. Las acciones de canalización admiten perfiles de recursos solo para los recursos de Managed Service para Apache Spark, por ejemplo, cuando se ejecutan acciones de canalización en un clúster efímero.

Consulta los tipos de recursos disponibles

Consulta Tipos de recursos.

También puedes ver todos los recursos disponibles en gcloud CLI con el siguiente comando:

gcloud beta orchestration-pipelines resource-types list

Cómo agregar un recurso nuevo

Para agregar un recurso aprovisionado nuevo a la configuración del entorno de implementación, agrega su definición de la siguiente manera:

  1. En la configuración de tu entorno de implementación, agrega un elemento nuevo a la lista environments.DEVELOPMENT_ENVIRONMENT.resources.

  2. Especifica las siguientes claves:

    • type: Es el tipo de recurso de Google Cloud que se aprovisionará. Ejemplos: bigquery.dataset, dataform.repository. Puedes ver los tipos de recursos disponibles con un comando de la gcloud CLI.

    • name: Es un nombre lógico para el recurso dentro del archivo deployment.yaml.

    • parent: Especifica un recurso principal para los tipos de recursos que requieren uno. Coloca el name del recurso principal como valor.

    • updateAction: Especifica qué acción se debe realizar cuando se detecta un cambio en la configuración del recurso:

      • (Predeterminado) patch: Actualiza las propiedades del recurso que cambiaron.

        La operación de actualización solo modifica las propiedades especificadas en la configuración (YAML) del recurso, y deja sin cambios otras propiedades existentes. Puedes usar este comportamiento, por ejemplo, para administrar solo las propiedades importantes para la ejecución de la canalización y mantener otras propiedades configuradas de forma manual.

        Si los cambios afectan campos inmutables o el recurso es inmutable, la implementación falla. En esos casos, recomendamos ajustar la definición para que solo se modifiquen los campos mutables. Si esto no es posible, puedes cambiar la acción de actualización a recreate.

      • skip: Ignora los cambios y no actualiza la configuración del recurso.

        Te recomendamos que uses esta opción cuando quieras administrar la existencia del recurso, pero realizar los cambios y las actualizaciones de configuración por otros medios, por ejemplo, de forma manual.

      • recreate: Si se detectan cambios, borra el recurso existente y, luego, crea uno nuevo basado en la definición del recurso actual.

        Recomendamos usar esta opción para los recursos que son completamente inmutables o cuando se realizan cambios en campos que no se pueden actualizar de forma local.

    • definition: Es la especificación del recurso, como una asignación que refleja la estructura de configuración del recurso en la API del recurso.

    • (Opcional) metadata: Metadatos específicos de las canalizaciones de orquestación. Algunos tipos de recursos usan campos de metadatos para configurar el recurso enGoogle Cloud . Por ejemplo, el campo metadata.location se puede usar para crear recursos zonales.

  3. Valida e implementa tu canalización. Las Canalizaciones de organización aprovisionarán el recurso nuevo cuando se implemente la canalización.

Ejemplo: Recursos de larga duración

En este ejemplo, se muestra cómo agregar un recurso de larga duración, en este caso, un clúster estático de Managed Service para Apache Spark. Una vez aprovisionado, se puede usar en acciones de canalización. Te recomendamos que uses este enfoque general cuando tus canalizaciones usen recursos persistentes.

En el siguiente ejemplo, se agrega un clúster estático de Managed Service para Apache Spark llamado example-static-cluster al entorno de implementación dev. La definición del recurso se proporciona según la API de 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

Este clúster se puede usar en las acciones de la canalización como de costumbre. No hay diferencias en el uso en comparación con, por ejemplo, un clúster creado 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"

Ejemplo: Proceso automatizado de compilación y lanzamiento para Dataform

En este ejemplo, se muestra un proceso automatizado de compilación y lanzamiento para Dataform. En la situación de ejemplo, ocurre lo siguiente:

  1. Un repositorio de Dataform está conectado a un repositorio de GitHub a través de Developer Connect.

  2. Envías los cambios al repositorio de GitHub.

  3. Después de enviar los cambios, implementa la canalización.

  4. Dataform extrae el código del repositorio de GitHub, crea un resultado de compilación y lo prepara para la ejecución.

  5. Luego, se usa una configuración de flujo de trabajo para ejecutar flujos de trabajo con esta versión compilada automáticamente.

En el siguiente ejemplo de código, se definen un repositorio de Dataform, una configuración de versión y una configuración de flujo de trabajo para él en el entorno de implementación dev:

  • La línea gitCommitish: "{{ COMMIT_SHA }}" vincula la configuración de la versión a la confirmación de Git específica que se implementa. COMMIT_SHA es una variable que se resuelve en el SHA de la confirmación del paquete de la canalización implementada.
  • La clave codeCompilationConfig.pipelineConfig.path apunta a una subcarpeta que contiene recursos de la canalización. De esta manera, puedes mantener varias canalizaciones de Dataform en un solo repositorio.

  • Establecer releaseCompilationResult en auto en la definición de releaseConfig indica a Canalizaciones de organización que active una compilación de Dataform después de que se cree o actualice el recurso releaseConfig con el nuevo gitCommitish:

    1. Primero, el framework inserta o actualiza el recurso releaseConfig para que apunte a la confirmación especificada.
    2. Luego, debido al parámetro de configuración auto, llama a la API de Dataform para crear un nuevo resultado de compilación basado en el código de esa confirmación.
    3. El releaseConfig se vuelve a actualizar para que apunte al ID del resultado de compilación recién creado, lo que convierte a esa versión en la "activa".
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 ejemplo de acción de canalización que ejecuta un flujo de trabajo con la configuración de flujo de trabajo creada:

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