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 Google Cloud recursos que usan tus canalizaciones de datos, lo que brinda los siguientes beneficios:

  • Control de versiones. Se hace un seguimiento de los cambios en la infraestructura 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 las canalizaciones de CI/CD.
  • Opcionalidad y coexistencia. El framework de aprovisionamiento de recursos es opcional. Si ya usas Terraform o otras prácticas de IaC establecidas 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 de 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, las canalizaciones de organización usan un modelo "crear o actualizar" sin estado 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, sucede 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 borra el recurso. Este enfoque prioriza la seguridad y evita la pérdida accidental de datos.

  • Si cambias el nombre de un recurso existente, las canalizaciones de organización crean un recurso nuevo con el nombre nuevo y conservan el recurso original.

Recursos aprovisionados en comparación con los perfiles de recursos

Los perfiles de recursos son archivos de plantilla que contienen la definición de uno o más Google Cloud recursos. 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 en línea dentro de cada entorno de desarrollo en 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 en línea, puedes mantener la configuración del recurso separada de la acción de canalización y volver a usar una configuración para varias acciones de 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

Agrega 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 environments.DEVELOPMENT_ENVIRONMENT.resources lista.

  2. Especifica las siguientes claves:

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

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

    • parent: Especifica un recurso superior para los tipos de recursos que lo requieren. Coloca el name del recurso superior 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 del recurso (YAML) 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, te recomendamos que ajustes la definición para modificar solo los campos mutables. Si esto no es posible, puedes cambiar la acción de actualización a recreate.

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

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

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

        Te recomendamos que uses esta opción para los recursos que son completamente inmutables o cuando se realizan cambios en los campos que no se pueden actualizar en el lugar.

    • definition: 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 organización. Algunos tipos de recursos usan campos de metadatos para configurar el recurso en Google Cloud Por ejemplo, el metadata.location campo se puede usar para crear recursos zonales.

  3. Valida y, luego, 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 las 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 en función de 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 canalización como de costumbre. No hay diferencia en el uso en comparación con, por ejemplo, un clúster creado de forma manual.

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, sucede lo siguiente:

  1. Un repositorio de Dataform se conecta 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, implementas 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 este lanzamiento compilado automáticamente.

En el siguiente ejemplo de código, se define un repositorio de Dataform, una configuración de lanzamiento 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 lanzamiento a la confirmación de Git específica que se implementa. El COMMIT_SHA es una variable que se resuelve en el SHA de confirmación del paquete de canalización implementado.
  • La clave codeCompilationConfig.pipelineConfig.path apunta a una subcarpeta que contiene activos de canalización. De esta manera, puedes mantener varias canalizaciones de Dataform en un solo repositorio.

  • Si se establece releaseCompilationResult en auto en la definición de releaseConfig, se indica a las canalizaciones de organización que activen 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 a la 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. Se vuelve a actualizar releaseConfig 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 es el siguiente:

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