Deklarativní šablony projektů pro automatizaci balíčků

Deklarativní balíčky automatizace (dříve označované jako Sady prostředků Databricks) popisují prostředky Databricks, jako jsou úlohy, kanály a poznámkové bloky, jako zdrojové soubory, umožňují zahrnout metadata spolu s těmito zdrojovými soubory za účelem zřízení infrastruktury a dalších prostředků a poskytnout kompletní definici projektu, a to vše zabalené jako jeden nasaditelný projekt. Viz Co jsou balíčky deklarativní automatizace?

Šablony sad umožňují uživatelům vytvářet sady konzistentním, opakovatelným způsobem, a to vytvořením struktur složek, kroků sestavení a úloh, testů a dalších atributů infrastruktury jako kódu DevOps (IaC), které jsou společné v rámci kanálu nasazení.

Pokud například při instalaci pravidelně spouštíte úlohy, které vyžadují vlastní balíčky s časově náročným krokem kompilace, můžete urychlit vývojovou smyčku vytvořením šablony sady, která určuje vlastní prostředí kontejneru.

Databricks poskytuje sadu výchozích balíčkových šablon, ale můžete také vytvořit vlastní balíčkové šablony. Uživatelé pak mohou inicializovat sady pomocí příkazu inicializace sady, určení výchozí šablony nebo vlastní šablony.

Vytvoření sady pomocí šablony

Pokud chcete k vytvoření sady použít šablonu sady Azure Databricks, použijte příkaz CliDatabricksbundle init, zadejte název šablony, která se má použít, nebo při vytváření sady prostředků v pracovním prostoru vyberte dostupnou šablonu. Viz Vytvořit sadu.

Následující příkaz například vytvoří sadu s použitím výchozí šablony sady Pythonu:

databricks bundle init default-python

Pokud chcete použít vlastní balíček šablon, předejte místní cestu nebo vzdálenou adresu URL šablony do příkazu rozhraní příkazového řádku Databricksbundle init.

Například následující příkaz používá šablonu dab-container-template, která byla vytvořena v Tutoriálu pro vlastní šablonu sady:

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

Pokud nezadáte šablonu, příkaz bundle init vás vyzve k výběru ze sady dostupných výchozích šablon.

výchozí šablony balíčků

Azure Databricks poskytuje následující výchozí šablony sad:

Šablona Popis
default-minimal Šablona pro vytvoření prázdné sady. Tato šablona obsahuje pouze požadované soubory a žádný ukázkový kód a také nakonfiguruje základní proměnné katalogu. Díky tomu můžete rychle vytvářet nové balíčkové projekty. Podívejte se na default-minimal.
default-python Šablona pro použití Pythonu s Databricks Tato šablona vytvoří sadu s úlohou a kanálem ETL a vyžaduje uv. Viz default-python.
default-scala Šablona pro použití Scala s Databricks. Tato šablona vytvoří sadu, která sestaví soubor SCALa JAR nakonfigurovaný pro nasazení do bezserverového výpočetního prostředí. Viz default-scala.
default-sql Šablona pro použití SQL s Databricks Tato šablona obsahuje konfigurační soubor, který definuje úlohu, která spouští dotazy SQL ve službě SQL Warehouse. Viz default-sql.
dbt-sql Šablona, která využívá dbt-core pro místní vývoj a balíčky k nasazení. Tato šablona obsahuje konfiguraci, která definuje úlohu s úlohou dbt, a konfigurační soubor, který definuje profily dbt pro nasazené úlohy dbt. Viz dbt-sql.
mlops-stacks Pokročilá šablona pro full stack pro zahájení nových projektů MLOps Stacks. Viz zásobníky MLOps a Deklarativní automatizační balíčky pro zásobníky MLOps.
pydabs Upravená verze default-python šablony, která místo YAML používá Python pro konfiguraci sady. Prohlédni si pydabs.

Vlastní šablony balíčků

Šablony balíčků používají syntaxi šablon balíčků Go, která poskytuje flexibilitu pro vlastní šablony balíčků, které můžete vytvořit. Podívejte se do dokumentace k šabloně balíčku Go.

Struktura projektu šablony

Minimálně projekt šablony sady musí mít:

  • Soubor databricks_template_schema.json v kořenovém adresáři projektu, který definuje vlastnost promptu uživatele pro název balíčkového projektu. Vizte schéma šablony .
  • databricks.yml.tmpl Soubor umístěný ve template složce, která definuje konfiguraci pro všechny sady vytvořené pomocí šablony. Pokud váš databricks.yml.tmpl soubor odkazuje na jakékoli další *.yml.tmpl šablony konfigurace, zadejte jejich umístění v include mapování. Viz šablon konfigurace.

