Substituições e variáveis em Databricks Asset Bundles

O Databricks Asset Bundles suporta substituições e variáveis personalizadas, que tornam seus arquivos de configuração de pacote mais modulares e reutilizáveis. Tanto as substituições quanto as variáveis personalizadas permitem a recuperação dinâmica de valores para que as configurações possam ser determinadas no momento em que um pacote é implantado e executado.

Substituições

Você pode usar substituições para recuperar valores de configurações que podem ser alteradas com base no contexto da implantação e execução do pacote. Por exemplo, as subsituções podem ser usadas para fazer referência aos valores dos campos bundle name, bundle targete workspace userName para construir o workspace root_path no arquivo de configuração do bundle:

bundle:
  name: hello-bundle

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

targets:
  dev:
    default: true

Se someone@example.com implantasse este pacote, ele seria implantado na raiz do caminho /Workspace/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev.

Você também pode criar substituições para recursos nomeados. Por exemplo, para a seguinte definição de pipeline, você pode usar ${resources.pipelines.my_pipeline.target} para o valor do destino do pipeline:

resources:
  pipelines:
    my_pipeline:
      name: my_pipeline
      schema: pipeline_bundle_${bundle.target}
      libraries:
        - notebook:
            path: ../src/my_pipeline.ipynb

      configuration:
        bundle.sourcePath: ${workspace.file_path}/src

Para determinar substituições válidas, use a referência de configuração de pacote, a referência de configuração de recursos ou a hierarquia de esquema de objetos correspondentes documentados na referência da API REST ou a saída do bundle schema comando.

Aqui estão algumas substituições comumente usadas:

• ${bundle.name}
• ${bundle.target} # Use this substitution instead of ${bundle.environment}
• ${workspace.host}
• ${workspace.current_user.domain_friendly_name}
• ${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}

Variáveis personalizadas

Você pode definir variáveis personalizadas simples e complexas em seu pacote para habilitar a recuperação dinâmica de valores necessários para muitos cenários. As variáveis personalizadas são declaradas em seus arquivos de configuração de pacote dentro do mapeamento de variables ou em um arquivo variable-overrides.json. Para obter informações sobre o mapeamento de variables, consulte as variáveis .

O exemplo de configuração a seguir define as variáveis my_cluster_id e 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

Se não fornecer um default valor para uma variável como parte desta declaração, deverá defini-lo ao executar comandos do bundle, por meio de uma variável de ambiente, noutro local dentro dos ficheiros de configuração do bundle ou no arquivo .databricks/bundle/<target>/variable-overrides.json do projeto do bundle. Consulte Definir o valor de uma variável.

Referenciar uma variável

Para fazer referência a uma variável personalizada dentro da configuração do pacote, utilize o marcador substitution${var.<variable_name>}. Por exemplo, a configuração a seguir faz referência às variáveis my_cluster_id e 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}

Definir o valor de uma variável

Se você não tiver definido um default valor para uma variável ou se quiser substituir temporariamente o default valor de uma variável, forneça o novo valor temporário da variável usando uma das seguintes abordagens.

• Forneça o valor da variável como parte de um bundle comando como validate, deployou run. Para fazer isso, use a opção --var="<key>=<value>", onde <key> é o nome da variável e <value> é o valor da variável. Por exemplo, como parte do bundle validate comando, para fornecer o valor de 1234-567890-abcde123 para a variável nomeada my_cluster_id, e para fornecer o valor de ./hello.py para a variável chamada my_notebook_path, execute:

  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"
  

• Forneça o valor da variável definindo uma variável de ambiente. O nome da variável de ambiente deve começar com BUNDLE_VAR_. Para definir variáveis de ambiente, consulte a documentação do seu sistema operacional. Por exemplo, para fornecer o valor de 1234-567890-abcde123 para a variável nomeada my_cluster_id, e para fornecer o valor de ./hello.py para a variável nomeada my_notebook_path, execute o seguinte comando antes de chamar um comando como bundle, validate, deploy, ou run:

  Para Linux e 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"
  

  Ou, forneça o valor da variável como parte de um bundle comando como validate, deployou run, por exemplo, para Linux e macOS:

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

  Ou para Windows:

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

• Forneça o valor da variável nos seus arquivos de configuração de pacotes usando o mapeamento variables dentro do mapeamento targets, seguindo este formato:

  variables:
    <variable-name>: <value>
  

  Por exemplo, para definir valores para as variáveis chamadas my_cluster_id e my_notebook_path para dois destinos separados:

  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
  

