CLI da pilha (herdada)

Importante

Esta documentação foi desativada e pode não estar atualizada.

Essas informações se aplicam às versões herdadas da CLI do Databricks 0.18 e anteriores. O Databricks recomenda que você use a versão 0.205 da CLI do Databricks mais recente ou superior. Consulte O que é a CLI do Databricks?. Para localizar sua versão da CLI do Databricks, execute databricks -v.

Para migrar da CLI do Databricks versão 0.18 ou inferior para a versão 0.205 ou superior, consulte Migração da CLI do Databricks.

As versões 0.205 e superiores da CLI do Databricks não dão suporte à CLI de pilha. Em seu lugar, o Databricks recomenda que você use o provedor Terraform do Databricks.

Observação

A CLI de pilha exige a CLI 0.8.3 ou superior do Databricks.

A CLI de pilha oferece uma forma de gerenciar uma pilha de recursos do Azure Databricks, como trabalhos, notebooks e arquivos DBFS. Você pode armazenar notebooks e arquivos DBFS localmente e criar um modelo JSON de configuração de pilha que define os mapeamentos dos arquivos locais para caminhos no seu workspace do Azure Databricks, com as configurações de trabalhos que executam os notebooks.

Use a CLI de pilha com o modelo JSON de configuração da pilha para implantar e gerenciar sua pilha.

Execute subcomandos da CLI de pilha do Databricks acrescentando-os ao databricks stack.

databricks stack --help

Usage: databricks stack [OPTIONS] COMMAND [ARGS]...

  [Beta] Utility to deploy and download Databricks resource stacks.

Options:
  -v, --version   [VERSION]
  --debug         Debug Mode. Shows full stack trace on error.
  --profile TEXT  CLI connection profile to use. The default profile is
                  "DEFAULT".
  -h, --help      Show this message and exit.

Commands:
  deploy    Deploy a stack of resources given a JSON configuration of the stack
    Usage: databricks stack deploy [OPTIONS] CONFIG_PATH
    Options:
       -o, --overwrite  Include to overwrite existing workspace notebooks and DBFS
                        files  [default: False]
  download  Download workspace notebooks of a stack to the local filesystem
            given a JSON stack configuration template.
    Usage: databricks stack download [OPTIONS] CONFIG_PATH
    Options:
       -o, --overwrite  Include to overwrite existing workspace notebooks in the
                        local filesystem   [default: False]

Implantar uma pilha em um workspace

Esse subcomando implanta uma pilha. Confira Configuração de pilha para saber como configurar uma pilha.

databricks stack deploy ./config.json

O modelo JSON de configuração de pilha fornece um exemplo de config.json.

Baixar alterações do notebook de pilha

Esse subcomando baixa os notebooks de uma pilha.

databricks stack download ./config.json

Exemplos

Configuração de pilha

Estrutura de arquivos de um exemplo de pilha

tree

.
├── notebooks
|   ├── common
|   |   └── notebook.scala
|   └── config
|       ├── environment.scala
|       └── setup.sql
├── lib
|   └── library.jar
└── config.json

Este exemplo de pilha contém um notebook principal em notebooks/common/notebook.scala com os notebooks de configuração na pasta notebooks/config. Há uma dependência de biblioteca JAR da pilha em lib/library.jar. config.json é o modelo JSON de configuração da pilha. É isso que é transmitido para a CLI de pilha para a implantação da pilha.

Modelo JSON de configuração de pilha

O modelo de configuração de pilha descreve a configuração da pilha.

cat config.json

{
  "name": "example-stack",
  "resources": [
  {
    "id": "example-workspace-notebook",
    "service": "workspace",
    "properties": {
      "source_path": "notebooks/common/notebook.scala",
      "path": "/Users/example@example.com/dev/notebook",
      "object_type": "NOTEBOOK"
    }
  },
  {
    "id": "example-workspace-config-dir",
    "service": "workspace",
    "properties": {
      "source_path": "notebooks/config",
      "path": "/Users/example@example.com/dev/config",
      "object_type": "DIRECTORY"
    }
  },
  {
    "id": "example-dbfs-library",
    "service": "dbfs",
    "properties": {
      "source_path": "lib/library.jar",
      "path": "dbfs:/tmp/lib/library.jar",
      "is_dir": false
    }
  },
    {
      "id": "example-job",
      "service": "jobs",
      "properties": {
        "name": "Example Stack CLI Job",
        "new_cluster": {
          "spark_version": "7.3.x-scala2.12",
          "node_type_id": "Standard_DS3_v2",
          "num_workers": 3
        },
        "timeout_seconds": 7200,
        "max_retries": 1,
        "notebook_task": {
          "notebook_path": "/Users/example@example.com/dev/notebook"
        },
        "libraries": [
          {
            "jar": "dbfs:/tmp/lib/library.jar"
          }
        ]
      }
    }
  ]
}

Cada trabalho, notebook do workspace, diretório do workspace, arquivo DBFS ou diretório do DBFS é definido como uma ResourceConfig. Cada ResourceConfig que representa um workspace ou um ativo do DBFS contém um mapeamento do arquivo ou do diretório em que ele existe localmente (source_path) para o local em que ele existirá no workspace ou no DBFS (path).

O esquema do modelo de configuração de pilha descreve o esquema do modelo de configuração de pilha.

Implantar uma pilha

Implante uma pilha usando o comando databricks stack deploy <configuration-file>.

databricks stack deploy ./config.json

Durante a implantação da pilha, os ativos do DBFS e do workspace são carregados no seu workspace do Azure Databricks e os trabalhos são criados.