Struktura složek a zahrnuté soubory ve složce projektu šablony balíčku template se shodují se strukturou a soubory balíčků vytvořených pomocí této šablony. Pokud například chcete, aby šablona vygenerovala sadu s jednoduchým poznámkovým blokem ve složce src a definicí úlohy, která spustí poznámkový blok ve složce resources, uspořádáte projekt šablony takto:

basic-bundle-template
  ├── databricks_template_schema.json
  └── template
      └── {{.project_name}}
          ├── databricks.yml.tmpl
          ├── resources
          │   └── {{.project_name}}_job.yml.tmpl
          └── src
              └── simple_notebook.ipynb

Návod

Název složky projektu a název definičního souboru úlohy v této šabloně sady používá proměnnou šablony. Informace o pomocnících a proměnných šablon najdete v tématu Pomocníci a proměnné šablony.

schéma šablony

Projekt šablony vlastní sady musí obsahovat soubor JSON databricks_template_schema.json v kořenovém adresáři projektu. Tento soubor definuje pole používaná rozhraním příkazového řádku Databricks při spuštění příkazu bundle init, například text výzvy.

Následující základní databricks_template_schema.json soubor definuje vstupní proměnnou project_name projektu sady, která obsahuje zprávu výzvy a výchozí hodnotu. Potom definuje zprávu o úspěchu pro inicializaci projektu sady, která používá hodnotu vstupní proměnné ve zprávě.

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

Pole schématu šablony

Soubor databricks_template_schema.json podporuje definování vstupních proměnných pro shromažďování informací během inicializace sady od uživatele v poli properties a také další pole pro přizpůsobení inicializace.

Vstupní proměnné jsou definovány v poli properties schématu šablony. Každá vstupní proměnná definuje metadata potřebná k zobrazení výzvy uživateli během initalizace svazku. Hodnota proměnné je pak přístupná pomocí syntaxe šablonových proměnných, například {{.project_name}}.

Můžete také nastavit hodnoty některých polí pro přizpůsobení procesu inicializace sady.

Podporovaná pole schématu jsou uvedena v následující tabulce.

Pole schématu Popis
properties Definice vstupních proměnných šablony balíčku Databricks doporučuje definovat alespoň jednu vstupní proměnnou, která je názvem projektu sady.
properties.<variable_name> Název vstupní proměnné.
properties.<variable_name>.default Výchozí hodnota, která se má použít, pokud uživatel nezadá hodnotu s --config-file jako součást příkazu bundle init nebo na příkazovém řádku, když se k ní zobrazí výzva.
properties.<variable_name>.description Zpráva výzvy uživatele přidružená ke vstupní proměnné.
properties.<variable_name>.enum Seznam možných hodnot vlastnosti, například "enum": ["azure", "aws", "gcp"]. Pokud je toto pole definováno, rozhraní příkazového řádku Databricks zobrazí hodnoty v seznamu na příkazovém řádku a vyzve uživatele k výběru hodnoty.
properties.<variable_name>.order Celé číslo, které definuje relativní pořadí vstupních vlastností. Tím se řídí pořadí, ve kterém se na příkazovém řádku zobrazují výzvy k těmto vstupním proměnným.
properties.<variable_name>.pattern Vzor regexp, který se má použít k ověření vstupu uživatele, například "pattern": "^[^ .\\\\/]{3,}$". Podporovanou syntaxi regexp najdete v tématu https://github.com/google/re2/wiki/Syntax.
properties.<variable_name>.pattern_match_failure_message Zpráva zobrazená uživateli, pokud hodnota zadaná uživatelem neodpovídá zadanému vzoru, například Project name must be at least 3 characters long and cannot contain the following characters: \"\\\", \"/\", \" \" and \".\".".
properties.<variable_name>.skip_prompt_if Pokud je toto schéma již uspokojeno stávající konfigurací, přeskočte dotaz na vstupní proměnnou. V takovém případě se místo toho použije výchozí hodnota vlastnosti. Příklad najdete v šabloně mlops-stacks. Pouze const porovnání jsou podporována.
properties.<variable_name>.skip_prompt_if.properties.<previous_variable_name>.const Pokud hodnota pro <previous_variable_name> odpovídá konstantě nakonfigurované v skip_prompt_if, výzva k <variable_name> se přeskočí.
template_dir Cesta k adresáři šablony, například ../default. To umožňuje obecné šablony tím, že umožňuje více databricks_template_schema.json souborů odkazovat na stejný adresář.
welcome_message První zpráva k výstupu před zobrazením výzvy uživatele k zadání vstupu.
success_message Zpráva, která se má vytisknout po úspěšném inicializaci šablony
min_databricks_cli_version Minimální verze semver tohoto rozhraní příkazového řádku Databricks, kterou šablona vyžaduje. databricks bundle init selže, pokud je verze rozhraní příkazového řádku menší než tato verze.
version Vyhrazeno pro budoucí použití. Verze schématu. Používá se k určení, jestli je schéma kompatibilní s aktuální verzí rozhraní příkazového řádku.

