Compartir a través de

Sustituciones y variables en Agrupaciones de recursos de Databricks

  • Artículo

Agrupaciones de recursos de Databricks admite sustituciones y variables personalizadas, lo que hace que los archivos de configuración de agrupación sean más modulares y reutilizables. Tanto las sustituciones como las variables personalizadas permiten la recuperación dinámica de valores, de modo que la configuración se pueda determinar en el momento en que se implementa y se ejecuta una agrupación.

Sugerencia

También puede usar referencias de valor dinámico para los valores de parámetros de trabajo para pasar contexto sobre una ejecución de trabajo a tareas de trabajo. Consulte ¿Qué es una referencia de valores dinámicos? y Parametrización de trabajos.

Sustituciones

Puede usar sustituciones para recuperar valores de configuración que cambian en función del contexto de la implementación y ejecución de la agrupación.

Por ejemplo, al ejecutar el comando bundle validate --output json, es posible que vea un gráfico similar al siguiente:

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "...": "...",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

Las sustituciones se pueden usar para hacer referencia a los valores de los campos de agrupación name, agrupación target y área de trabajo userName a fin de construir el área de trabajo root_path en el archivo de configuración de agrupación:

bundle:
  name: hello-bundle

workspace:
  root_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

# ...

targets:
  dev:
    default: true

También puede crear sustituciones para los recursos con nombre. Por ejemplo, para la canalización configurada con el nombre my_pipeline, ${resources.pipelines.my_pipeline.target} es la sustitución del valor del destinomy_pipeline.

Para determinar las sustituciones válidas, puede usar la jerarquía de esquemas documentada en la Referencia de la API de REST o la salida del comando bundle schema.

Estas son algunas sustituciones usadas habitualmente:

  • ${bundle.name}
  • ${bundle.target} # Use this substitution instead of ${bundle.environment}
  • ${workspace.host}
  • ${workspace.current_user.short_name}
  • ${workspace.current_user.userName}
  • ${workspace.file_path}
  • ${workspace.root_path}
  • ${resources.jobs.<job-name>.id}
  • ${resources.models.<model-name>.name}
  • ${resources.pipelines.<pipeline-name>.name}

Variables personalizadas

Puede definir variables personalizadas simples y complejas en la agrupación a fin de habilitar la recuperación dinámica de valores necesarios para muchos escenarios. Se declaran variables personalizadas en los archivos de configuración de la agrupación dentro de la asignación variables. Vea variables.

La siguiente configuración de ejemplo define las variables my_cluster_id y my_notebook_path:

variables:
  my_cluster_id:
    description: The ID of an existing cluster.
    default: 1234-567890-abcde123
  my_notebook_path:
    description: The path to an existing notebook.
    default: ./hello.py

Si no proporciona un valor default para una variable como parte de esta declaración, debe establecerlo al ejecutar comandos de agrupación, a través de una variable de entorno, o bien en otro lugar de los archivos de configuración de la agrupación, como se describe en Establecimiento del valor de una variable.

Para hacer referencia a una variable personalizada en la configuración de agrupación, use la sustitución ${var.<variable_name>} de la variable. Por ejemplo, para hacer referencia a las variables my_cluster_id y my_notebook_path:

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ${var.my_notebook_path}

Establecimiento del valor de una variable

Si no ha proporcionado un valor de default para una variable, o si desea invalidar temporalmente el valor de default para una variable, proporcione el nuevo valor temporal de la variable mediante uno de los métodos siguientes:

  • Proporcione el valor de la variable como parte de un comando bundle, como validate, deploy o run. Para ello, use la opción --var="<key>=<value>", donde <key> es el nombre de la variable y <value> es el valor de la variable. Por ejemplo, como parte del comando bundle validate, para proporcionar el valor de 1234-567890-abcde123 a la variable denominada my_cluster_id y el valor de ./hello.py a la variable denominada my_notebook_path, ejecute:

    databricks bundle validate --var="my_cluster_id=1234-567890-abcde123,my_notebook_path=./hello.py"