• Forneça o valor da variável dentro do .databricks/bundle/<target>/variable-overrides.json arquivo, usando o seguinte formato:

  {
    "<variable-name>": "<variable-value>"
  }
  

  Por exemplo, para fornecer valores para as variáveis chamadas my_cluster_id e my_notebook_path para o destino de desenvolvimento, crie um .databricks/bundle/dev/variable-overrides.json de arquivo e defina seu conteúdo para:

  {
    "my_cluster_id": "1234-567890-abcde123",
    "my_notebook_path": "./hello.py"
  }
  

  Você também pode definir variáveis complexas no arquivo variable-overrides.json.

Ordem de precedência

A CLI do Databricks procura valores para variáveis na seguinte ordem, parando quando encontra um valor para uma variável:

1. Dentro de quaisquer --var opções especificadas como parte do bundle comando.
2. Dentro de qualquer conjunto de variáveis de ambiente que comece com BUNDLE_VAR_.
3. Dentro do arquivo variables-overrides.json, se ele existir.
4. Dentro de quaisquer variables mapeamentos, entre os mapeamentos dentro de targets seus arquivos de configuração de pacote.
5. Qualquer default valor para a definição dessa variável, entre os mapeamentos de nível variables superior dentro dos arquivos de configuração do pacote.

Definir uma variável complexa

Presume-se que uma variável personalizada seja do tipo string, a menos que você a defina como uma variável complexa. Para definir uma variável personalizada com um tipo complexo para seu pacote na configuração do pacote, defina type como complex.

No exemplo a seguir, as configurações de cluster são definidas dentro de uma variável complexa personalizada chamada 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

Você também pode definir uma variável complexa no arquivo .databricks/bundle/<target>/variable-overrides.json, conforme mostrado no exemplo a seguir:

{
  "my_cluster": {
    "spark_version": "13.2.x-scala2.11",
    "node_type_id": "Standard_DS3_v2",
    "num_workers": 2
  }
}

Recuperar o valor de ID de um objeto

Para os tipos de objeto alert, cluster_policy, cluster, dashboard, instance_pool, job, metastore, notification_destination, pipeline, query, service_principal e warehouse, pode definir um lookup para a sua variável personalizada para recuperar a ID de um objeto nomeado usando este formato:

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

Se uma pesquisa for definida para uma variável, a ID do objeto com o nome especificado será usada como o valor da variável. Isso garante que a ID resolvida correta do objeto seja sempre usada para a variável.

Por exemplo, na configuração a seguir, ${var.my_cluster_id} será substituído pela ID do cluster compartilhado 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}

Substituição de saída e valores variáveis

Para garantir que suas substituições e variáveis sejam especificadas e analisadas corretamente pelo Databricks Asset Bundles, execute databricks bundle validate. Consulte databricks bundle validate. Para visualizar os valores que serão usados quando desdobrar um pacote, use a opção --output json.

databricks bundle validate --output json

Por exemplo, para um pacote com a variável my_cluster_id definida e usada em uma tarefa de trabalho:

bundle:
  name: variables_bundle

variables:
  my_cluster_id:
    default: 1234-567890-abcde123

resources:
  jobs:
    variables_bundle_job:
      name: variables_bundle_job
      tasks:
        - task_key: notebook_task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ../src/notebook.ipynb

A databricks bundle validate saída do esquema seria a seguinte:

{
  "bundle": {
    "..."
    "name": "variables_bundle",
    "target": "dev",
  "..."
  },
  "resources": {
    "jobs": {
      "variables_bundle_job": {
        "deployment": {
          "kind": "BUNDLE",
          "metadata_file_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/state/metadata.json"
        },
        "max_concurrent_runs": 4,
        "name": "[dev someone] variables_bundle_job",
        "tasks": [
          {
            "existing_cluster_id": "1234-567890-abcde123",
            "notebook_task": {
              "notebook_path": "/Workspace/Users/someone@example.com/.bundle/variables_bundle/dev/files/variables_bundle/src/notebook"
            },
            "task_key": "notebook_task"
          },
        ],
      "..."
      }
    }
  },
  "..."
  "variables": {
    "my_cluster_id": {
      "default": "1234-567890-abcde123",
      "value": "1234-567890-abcde123"
    }
  },
"..."
}