Šablony konfigurace

Vlastní šablona sady by měla obsahovat soubor databricks.yml.tmpl ve složce template v projektu šablony sady, který se používá k vytvoření konfiguračního souboru projektu sady databricks.yml. Šablony konfiguračních souborů pro prostředky lze vytvořit ve složce resources. Naplňte tyto soubory šablony konfigurační šablonou YAML.

Následující jednoduché ukázkové šablony konfigurace pro databricks.yml a přidružené *_job.yml vytvářejí název sady a dvě cílová prostředí. Definují úlohu, která spouští notebook v dané sadě, pro sady vytvořené pomocí této šablony. Tyto šablony konfigurace využívají nahrazení balíčků a pomocníky šablon balíčků .

template/{{.project_name}}/databricks.yml.tmpl:

# databricks.yml
# This is the configuration for the bundle {{.project_name}}.

bundle:
  name: {{.project_name}}

include:
  - resources/*.yml

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}}
      # Deploy to a folder whose write access is restricted to the deploying
      # identity. Avoid /Shared, which is writable by all workspace users.
      root_path: /Workspace/Production/.bundle/${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 -}}

template/{{.project_name}}/resources/{{.project_name}}_job.yml.tmpl:

# {{.project_name}}_job.yml
# 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

Pomocníci šablon a proměnné

Pomocné funkce šablon jsou funkce poskytované Databricks, které můžete použít v souborech šablon k získání uživatelsky specifických informací za běhu nebo k interakci s enginem šablon. Můžete také definovat vlastní proměnné šablony.

Pro projekty šablonových sad Databricks jsou k dispozici následující pomocné nástroje. Informace o používání šablon a proměnných Jazyka Go najdete v tématu Šablony Jazyka Go.

Pomocník Popis
{{url}} Alias pro https://pkg.go.dev/net/url#Parse. To umožňuje použití všech metod url.URL.
{{regexp}} Alias pro https://pkg.go.dev/regexp#Compile. To umožňuje použití všech metod regexp.Regexp.
{{random_int}} Vrátí jako int nezáporné pseudonáhodné číslo v polootevřeném intervalu (0,n).
{{uuid}} Vrátí jako řetězec UUID, což je 128bitový (16bajtů) univerzální jedinečný IDentifier definovaný v DOKUMENTU RFC 4122.Toto ID je stabilní po dobu trvání provádění šablony a dá se použít k naplnění pole bundle.uuid v databricks.yml autory šablon.
{{bundle_uuid}} Jedinečné ID balíčku. Více vyvolání této funkce vrátí stejné UUID.
{{pair}} Pár klíč-hodnota. Používá se s pomocníkem map k vygenerování map pro použití v šabloně.
{{map}} Převede seznam dvojic na objekt mapy. To je užitečné při předávání více objektů šablonám definovaným v adresáři knihovny. Vzhledem k tomu, že syntaxe textové šablony Go pro vyvolání šablony umožňuje zadat pouze jeden argument, lze tuto funkci použít k alternativnímu řešení tohoto omezení.
Například v následujícím řádku lze na {{template "my_template" (map (pair "foo" $arg1) (pair "bar" $arg2))}}, $arg1 a $arg2 odkazovat zevnitř my_template jako na .foo a .bar.
{{smallest_node_type}} Vrátí nejmenší typ uzlu.
{{path_separator}} Znak oddělovače cest pro operační systém. To je / pro systémy Unix a \ pro Windows.
{{workspace_host}} Adresa URL hostitele pracovního prostoru, na které je uživatel aktuálně ověřený.
{{user_name}} Celé jméno uživatele, který šablonu inicializuje.
{{short_name}} Krátký název uživatele, který šablonu inicializuje.
{{default_catalog}} Vrátí výchozí katalog pracovních prostorů. Pokud neexistuje výchozí hodnota nebo pokud není povolený katalog Unity, vrátí se prázdný řetězec.
{{is_service_principal}} Určuje, zda je aktuální uživatel servisním principálem.
{{ skip <glob-pattern-relative-to-current-directory> }} Způsobí, že modul šablony přeskočí generování všech souborů a adresářů, které odpovídají vzoru vstupního globu. Příklad najdete v šabloně mlops-stacks.

Pomocníci pro vlastní šablony

Pokud chcete definovat vlastní pomocné rutiny šablon, vytvořte soubor šablony ve složce library projektu šablony a pomocí syntaxe šablon Go definujte pomocné rutiny. Například následující obsah souboru library/variables.tmpl definuje proměnné cli_version a model_name. Pokud se tato šablona používá k inicializaci sady, hodnota proměnné model_name se vytvoří pomocí pole input_project_name definovaného v souboru schématu šablony. Hodnota této hodnoty pole je uživatelský vstup po zobrazení výzvy.

{{ define `cli_version` -}}
    v0.240.0
{{- end }}

{{ define `model_name` -}}
    {{ .input_project_name }}-model
{{- end }}

Úplný příklad najdete v souboru proměnných šablon mlops-stacks.

Otestování šablony sady

Nakonec nezapomeňte šablonu otestovat. Pomocí rozhraní příkazového řádku Databricks můžete například inicializovat novou sadu pomocí šablony definované v předchozích částech:

databricks bundle init basic-bundle-template

Do příkazového řádku What is your bundle project name?zadejte my_test_bundle.

Po vytvoření testovací sady bude výstupem zpráva o úspěchu ze souboru schématu. Pokud prozkoumáte obsah my_test_bundle složky, měli byste vidět následující:

my_test_bundle
   ├── databricks.yml
   ├── resources
   │  └── my_test_bundle_job.yml
   └── src
      └── simple_notebook.ipynb

A soubor a úloha databricks.yml je teď přizpůsobená:

# databricks.yml
# This is the configuration for the bundle my-test-bundle.

bundle:
  name: my_test_bundle

include:
  - resources/*.yml

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
      # Deploy to a folder whose write access is restricted to the deploying
      # identity. Avoid /Shared, which is writable by all workspace users.
      root_path: /Workspace/Production/.bundle/${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

# my_test_bundle_job.yml
# 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

Sdílení vlastní šablony

Pokud chcete sdílet šablonu sady s ostatními uživateli, můžete ji uložit ve správě verzí s libovolným poskytovatelem, kterého Git podporuje a ke kterému mají vaši uživatelé přístup. Chcete-li spustit příkaz bundle init s adresou URL Gitu, ujistěte se, že je soubor databricks_template_schema.json v kořenovém adresáři této adresy URL Gitu.

Návod

Můžete umístit soubor databricks_template_schema.json do jiné složky vzhledem ke kořenovému adresáři balíčku. Potom můžete pomocí bundle init možnosti příkazu --template-dir odkazovat na tuto složku, která obsahuje databricks_template_schema.json soubor.

Konfigurace vlastní složky šablony v pracovním prostoru

Důležité

Tato funkce je v beta verzi.

Vlastní šablony sad lze zpřístupnit pro vytváření sad v pracovním prostoru.

  1. Uložte šablonu sady prostředků do úložiště GitHub a nakonfigurujte složku Gitu pro připojení k ní. Informace o konfiguraci složky Git najdete v tématu Klonování úložiště.

  2. Jako správce účtu nebo pracovního prostoru přejděte do Nastavení v pracovním prostoru. Viz Správa pracovního prostoru.

  3. Klikněte na Vývoj.

  4. V části Deklarativní automatizační sady vyberte složku pro vlastní šablony. Všechny vlastní šablony balíčků musí být k dispozici na kořenové úrovni složky.

    Výběr vlastní složky šablony sady

  5. Když se zobrazí dialogové okno oprávnění, udělte všem uživatelům přístup ke složce pro vlastní šablony nebo vyberte Nepovolit přístup k nastavení podrobnějších oprávnění.

    1. Pokud chcete nastavit podrobnější oprávnění, vyberte tři tečky v libovolné složce a klikněte na Zobrazit podrobnosti.

      Nastavení podrobných oprávnění ke složce Gitu

    2. Na panelu podrobností složky Gitu klikněte na Sdílet.

    3. Zvolte, kdo může upravovat šablony (MŮŽE SPRAVOVAT) a kdo může vytvářet sady pomocí šablon (MŮŽE ZOBRAZIT).

    Další informace o oprávněních najdete v tématu Seznamy ACL složky a seznamy ACL složek Git.

Šablony v této složce jsou nyní k dispozici uživatelům při vytváření balíčků v pracovním prostoru. Podívejte se na Vytvoření balíčku.

Další kroky

  • Last updated on