Delen via

Projectsjablonen voor Databricks Asset Bundle

  • Artikel

In dit artikel worden de syntaxis voor Databricks Asset Bundle-sjablonen beschreven. Bundels maken programmatisch beheer van Azure Databricks-werkstromen mogelijk. Zie Wat zijn Databricks-assetbundels?

Met bundelsjablonen kunnen gebruikers bundels op een consistente, herhaalbare manier maken door mapstructuren tot stand te brengen, stappen en taken, tests en andere IaC-kenmerken (Infrastructure-as-Code) van DevOps te maken die gebruikelijk zijn in een pijplijn voor de implementatie van een ontwikkelomgeving.

Als u bijvoorbeeld regelmatig Databricks-taken uitvoert waarvoor aangepaste pakketten nodig zijn met een tijdrovende compilatiestap bij de installatie, kunt u uw ontwikkelingslus versnellen door een bundelsjabloon te maken die aangepaste containeromgevingen ondersteunt.

Bundelsjablonen definiëren de mapstructuur van de bundel die wordt gemaakt en bevatten een databricks.yml.tmpl configuratiebestandsjabloon en een databricks_template_schema.json bestand met gebruikerspromptvariabelen.

Een standaardbundelsjabloon gebruiken

Als u een standaardbundelsjabloon van Azure Databricks wilt gebruiken om uw bundel te maken, gebruikt u de Opdracht Databricks CLI bundle init en geeft u de naam op van de standaardsjabloon die u wilt gebruiken. Met de volgende opdracht maakt u bijvoorbeeld een bundel met behulp van de standaard-Python-bundelsjabloon:

databricks bundle init default-python

Als u geen standaardsjabloon opgeeft, wordt met de bundle init opdracht de set beschikbare sjablonen weergegeven waaruit u kunt kiezen.

Azure Databricks biedt de volgende standaardbundelsjablonen:

Sjabloon Beschrijving
default-python Een sjabloon voor het gebruik van Python met Databricks. Met deze sjabloon maakt u een bundel met een taak en een Delta Live Tables-pijplijn. Zie default-python.
default-sql Een sjabloon voor het gebruik van SQL met Databricks. Deze sjabloon bevat een configuratiebestand dat een taak definieert waarmee SQL-query's worden uitgevoerd in een SQL Warehouse. Zie default-sql.
dbt-sql Een sjabloon die gebruikmaakt van dbt-core voor lokale ontwikkeling en bundels voor implementatie. Deze sjabloon bevat de configuratie waarmee een taak met een dbt-taak wordt gedefinieerd, evenals een configuratiebestand dat dbt-profielen definieert voor geïmplementeerde dbt-taken. Zie dbt-sql.
mlops-stacks Een geavanceerde volledige stacksjabloon voor het starten van nieuwe MLOps Stacks-projecten. Zie mlops-stacks en Databricks Asset Bundles voor MLOps Stacks.

Een aangepaste bundelsjabloon gebruiken

Als u een andere bundelsjabloon dan de standaardbundelsjablonen van Azure Databricks wilt gebruiken, geeft u het lokale pad of de externe URL van de sjabloon door aan de Opdracht Databricks CLIbundle init.

Met de volgende opdracht wordt bijvoorbeeld de dab-container-template sjabloon gebruikt die is gemaakt in de zelfstudie aangepaste bundelsjablonen:

databricks bundle init /projects/my-custom-bundle-templates/dab-container-template

Een aangepaste bundelsjabloon maken

Bundelsjablonen maken gebruik van de sjabloonsyntaxis van Go-pakketten. Zie de go-pakketsjabloondocumentatie .

Een bundelsjabloonproject moet minimaal het volgende hebben:

  • Een databricks_template_schema.json bestand in de hoofdmap van het project waarmee één gebruikerspromptvariabele wordt gedefinieerd voor de naam van het bundelproject.
  • Een databricks.yml.tmpl bestand in een template map die de configuratie definieert voor alle bundels die met de sjabloon zijn gemaakt. Als uw databricks.yml.tmpl bestand verwijst naar aanvullende *.yml.tmpl configuratiesjablonen, geeft u de locatie van deze sjablonen op in de include toewijzing.

U kunt eventueel submappen en bestanden toevoegen aan de template map die u wilt spiegelen in bundels die door de sjabloon zijn gemaakt.

Gebruikerspromptvariabelen definiëren

De eerste stap bij het bouwen van een basisbundelsjabloon is het maken van een sjabloonprojectmap en een bestand met de naam databricks_template_schema.json in de hoofdmap van het project. Dit bestand bevat de variabelen waarvoor gebruikers invoerwaarden opgeven wanneer ze de sjabloon gebruiken om een bundel te maken met behulp van bundle init. De indeling van dit bestand volgt de JSON-schemaspecificatie.

mkdir basic-bundle-template
touch basic-bundle-template/databricks_template_schema.json

Voeg het volgende toe aan het databricks_template_schema.json bestand en sla het bestand op:

{
   "properties": {
   "project_name": {
      "type": "string",
      "default": "basic_bundle",
      "description": "What is the name of the bundle you want to create?",
      "order": 1
   }
   },
   "success_message": "\nYour bundle '{{.project_name}}' has been created."
}