No momento da implantação da pilha, um arquivo JSON StackStatus para a implantação é salvo no mesmo diretório do modelo de configuração de pilha com o nome, adicionando deployed imediatamente antes da extensão .json: (por exemplo, ./config.deployed.json). Esse arquivo é usado pela CLI de pilha para acompanhar os recursos já implantados no seu workspace.

O esquema de status da pilha descreve o esquema de uma configuração de pilha.

Importante

Não tente editar nem mover o arquivo de status da pilha. Se você receber erros referentes ao arquivo de status da pilha, exclua o arquivo e tente realizar a implantação novamente.

./config.deployed.json

{
  "cli_version": "0.8.3",
  "deployed_output": [
    {
      "id": "example-workspace-notebook",
      "databricks_id": {
        "path": "/Users/example@example.com/dev/notebook"
      },
      "service": "workspace"
    },
    {
      "id": "example-workspace-config-dir",
      "databricks_id": {
        "path": "/Users/example@example.com/dev/config"
      },
      "service": "workspace"
    },
    {
      "id": "example-dbfs-library",
      "databricks_id": {
        "path": "dbfs:/tmp/lib/library.jar"
      },
      "service": "dbfs"
    },
    {
      "id": "example-job",
      "databricks_id": {
        "job_id": 123456
      },
      "service": "jobs"
    }
  ],
  "name": "example-stack"
}

Estruturas de dados

Nesta seção:

• Esquema do modelo de configuração de pilha
• Esquema de status da pilha
• DatabricksId

Esquema do modelo de configuração de pilha

StackConfig

Estes são os campos externos de um modelo de configuração de pilha. Todos os campos são obrigatórios.

Nome do campo	Tipo	Descrição
name	STRING	O nome da pilha.
recursos	Lista de ResourceConfig	Um ativo do Azure Databricks. Os recursos estão relacionados a três serviços (namespaces da API REST): workspace, trabalhos e DBFS.

ResourceConfig

Os campos de cada ResourceConfig. Todos os campos são obrigatórios.

Nome do campo	Tipo	Descrição
id	STRING	Uma ID exclusiva para o recurso. A exclusividade de ResourceConfig é imposta.
serviço	ResourceService	O serviço de API REST no qual o recurso opera. Uma opção entre jobs, workspace ou dbfs.
properties	ResourceProperties	Os campos dele são diferentes, dependendo do serviço ResourceConfig.

ResourceProperties

As propriedades de um recurso por ResourceService. Os campos são classificados como aqueles usados ou não usados em uma API REST do Azure Databricks. Todos os campos listados são obrigatórios.

serviço	Campos da API REST usados na CLI de pilha	Campos usados somente na CLI de pilha
workspace	path: STRING – Caminhos de workspace remotos de notebooks ou diretórios. (Ex. /Users/example@example.com/notebook) object_type: API do Workspace – Tipo de objeto notebook. Só pode ser NOTEBOOK ou DIRECTORY.	source_path: STRING – Caminho de origem local de notebooks ou diretórios do workspace. Um caminho relativo ao arquivo de modelo de configuração de pilha ou um caminho absoluto no sistema de arquivos.
jobs	Qualquer campo na estrutura settings ou new_settings. O único campo não obrigatório na estrutura settings ou new_settings, mas obrigatório na CLI de pilha, é: name: STRING – Nome do trabalho a ser implantado. Para fins de não criação de muitos trabalhos duplicados, a CLI de pilha impõe nomes exclusivos aos trabalhos de pilha implantados.	Nenhum.
dbfs	path: STRING – Caminho do DBFS remoto correspondente. Precisa começar com dbfs:/. (ex. dbfs:/this/is/a/sample/path) is_dir: BOOL – Indica se um caminho do DBFS é um diretório ou um arquivo.	source_path: STRING – Caminho de origem local de arquivos ou diretórios do DBFS. Um caminho relativo ao arquivo de modelo de configuração de pilha ou um caminho absoluto no sistema de arquivos.

ResourceService

Cada recurso pertence a um serviço específico que se alinha com a API REST do Databricks. Esses são os serviços compatíveis com a CLI de pilha.

Serviço	Descrição
workspace	Um notebook ou um diretório de workspace.
jobs	Um trabalho do Azure Databricks.
dbfs	Um arquivo ou um diretório do DBFS.

Esquema de status da pilha

StackStatus

Um arquivo de status da pilha é criado depois que uma pilha é implantada por meio da CLI. Os campos de nível superior são:

Nome do campo	Tipo	Descrição
name	STRING	O nome da pilha. Esse campo é o mesmo campo que em StackConfig.
cli_version	STRING	A versão da CLI do Databricks usada para implantar a pilha.
deployed_resources	Lista de ResourceStatus	O status de cada recurso implantado. Para cada recurso definido em StackConfig, um ResourceStatus correspondente é gerado aqui.

ResourceStatus

Nome do campo	Tipo	Descrição
id	STRING	Uma ID exclusiva da pilha para o recurso.
serviço	ResourceService	O serviço de API REST no qual o recurso opera. Uma opção entre jobs, workspace ou dbfs.
databricks_id	DatabricksId	A ID física do recurso implantado. O esquema real depende do tipo (serviço) do recurso.

DatabricksId

Um objeto JSON cujo campo depende do serviço.

Serviço	Campo em JSON	Type	Descrição
workspace	caminho	STRING	O caminho absoluto do notebook ou do diretório em um workspace do Azure Databricks. A nomenclatura é consistente com a API de Workspace.
jobs	job_id	STRING	A ID do trabalho, conforme mostrado em um workspace do Azure Databricks. Isso pode ser usado para atualizar os trabalhos já implantados.
dbfs	caminho	STRING	O caminho absoluto do notebook ou do diretório em um workspace do Azure Databricks. A nomenclatura é consistente com a API do DBFS.