# Or:
databricks bundle validate --var="my_cluster_id=1234-567890-abcde123" --var="my_notebook_path=./hello.py"

  • Proporcione el valor de la variable estableciendo una variable de entorno. El nombre de la variable de entorno debe comenzar por BUNDLE_VAR_. Para establecer las variables de entorno, consulte la documentación del sistema operativo. Por ejemplo, para proporcionar el valor de 1234-567890-abcde123 a la variable denominada my_cluster_id y el valor de ./hello.py a la variable denominada my_notebook_path, ejecute el siguiente comando antes de llamar a un comando bundle como validate, deploy o run:

    Para Linux y macOS:

    export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py

    Para Windows:

    "set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"

    O bien, proporcione el valor de la variable como parte de un comando bundle como validate, deploy o run, por ejemplo para Linux y macOS:

    BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate

    O para Windows:

    "set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"

  • Proporcione el valor de la variable dentro de los archivos de configuración de agrupación. Para ello, use una asignación variables dentro de la asignación targets, siguiendo este formato:

    variables:
  <variable-name>: <value>

    Por ejemplo, para proporcionar valores para las variables denominadas my_cluster_id y my_notebook_path para dos destinos independientes:

    targets:
  dev:
    variables:
      my_cluster_id: 1234-567890-abcde123
      my_notebook_path: ./hello.py
  prod:
    variables:
      my_cluster_id: 2345-678901-bcdef234
      my_notebook_path: ./hello.py

Nota:

Independientemente del enfoque que elija para proporcionar valores de variable, debe proporcionar los mismos valores durante las fases de implementación y ejecución. De lo contrario, podría obtener resultados inesperados entre el momento de una implementación y la ejecución de un trabajo o canalización que se base en esa implementación existente.

En los ejemplos anteriores, la CLI de Databricks busca valores para las variables my_cluster_id y my_notebook_path, en el orden siguiente, se detiene cuando encuentra un valor para cada variable coincidente, omitiendo cualquier otra ubicación para esa variable:

  1. Dentro de las --var opciones especificadas como parte del comando bundle.
  2. Dentro de cualquier conjunto de variables de entorno que comiencen por BUNDLE_VAR_.
  3. Dentro de las asignaciones variables, entre las asignaciones targets dentro de los archivos de configuración de agrupación.
  4. Cualquier valor default de la definición de esa variable, entre las asignaciones variables de nivel superior dentro de los archivos de configuración de agrupación.

Definición de una variable compleja

Se supone que una variable personalizada es de tipo cadena a menos que la defina como una variable compleja. Para definir una variable personalizada con un tipo complejo para la agrupación, establezca type en complex en la configuración de la agrupación.

Nota:

El único valor válido para la configuración type es complex. Además, la validación de la agrupación no se produce si type se establece en complex y si el valor default definido para la variable es un valor único.

En el ejemplo siguiente, la configuración del clúster se define en una variable compleja personalizada denominada my_cluster:

variables:
  my_cluster:
    description: "My cluster definition"
    type: complex
    default:
      spark_version: "13.2.x-scala2.11"
      node_type_id: "Standard_DS3_v2"
      num_workers: 2
      spark_conf:
        spark.speculation: true
        spark.databricks.delta.retentionDurationCheck.enabled: false

resources:
  jobs:
    my_job:
      job_clusters:
        - job_cluster_key: my_cluster_key
          new_cluster: ${var.my_cluster}
      tasks:
      - task_key: hello_task
        job_cluster_key: my_cluster_key

Recuperación de un valor de id. de objeto

Para el alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, pipeline, query, service_principaly warehouse tipos de objeto, puede definir un lookup para la variable personalizada para recuperar un identificador de objeto con nombre mediante este formato:

variables:
  <variable-name>:
    lookup:
      <object-type>: "<object-name>"

Si se define una búsqueda para una variable, el id. del objeto con el nombre especificado se usa como valor de la variable. Esto garantiza que el id. resuelto correcto del objeto siempre se use para la variable.

Nota:

Se produce un error si no existe un objeto con el nombre especificado o si hay más de un objeto con el nombre especificado.

Por ejemplo, en la siguiente configuración, ${var.my_cluster_id} se reemplazará por el identificador del clúster compartido de 12.2.

variables:
  my_cluster_id:
    description: An existing cluster
    lookup:
      cluster: "12.2 shared"

resources:
  jobs:
    my_job:
      name: "My Job"
      tasks:
        - task_key: TestTask
          existing_cluster_id: ${var.my_cluster_id}