CLI de pila (heredada)

Artículo
03/01/2024

Importante

Esta documentación se ha retirado y es posible que no se actualice.

Esta información se aplica a las versiones heredadas de la CLI de Databricks 0.18 y versiones posteriores. En su lugar, Databricks recomienda usar la versión más reciente 0.205 o posterior de la CLI de Databricks. Consulte ¿Qué es la CLI de Databricks?. Para encontrar su versión de la CLI de Databricks, ejecute databricks -v.

Para migrar de la versión 0.18 o inferior a la versión 0.205 o superior de la CLI de Databricks, consulte Migración de la CLI de Databricks.

Las versiones 0.205 y posteriores de la CLI de Databricks no admiten la CLI de pila. Databricks recomienda usar en su lugar el Proveedor de Databricks Terraform.

Nota:

La CLI de pila requiere la CLI de Databricks 0.8.3 o posterior.

La CLI de pila proporciona una manera de administrar una pila de recursos de Azure Databricks, como trabajos, cuadernos y archivos DBFS. Puede almacenar localmente cuadernos y archivos DBFS y crear una plantilla JSON de configuración de pila que defina las asignaciones de los archivos locales a las rutas de acceso en el área de trabajo de Azure Databricks, junto con las configuraciones de los trabajos que ejecutan los cuadernos.

Para implementar y administrar la pila, utilice la CLI de pila con la plantilla JSON de configuración correspondiente.

Para ejecutar subcomandos de la CLI de pila de Databricks, anéxelos a 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]

Implementación de una pila en un área de trabajo

Este subcomando implementa una pila. Consulte Configuración de una pila para aprender a configurar una pila.

databricks stack deploy ./config.json

En la sección Plantilla JSON de configuración de pila, se proporciona un ejemplo de config.json.

Descarga de los cambios del cuaderno de una pila

Este subcomando descarga los cuadernos de una pila.

databricks stack download ./config.json

Ejemplos

Configuración de una pila

Estructura de archivos de una pila de ejemplo

tree

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

Esta pila de ejemplo contiene un cuaderno principal en notebooks/common/notebook.scala junto con cuadernos de configuración en la carpeta notebooks/config. Hay una dependencia de biblioteca JAR de la pila en lib/library.jar. config.json es la plantilla JSON de configuración de la pila. Es lo que se pasa a la CLI de pila para la implementación de la pila.

Plantilla JSON de configuración de pila

La plantilla de configuración de pila describe la configuración de la pila.

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 trabajo, cuaderno de área de trabajo, directorio de área de trabajo, archivo DBFS o directorio DBFS se define como un elemento ResourceConfig. Cada ResourceConfig que representa un recurso de área de trabajo o DBFS contiene una asignación del archivo o directorio en el que existe localmente (source_path) a la ubicación en la que existiría en el área de trabajo o DBFS (path).

El esquema de plantilla de configuración de pila describe el esquema de la plantilla de configuración de pila.

Implementación de una pila

Una pila se implementa mediante el comando databricks stack deploy <configuration-file>.

databricks stack deploy ./config.json

Durante la implementación de la pila, los recursos de área de trabajo o DBFS se cargan en el área de trabajo de Azure Databricks y se crean los trabajos.

En el momento de implementación de la pila, se guarda un archivo JSON StackStatus para la implementación en el mismo directorio de la plantilla de configuración de pila con el nombre, agregando deployed inmediatamente antes de la extensión .json: (por ejemplo, ./config.deployed.json). La CLI de pila utiliza este archivo para llevar un seguimiento de los recursos implementados anteriormente en el área de trabajo.

El esquema de estado de la pila describe el esquema de la configuración de una pila.

Importante

No intente editar ni mover el archivo de estado de la pila. Si recibe algún error relacionado con el archivo de estado de la pila, elimínelo y vuelva a intentar la implementación.

./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"
}

Estructuras de datos

En esta sección:

Esquema de plantilla de configuración de pila
Esquema de estado de pila
DatabricksId

Esquema de plantilla de configuración de pila

StackConfig

Estos son los campos externos de una plantilla de configuración de pila. Todos los campos son obligatorios.

Nombre del campo	Tipo	Descripción
name	`STRING`	El nombre de la pila.
resources	Lista de ResourceConfig	Un recurso en Azure Databricks. Los recursos están relacionados con tres servicios (espacios de nombres de API REST): área de trabajo, trabajos y DBFS.