In dit bestand:

  • project_name is de enige naam van de invoervariabele.
  • default is een optionele standaardwaarde als een waarde niet wordt opgegeven door de gebruiker --config-file als onderdeel van de bundle init opdracht of wordt overschreven door de gebruiker bij de opdrachtprompt.
  • description is de gebruikersprompt die is gekoppeld aan de invoervariabele, als een waarde niet wordt opgegeven door de gebruiker --config-file als onderdeel van de bundle init opdracht.
  • order is een optionele volgorde waarin elke gebruikersprompt wordt weergegeven als een waarde niet wordt opgegeven door de gebruiker als --config-file onderdeel van de bundle init opdracht. Als order dit niet is opgegeven, worden gebruikersprompts weergegeven in de volgorde waarin ze worden vermeld in het schema.
  • success_message is een optioneel bericht dat wordt weergegeven bij het maken van een project.

De mapstructuur bouwen

Maak vervolgens de vereiste template map en bouw de mapstructuur erin. Deze structuur wordt gespiegeld door bundels die met deze sjabloon zijn gemaakt. Plaats ook alle bestanden die u in deze mappen wilt opnemen. Deze eenvoudige bundelsjabloon slaat bestanden op in een src map en bevat één eenvoudig notitieblok.

mkdir -p basic-bundle-template/template/src
touch basic-bundle-template/template/src/simple_notebook.ipynb

Voeg het volgende toe aan het simple_notebook.ipynb bestand:

print("Hello World!")

Configuratiesjabloonbestanden vullen

Maak nu het vereiste databricks.yml.tmpl bestand in de template map:

touch basic-bundle-template/template/databricks.yml.tmpl

Vul dit bestand in met de YAML van de basisconfiguratiesjabloon. Met deze configuratiesjabloon worden de bundelnaam, één taak met behulp van het opgegeven notebookbestand en twee doelomgevingen vastgelegd voor bundels die met deze sjabloon zijn gemaakt. Het maakt ook gebruik van bundelvervangingen, wat ten zeerste wordt aanbevolen. Zie bundelvervangingen.

# This is the configuration for the Databricks Asset Bundle {{.project_name}}.

bundle:
  name: {{.project_name}}

# The main job for {{.project_name}}
resources:
    jobs:
        {{.project_name}}_job:
        name: {{.project_name}}_job
        tasks:
            - task_key: notebook_task
            job_cluster_key: job_cluster
            notebook_task:
                notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
            new_cluster:
                node_type_id: i3.xlarge
                spark_version: 13.3.x-scala2.12

targets:
  # The deployment targets. See https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html
  dev:
    mode: development
    default: true
    workspace:
      host: {{workspace_host}}

  prod:
    mode: production
    workspace:
      host: {{workspace_host}}
      root_path: /Shared/.bundle/prod/${bundle.name}
    {{- if not is_service_principal}}
    run_as:
      # This runs as {{user_name}} in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: {{user_name}}
    {{end -}}

De bundelsjabloon testen

Test ten slotte de sjabloon. Maak een nieuwe bundelprojectmap en gebruik vervolgens de Databricks CLI om een nieuwe bundel te initialiseren met behulp van de sjabloon:

mkdir my-test-bundle
cd my-test-bundle
databricks bundle init ../basic-bundle-template

Typ voor de prompt What is your bundle project name?.my_test_bundle

Zodra de testbundel is gemaakt, wordt het succesbericht van het schemabestand uitgevoerd. Als u de inhoud van de my-test-bundle map bekijkt, ziet u het volgende:

my-test-bundle
   ├── databricks.yml
   └── src
      └── simple_notebook.ipynb

En het databricks.yml-bestand is nu aangepast:

# This is the configuration for the Databricks Asset Bundle my-test-bundle.

bundle:
  name: my-test-bundle

# The main job for my-test-bundle
resources:
    jobs:
        my-test-bundle_job:
        name: my-test-bundle_job
        tasks:
            - task_key: notebook_task
                job_cluster_key: job_cluster
                notebook_task:
                    notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
                new_cluster:
                    node_type_id: i3.xlarge
                    spark_version: 13.3.x-scala2.12

targets:
  # The 'dev' target, used for development purposes. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#development-mode)
  dev:
    mode: development
    default: true
    workspace:
      host: https://my-host.cloud.databricks.com

  # The 'prod' target, used for production deployment. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#production-mode)
  prod:
    mode: production
    workspace:
      host: https://my-host.cloud.databricks.com
      root_path: /Shared/.bundle/prod/${bundle.name}
    run_as:
      # This runs as someone@example.com in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: someone@example.com

De sjabloon delen

Als u deze bundelsjabloon met anderen wilt delen, kunt u deze opslaan in versiebeheer met elke provider die door Git wordt ondersteund en waartoe uw gebruikers toegang hebben. Als u de bundle init opdracht wilt uitvoeren met een Git-URL, moet u ervoor zorgen dat het databricks_template_schema.json bestand zich op de hoofdlocatie bevindt ten opzichte van die Git-URL.

Tip

U kunt het databricks_template_schema.json bestand in een andere map plaatsen ten opzichte van de hoofdmap van de bundel. Vervolgens kunt u de optie van --template-dir de bundle init opdracht gebruiken om te verwijzen naar die map, die het databricks_template_schema.json bestand bevat.

Volgende stappen