CLI de Stack

Importante

Esta característica está en versión beta.

Nota

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

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

Use la CLI de pila con la plantilla JSON de configuración de pila para implementar y administrar la pila.

Ejecute los subcomandos de la CLI de la pila de Databricks anexándolos 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 la pila para obtener información sobre cómo configurar una pila.

databricks stack deploy ./config.json

La plantilla JSON de configuración de pila proporciona un ejemplo de config.json .

Descarga de cambios en el cuaderno de pila

Este subcomando descarga los cuadernos de una pila.

databricks stack download ./config.json

Ejemplos

Configuración de la 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 notebooks/config carpeta . Hay una dependencia de biblioteca JAR de la pila en lib/library.jar . config.json es la plantilla JSON de configuración de pila de la pila. Esto 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 del área de trabajo, archivo DBFS o directorio DBFS se define como resourceconfig. Cada que representa un área de trabajo o un recurso DBFS contiene una asignación del archivo o directorio donde existe localmente ( ) a donde existiría en el área de trabajo o ResourceConfig source_path DBFS ( path ).

El esquema de la 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 databricks stack deploy <configuration-file> comando .

databricks stack deploy ./config.json

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

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

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

Importante

No intente editar ni mover el archivo de estado de la pila. Si recibe errores relacionados 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

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 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 para el recurso. Se aplica la unidad de ResourceConfig.
service ResourceService El servicio de API REST en el que opera el recurso. Uno de: jobs ,
workspace, o dbfs .
properties ResourceProperties Los campos de este son diferentes en función del ResourceConfig servicio.

ResourceProperties

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

service Campos de la API REST que se usa en la CLI de Stack Campos que solo se usan en la CLI de Stack
área de trabajo ruta de acceso: STRING rutas de acceso de área de trabajo remotas de cuadernos o directorios. (Por ejemplo, /Users/example@example.com/notebook)

object_type: ObjectType:tipo de objeto notebook. Solo puede ser NOTEBOOK o DIRECTORY .
source_path: ruta STRING de acceso de origen local de los 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 JobSettings. El único campo no necesario en JobSettings pero necesario para la CLI de pila es:

name: STRING nombre del trabajo que se va a implementar. Con el fin de no crear demasiados trabajos duplicados, la CLI de Stack aplica nombres únicos en los trabajos implementados en la pila.
Ninguno.
dbfs ruta de acceso: STRING coincidencia con la ruta de acceso remota de DBFS. Debe comenzar por dbfs:/ . (Ejemplo: dbfs:/this/is/a/sample/path)

is_dir: si BOOL una ruta de acceso de DBFS es un directorio o un archivo.
source_path: ruta STRING 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 que admite la CLI de Stack.

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

Esquema de estado de pila

StackStatus

Se crea un archivo de estado de pila después de implementar una pila mediante la CLI. Los campos de nivel superior son:

Nombre del campo Tipo Descripción
name STRING Nombre de la pila. Este campo es el mismo campo que en StackConfig.
cli_version STRING La versión de la CLI de Databricks que se usa 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: 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 directorio en un área Azure Databricks trabajo. La nomenclatura es coherente con workspace API.
jobs job_id STRING El identificador de trabajo como se muestra en un área Azure Databricks trabajo. Se puede usar para actualizar los trabajos ya implementados.
dbfs path STRING Ruta de acceso absoluta del cuaderno o directorio en un área Azure Databricks trabajo. La nomenclatura es coherente con la API de DBFS.