ResourceConfig

Los campos de cada ResourceConfig. Todos los campos son obligatorios.

Nombre del campo	Tipo	Descripción
id	`STRING`	Identificador único del recurso. Se aplica la exclusividad de ResourceConfig.
service	ResourceService	El servicio de API REST en el que opera el recurso. Uno de estos valores: `jobs`, `workspace` o `dbfs`.
properties	ResourceProperties	Aquí, los campos son diferentes en función del servicio `ResourceConfig`.

ResourceProperties

Propiedades de un recurso por ResourceService. Los campos se clasifican como aquellos que se usan o no se usan en una API REST de Azure Databricks. Todos los campos que se muestran son obligatorios.

service	Campos de la API REST que se usan en la CLI de pila	Campos que se usan solo en la CLI de pila
área de trabajo	path: `STRING`: rutas de acceso al área de trabajo remota de cuadernos o directorios. (Ex. `/Users/example@example.com/notebook`) object_type: API del área de trabajo: tipo de objeto de cuaderno. Solo puede ser `NOTEBOOK` o `DIRECTORY`.	source_path: `STRING`: ruta de acceso al origen local de cuadernos o directorios del área de trabajo. Una ruta de acceso relativa al archivo de plantilla de configuración de pila o una ruta de acceso absoluta en el sistema de archivos.
jobs	Cualquier campo de la configuración o la estructura new_settings. El único campo que no es obligatorio en la configuración o la estructura new_settings, pero que sí lo es para la CLI de pila es: name: `STRING`: nombre del trabajo que se va a implementar. A fin de no crear demasiados trabajos duplicados, la CLI de pila aplica nombres únicos en los trabajos implementados de la pila.	ninguno.
dbfs	path: `STRING`: ruta de acceso de DBFS remota coincidente. Debe comenzar por `dbfs:/`. (ex. `dbfs:/this/is/a/sample/path`) is_dir: `BOOL`: indica si una ruta de acceso de DBFS es un directorio o un archivo.	source_path: `STRING`: ruta de acceso de origen local de archivos o directorios DBFS. Una ruta de acceso relativa al archivo de plantilla de configuración de pila o una ruta de acceso absoluta en el sistema de archivos.

ResourceService

Cada recurso pertenece a un servicio específico que se alinea con la API REST de Databricks. Estos son los servicios compatibles con la CLI de pila.

Servicio	Descripción
área de trabajo	Directorio o cuaderno del área de trabajo.
jobs	Trabajo de Azure Databricks.
dbfs	Directorio o archivo de DBFS.

Esquema de estado de pila

StackStatus

Se crea un archivo de estado de pila una vez que se implementa una pila mediante la CLI. Los campos de nivel superior son:

Nombre del campo	Tipo	Descripción
name	`STRING`	El nombre de la pila. Se trata del mismo campo que en StackConfig.
cli_version	`STRING`	La versión de la CLI de Databricks que se utiliza para implementar la pila.
deployed_resources	Lista de ResourceStatus	Estado de cada recurso implementado. Para cada recurso definido en StackConfig, aquí se genera un ResourceStatus correspondiente.

ResourceStatus

Nombre del campo	Tipo	Descripción
id	`STRING`	Identificador único de pila para el recurso.
service	ResourceService	El servicio de API REST en el que opera el recurso. Uno de estos valores: `jobs`, `workspace` o `dbfs`.
databricks_id	DatabricksId	Identificador físico del recurso implementado. El esquema real depende del tipo (servicio) del recurso.

DatabricksId

Objeto JSON cuyo campo depende del servicio.

Servicio	Campo en JSON	Tipo	Descripción
área de trabajo	path	STRING	Ruta de acceso absoluta del cuaderno o el directorio en un área de trabajo de Azure Databricks. La nomenclatura es coherente con API de área de trabajo.
jobs	job_id	STRING	Identificador del trabajo tal como se muestra en un área de trabajo de Azure Databricks. Se puede usar para actualizar los trabajos ya implementados.
dbfs	path	STRING	Ruta de acceso absoluta del cuaderno o el directorio en un área de trabajo de Azure Databricks. La nomenclatura es coherente con la API de DBFS.