Konfiguracja pakietu zasobów usługi Databricks
W tym artykule opisano składnię plików konfiguracji pakietu zasobów usługi Databricks, które definiują pakiety zasobów usługi Databricks. Zobacz Co to są pakiety zasobów usługi Databricks?
Aby utworzyć pakiety i pracować z pakietami, zobacz Tworzenie pakietów zasobów usługi Databricks.
Omówienie
Plik konfiguracji pakietu musi być wyrażony w formacie YAML i musi zawierać co najmniej mapowanie pakietów najwyższego poziomu. Każdy pakiet musi zawierać co najmniej jeden (i tylko jeden) plik konfiguracji pakietu o nazwie databricks.yml
. Jeśli istnieje wiele plików konfiguracji pakietu, należy się do nich odwoływać przy databricks.yml
użyciu include
mapowania.
Aby uzyskać szczegółowe informacje na temat każdego mapowania najwyższego poziomu, zobacz Mapowania.
Aby uzyskać więcej informacji na temat języka YAML, zobacz oficjalną specyfikację YAML i samouczek.
Specyfikacja
Poniższa specyfikacja YAML zawiera klucze konfiguracji najwyższego poziomu dla pakietów zasobów usługi Databricks. Aby uzyskać informacje o konfiguracji, zobacz
# This is the default bundle configuration if not otherwise overridden in
# the "targets" top-level mapping.
bundle: # Required.
name: string # Required.
databricks_cli_version: string
cluster_id: string
git:
origin_url: string
branch: string
# These are for any custom variables for use throughout the bundle.
variables:
<some-unique-variable-name>:
description: string
default: string or complex
# These are the default workspace settings if not otherwise overridden in
# the following "targets" top-level mapping.
workspace:
artifact_path: string
auth_type: string
azure_client_id: string # For Azure Databricks only.
azure_environment: string # For Azure Databricks only.
azure_login_app_id: string # For Azure Databricks only. Non-operational and reserved for future use.
azure_tenant_id: string # For Azure Databricks only.
azure_use_msi: true | false # For Azure Databricks only.
azure_workspace_resource_id: string # For Azure Databricks only.
client_id: string # For Databricks on AWS only.
file_path: string
google_service_account: string # For Databricks on Google Cloud only.
host: string
profile: string
root_path: string
state_path: string
# These are the permissions to apply to experiments, jobs, models, and pipelines defined
# in the "resources" mapping.
permissions:
- level: <permission-level>
group_name: <unique-group-name>
- level: <permission-level>
user_name: <unique-user-name>
- level: <permission-level>
service_principal_name: <unique-principal-name>
# These are the default artifact settings if not otherwise overridden in
# the following "targets" top-level mapping.
artifacts:
<some-unique-artifact-identifier>:
build: string
files:
- source: string
path: string
type: string
# These are any additional configuration files to include.
include:
- "<some-file-or-path-glob-to-include>"
- "<another-file-or-path-glob-to-include>"
# This is the identity to use to run the bundle
run_as:
- user_name: <user-name>
- service_principal_name: <service-principal-name>
# These are the default job and pipeline settings if not otherwise overridden in
# the following "targets" top-level mapping.
resources:
clusters:
<some-unique-programmatic-identifier-for-this-cluster>:
# See the REST API create request payload reference for clusters.
dashboards:
<some-unique-programmatic-identifier-for-this-dashboard>:
# See the REST API create request payload reference for dashboards.
experiments:
<some-unique-programmatic-identifier-for-this-experiment>:
# See the REST API create request payload reference for experiments.
jobs:
<some-unique-programmatic-identifier-for-this-job>:
# See REST API create request payload reference for jobs.
models:
<some-unique-programmatic-identifier-for-this-model>:
# See the REST API create request payload reference for models.
pipelines:
<some-unique-programmatic-identifier-for-this-pipeline>:
# See the REST API create request payload reference for Delta Live Tables (pipelines).
schemas:
<some-unique-programmatic-identifier-for-this-schema>:
# See the Unity Catalog schema request payload reference.
volumes:
<some-unique-programmatic-identifier-for-this-volume>:
# See the Unity Catalog volume request payload reference.
# These are any additional files or paths to include or exclude.
sync:
include:
- "<some-file-or-path-glob-to-include>"
- "<another-file-or-path-glob-to-include>"
exclude:
- "<some-file-or-path-glob-to-exclude>"
- "<another-file-or-path-glob-to-exclude>"
paths:
- "<some-file-or-path-to-synchronize>"
# These are the targets to use for deployments and workflow runs. One and only one of these
# targets can be set to "default: true".
targets:
<some-unique-programmatic-identifier-for-this-target>:
artifacts:
# See the preceding "artifacts" syntax.
bundle:
# See the preceding "bundle" syntax.
cluster_id: string
default: true | false
mode: development
presets:
<preset>: <value>
resources:
# See the preceding "resources" syntax.
sync:
# See the preceding "sync" syntax.
variables:
<preceding-unique-variable-name>: <non-default-value>
workspace:
# See the preceding "workspace" syntax.
run_as:
# See the preceding "run_as" syntax.
Przykłady
Uwaga
Przykłady konfiguracji, które demonstrują funkcje pakietu i typowe przypadki użycia pakietów, zobacz Przykłady konfiguracji pakietu i repozytorium przykładów pakietów w usłudze GitHub.
Poniższa przykładowa konfiguracja pakietu określa plik lokalny o nazwie hello.py
, który znajduje się w tym samym katalogu co ten lokalny plik konfiguracji pakietu o nazwie databricks.yml
. Ten notes jest uruchamiany jako zadanie przy użyciu klastra zdalnego z określonym identyfikatorem klastra. Adres URL zdalnego obszaru roboczego oraz poświadczenia do uwierzytelnienia obszaru roboczego są odczytywane z lokalnego profilu konfiguracji użytkownika o nazwie DEFAULT
.
Usługa Databricks zaleca użycie host
mapowania zamiast default
mapowania wszędzie tam, gdzie jest to możliwe, ponieważ sprawia to, że pliki konfiguracji pakietu są bardziej przenośne.
host
Ustawienie mapowania powoduje, że interfejs wiersza polecenia usługi Databricks znajdzie pasujący profil w .databrickscfg
pliku, a następnie użyj pól tego profilu, aby określić typ uwierzytelniania usługi Databricks do użycia. Jeśli w pliku istnieje host
wiele profilów z pasującym .databrickscfg
polem, musisz użyć profile
polecenia , aby poinstruować interfejs wiersza polecenia usługi Databricks o określonym profilu do użycia. Aby zapoznać się z przykładem, zobacz deklarację docelową prod
w dalszej części tej sekcji.
Ta technika umożliwia ponowne użycie oraz zastąpienie definicji i ustawień zadania w resources
bloku:
bundle:
name: hello-bundle
resources:
jobs:
hello-job:
name: hello-job
tasks:
- task_key: hello-task
existing_cluster_id: 1234-567890-abcde123
notebook_task:
notebook_path: ./hello.py
targets:
dev:
default: true
Chociaż następujący plik konfiguracji pakietu jest funkcjonalnie równoważny, nie jest modularyzowany, co nie umożliwia dobrego ponownego użycia. Ponadto ta deklaracja dołącza zadanie do zadania, a nie zastępuje istniejącego zadania:
bundle:
name: hello-bundle
targets:
dev:
default: true
resources:
jobs:
hello-job:
name: hello-job
tasks:
- task_key: hello-task
existing_cluster_id: 1234-567890-abcde123
notebook_task:
notebook_path: ./hello.py
W poniższym przykładzie dodano element docelowy o nazwie prod
, który korzysta z innego adresu URL zdalnego obszaru roboczego oraz poświadczeń uwierzytelniania, odczytywanych z odpowiedniego wpisu .databrickscfg
w pliku host
obiektu wywołującego z określonym adresem URL obszaru roboczego. To zadanie uruchamia ten sam notes, ale używa innego klastra zdalnego z określonym identyfikatorem klastra. Zwróć uwagę, że nie trzeba deklarować notebook_task
mapowania w ramach prod
mapowania, ponieważ wraca do używania notebook_task
mapowania w ramach mapowania najwyższego poziomu resources
, jeśli notebook_task
mapowanie nie jest jawnie zastępowane w ramach prod
mapowania.
bundle:
name: hello-bundle
resources:
jobs:
hello-job:
name: hello-job
tasks:
- task_key: hello-task
existing_cluster_id: 1234-567890-abcde123
notebook_task:
notebook_path: ./hello.py
targets:
dev:
default: true
prod:
workspace:
host: https://<production-workspace-url>
resources:
jobs:
hello-job:
name: hello-job
tasks:
- task_key: hello-task
existing_cluster_id: 2345-678901-fabcd456
Aby zweryfikować, wdrożyć i uruchomić to zadanie w ramach dev
elementu docelowego:
# Because the "dev" target is set to "default: true",
# you do not need to specify "-t dev":
databricks bundle validate
databricks bundle deploy
databricks bundle run hello_job
# But you can still explicitly specify it, if you want or need to:
databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev hello_job
Aby zweryfikować, wdrożyć i uruchomić to zadanie w ramach prod
elementu docelowego:
# You must specify "-t prod", because the "dev" target
# is already set to "default: true":
databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod hello_job
Poniżej przedstawiono poprzedni przykład, ale podzielony na pliki składników w celu jeszcze większej modularyzacji i lepszego ponownego użycia w wielu plikach konfiguracji pakietu. Ta technika umożliwia nie tylko ponowne używanie różnych definicji i ustawień, ale także zamianę dowolnego z tych plików z innymi plikami, które zapewniają zupełnie inne deklaracje:
databricks.yml
:
bundle:
name: hello-bundle
include:
- "bundle*.yml"
bundle.resources.yml
:
resources:
jobs:
hello-job:
name: hello-job
tasks:
- task_key: hello-task
existing_cluster_id: 1234-567890-abcde123
notebook_task:
notebook_path: ./hello.py
bundle.targets.yml
:
targets:
dev:
default: true
prod:
workspace:
host: https://<production-workspace-url>
resources:
jobs:
hello-job:
name: hello-job
tasks:
- task_key: hello-task
existing_cluster_id: 2345-678901-fabcd456
Mapowania
W poniższych sekcjach opisano składnię pliku konfiguracji pakietu według mapowania najwyższego poziomu.
pakiet
Plik konfiguracji pakietu musi zawierać tylko jedno mapowanie najwyższego poziomu bundle
, które kojarzy zawartość pakietu i ustawienia obszaru roboczego usługi Azure Databricks.
To bundle
mapowanie musi zawierać name
mapowanie określające nazwę programową (lub logiczną) pakietu. Poniższy przykład deklaruje pakiet z nazwą hello-bundle
programową (lub logiczną).
bundle:
name: hello-bundle
bundle
Mapowanie może być również elementem podrzędnym jednego lub większej liczby obiektów docelowych w mapowaniu obiektów docelowych najwyższego poziomu. Każde z tych mapowań podrzędnych bundle
określa wszelkie przesłonięcia inne niż domyślne na poziomie docelowym. Jednak wartości mapowania bundle
najwyższego poziomu name
nie można zastąpić na poziomie docelowym.
cluster_id
Mapowanie bundle
może mieć mapowanie podrzędne cluster_id
. To mapowanie umożliwia określenie identyfikatora klastra do użycia jako przesłonięcia dla klastrów zdefiniowanych gdzie indziej w pliku konfiguracji pakietu. Aby uzyskać informacje na temat pobierania identyfikatora klastra, zobacz Adres URL i identyfikator klastra.
Zastępowanie cluster_id
jest przeznaczone tylko dla scenariuszy przeznaczonych tylko do programowania i jest obsługiwane tylko dla obiektu docelowego, który ma mapowanie mode
ustawione na wartość development
. Aby uzyskać więcej informacji na temat target
mapowania, zobacz cele.
compute_id
Uwaga
To ustawienie jest przestarzałe. Zamiast tego użyj cluster_id .
Mapowanie bundle
może mieć mapowanie podrzędne compute_id
. To mapowanie umożliwia określenie identyfikatora klastra do użycia jako przesłonięcia dla klastrów zdefiniowanych gdzie indziej w pliku konfiguracji pakietu.
Git
Możesz pobrać i zastąpić szczegóły kontroli wersji usługi Git skojarzone z pakietem. Jest to przydatne w przypadku dodawania adnotacji do wdrożonych zasobów. Możesz na przykład uwzględnić adres URL pochodzenia repozytorium w opisie wdrażanego modelu uczenia maszynowego.
Za każdym razem, gdy uruchamiasz bundle
polecenie, takie jak validate
, deploy
lub run
, bundle
polecenie wypełnia drzewo konfiguracji polecenia następującymi ustawieniami domyślnymi:
-
bundle.git.origin_url
, który reprezentuje adres URL pochodzenia repozytorium. Jest to ta sama wartość, którą można uzyskać po uruchomieniu poleceniagit config --get remote.origin.url
z sklonowanego repozytorium. Za pomocą podstawiania można odwoływać się do tej wartości z plikami konfiguracji pakietu jako${bundle.git.origin_url}
. -
bundle.git.branch
, który reprezentuje bieżącą gałąź w repozytorium. Jest to ta sama wartość, którą można uzyskać po uruchomieniu poleceniagit branch --show-current
z sklonowanego repozytorium. Za pomocą podstawiania można odwoływać się do tej wartości z plikami konfiguracji pakietu jako${bundle.git.branch}
.
Aby pobrać lub zastąpić ustawienia usługi Git, pakiet musi znajdować się w katalogu skojarzonym z repozytorium Git, na przykład katalogiem lokalnym zainicjowanym przez uruchomienie git clone
polecenia . Jeśli katalog nie jest skojarzony z repozytorium Git, te ustawienia usługi Git są puste.
W razie potrzeby można zastąpić origin_url
ustawienia i branch
w git
mapowaniu mapowania najwyższego poziomu bundle
w następujący sposób:
bundle:
git:
origin_url: <some-non-default-origin-url>
branch: <some-non-current-branch-name>
databricks_cli_version
Mapowanie bundle
może zawierać databricks_cli_version
mapowanie, które ogranicza wersję interfejsu wiersza polecenia usługi Databricks wymaganą przez pakiet. Może to zapobiec problemom spowodowanym użyciem mapowań, które nie są obsługiwane w określonej wersji interfejsu wiersza polecenia usługi Databricks.
Wersja interfejsu wiersza polecenia usługi Databricks jest zgodna z semantyczną wersją , a databricks_cli_version
mapowanie obsługuje określanie ograniczeń wersji. Jeśli bieżąca databricks --version
wartość nie znajduje się w granicach określonych w mapowaniu pakietu databricks_cli_version
, wystąpi błąd podczas databricks bundle validate
wykonywania w pakiecie. W poniższych przykładach pokazano niektóre typowe składnie ograniczeń wersji:
bundle:
name: hello-bundle
databricks_cli_version: "0.218.0" # require Databricks CLI 0.218.0
bundle:
name: hello-bundle
databricks_cli_version: "0.218.*" # allow all patch versions of Databricks CLI 0.218
bundle:
name: my-bundle
databricks_cli_version: ">= 0.218.0" # allow any version of Databricks CLI 0.218.0 or higher
bundle:
name: my-bundle
databricks_cli_version: ">= 0.218.0, <= 1.0.0" # allow any Databricks CLI version between 0.218.0 and 1.0.0, inclusive
Zmiennych
Plik ustawień pakietów może zawierać jedno najwyższego poziomu mapowanie variables
, w którym zdefiniowano zmienne niestandardowe. Dla każdej zmiennej ustaw opcjonalny opis, wartość domyślną, czy zmienna niestandardowa jest typem złożonym, lub wyszukiwanie w celu pobrania wartości identyfikatora, przy użyciu następującego formatu:
variables:
<variable-name>:
description: <variable-description>
default: <optional-default-value>
type: <optional-type-value> # "complex" is the only valid value
lookup:
<optional-object-type>: <optional-object-name>
Uwaga
Przyjmuje się, że zmienne mają być typu string
, chyba że type
jest ustawiona na wartość complex
. Zobacz Definiowanie zmiennej złożonej.
Aby odwołać się do zmiennej niestandardowej w ramach konfiguracji pakietu, użyj podstawienia ${var.<variable_name>}
.
Aby uzyskać więcej informacji na temat zmiennych niestandardowych i podstawień, zobacz Podstawianie i zmienne w pakietach zasobów usługi Databricks.
obszar roboczy
Plik konfiguracji pakietu może zawierać tylko jedno mapowanie najwyższego poziomu workspace
, aby określić domyślne ustawienia obszaru roboczego usługi Azure Databricks do użycia.
Ważne
Prawidłowe ścieżki obszaru roboczego usługi Databricks zaczynają się od /Workspace
lub /Volumes
. Niestandardowe ścieżki obszaru roboczego są automatycznie poprzedzone prefiksem /Workspace
, więc jeśli używasz podstawianie ścieżki obszaru roboczego w ścieżce niestandardowej, takiej jak ${workspace.file_path}
, nie musisz poprzedzać /Workspace
ścieżki.
root_path
To workspace
mapowanie może zawierać mapowanie, root_path
aby określić inną niż domyślną ścieżkę główną do użycia w obszarze roboczym dla wdrożeń i przebiegów przepływu pracy, na przykład:
workspace:
root_path: /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}
Domyślnie w interfejsie root_path
wiersza polecenia usługi Databricks jest używana domyślna ścieżka /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}
, która używa podstawień.
artifact_path
To workspace
mapowanie może również zawierać mapowanie, aby określić inną niż domyślną artifact_path
ścieżkę artefaktu do użycia w obszarze roboczym dla wdrożeń i przebiegów przepływu pracy, na przykład:
workspace:
artifact_path: /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/artifacts
Domyślnie w interfejsie artifact_path
wiersza polecenia usługi Databricks jest używana domyślna ścieżka ${workspace.root}/artifacts
, która używa podstawień.
Uwaga
Mapowanie artifact_path
nie obsługuje ścieżek systemu plików usługi Databricks (DBFS).
file_path
To workspace
mapowanie może również zawierać mapowanie, aby określić inną niż domyślną file_path
ścieżkę pliku do użycia w obszarze roboczym dla wdrożeń i przebiegów przepływu pracy, na przykład:
workspace:
file_path: /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/files
Domyślnie w interfejsie file_path
wiersza polecenia usługi Databricks jest używana domyślna ścieżka ${workspace.root}/files
, która używa podstawień.
state_path
Mapowanie state_path
jest domyślnie ustawione na domyślną ścieżkę ${workspace.root}/state
i reprezentuje ścieżkę w obszarze roboczym, aby przechowywać informacje o stanie programu Terraform dotyczące wdrożeń.
Inne mapowania obszarów roboczych
Mapowanie workspace
może również zawierać następujące opcjonalne mapowania, aby określić mechanizm uwierzytelniania usługi Azure Databricks do użycia. Jeśli nie są one określone w tym workspace
mapowaniu, muszą być określone w workspace
mapowaniu jako element podrzędny co najmniej jednego miejsca docelowego w mapowaniu obiektów docelowych najwyższego poziomu.
Ważne
Należy na stałe wprowadzić wartości dla następujących mapowań workspace
w celu uwierzytelniania w usłudze Azure Databricks. Na przykład nie można określić zmiennych niestandardowych dla wartości tych mapowań, korzystając ze składni ${var.*}
.
Mapowanie
profile
(lub opcje lub--profile
-p
podczas uruchamiania pakietu walidować, wdrażać, uruchamiać i niszczyć polecenia za pomocą interfejsu wiersza polecenia usługi Databricks) określa nazwę profilu konfiguracji do użycia z tym obszarem roboczym na potrzeby uwierzytelniania usługi Azure Databricks. Ten profil konfiguracji odpowiada temu, który został utworzony podczas konfigurowania Databricks CLI.Uwaga
Usługa Databricks zaleca użycie
host
mapowania (lub--profile
-p
opcji podczas uruchamiania pakietu walidowania, wdrażania, uruchamiania i niszczenia poleceń za pomocą interfejsu wiersza polecenia usługi Databricks) zamiastprofile
mapowania, ponieważ sprawia to, że pliki konfiguracji pakietu są bardziej przenośne.host
Ustawienie mapowania powoduje, że interfejs wiersza polecenia usługi Databricks znajdzie pasujący profil w.databrickscfg
pliku, a następnie użyj pól tego profilu, aby określić typ uwierzytelniania usługi Databricks do użycia. Jeśli w pliku istniejehost
wiele profilów z pasującym.databrickscfg
polem, musisz użyćprofile
mapowania (lub--profile
-p
opcji wiersza polecenia), aby poinstruować interfejs wiersza polecenia usługi Databricks o tym, którego profilu użyć. Przykład można znaleźć wprod
deklaracji docelowej w przykładach.Mapowanie
host
określa adres URL obszaru roboczego usługi Azure Databricks. Zobacz Adres URL obszaru roboczego.W przypadku uwierzytelniania maszyny-maszyny (M2M) protokołu OAuth jest używane mapowanie
client_id
. Alternatywnie można ustawić tę wartość w lokalnej zmiennej środowiskowejDATABRICKS_CLIENT_ID
. Możesz też utworzyć profil konfiguracji zclient_id
wartością, a następnie określić nazwę profilu zprofile
mapowaniem (lub za pomocą opcji lub--profile
podczas uruchamiania pakietu weryfikujące, wdrażać, uruchamiać i niszczyć polecenia za pomocą-p
interfejsu wiersza polecenia usługi Databricks). Zobacz Autoryzowanie nienadzorowanego dostępu do zasobów usługi Azure Databricks przy użyciu jednostki usługi przy użyciu protokołu OAuth.Uwaga
Nie można określić wartości wpisu tajnego OAuth usługi Azure Databricks w pliku konfiguracji pakietu. Zamiast tego ustaw lokalną zmienną środowiskową
DATABRICKS_CLIENT_SECRET
. Możesz też dodaćclient_secret
wartość do profilu konfiguracji, a następnie określić nazwę profilu zprofile
mapowaniem (lub za pomocą opcji lub--profile
podczas uruchamiania pakietu weryfikowania, wdrażania, uruchamiania i niszczenia poleceń za pomocą-p
interfejsu wiersza polecenia usługi Databricks).W przypadku uwierzytelniania interfejsu wiersza polecenia platformy Azure jest używane mapowanie
azure_workspace_resource_id
. Alternatywnie można ustawić tę wartość w lokalnej zmiennej środowiskowejDATABRICKS_AZURE_RESOURCE_ID
. Możesz też utworzyć profil konfiguracji zazure_workspace_resource_id
wartością, a następnie określić nazwę profilu zprofile
mapowaniem (lub za pomocą opcji lub--profile
podczas uruchamiania pakietu weryfikujące, wdrażać, uruchamiać i niszczyć polecenia za pomocą-p
interfejsu wiersza polecenia usługi Databricks). Zobacz Uwierzytelnianie interfejsu wiersza polecenia platformy Azure.W przypadku uwierzytelniania wpisów tajnych klienta platformy Azure z jednostkami usługi są używane mapowania
azure_workspace_resource_id
,azure_tenant_id
iazure_client_id
. Alternatywnie można ustawić te wartości w lokalnych zmiennych środowiskowychDATABRICKS_AZURE_RESOURCE_ID
,ARM_TENANT_ID
iARM_CLIENT_ID
, odpowiednio. Możesz też utworzyć profil konfiguracji z wartościamiazure_workspace_resource_id
,azure_tenant_id
iazure_client_id
, a następnie określić nazwę profilu za pomocą mapowaniaprofile
(lub przy użyciu opcji--profile
lub-p
podczas uruchamiania komendy walidacji, wdrażania, uruchamiania i niszczenia, korzystając z interfejsu wiersza poleceń Databricks CLI). Zobacz Uwierzytelnianie jednostki usługi MS Entra.Uwaga
Nie można określić wartości wpisu tajnego klienta platformy Azure w pliku konfiguracji pakietu. Zamiast tego ustaw lokalną zmienną środowiskową
ARM_CLIENT_SECRET
. Możesz też dodaćazure_client_secret
wartość do profilu konfiguracji, a następnie określić nazwę profilu zprofile
mapowaniem (lub za pomocą opcji lub--profile
podczas uruchamiania pakietu weryfikowania, wdrażania, uruchamiania i niszczenia poleceń za pomocą-p
interfejsu wiersza polecenia usługi Databricks).W przypadku uwierzytelniania tożsamości zarządzanych platformy
azure_use_msi
Azure używane są mapowania ,azure_client_id
iazure_workspace_resource_id
. Alternatywnie można ustawić te wartości w lokalnych zmiennych środowiskowychARM_USE_MSI
,ARM_CLIENT_ID
iDATABRICKS_AZURE_RESOURCE_ID
, odpowiednio. Możesz też utworzyć profil konfiguracji z wartościamiazure_use_msi
,azure_client_id
iazure_workspace_resource_id
, a następnie określić nazwę profilu za pomocą mapowaniaprofile
(lub przy użyciu opcji--profile
lub-p
podczas uruchamiania komendy walidacji, wdrażania, uruchamiania i niszczenia, korzystając z interfejsu wiersza poleceń Databricks CLI). Zobacz Uwierzytelnianie tożsamości zarządzanych platformy Azure.Mapowanie
azure_environment
określa typ środowiska platformy Azure (na przykład Publiczny, UsGov, Chiny i Niemcy) dla określonego zestawu punktów końcowych interfejsu API. Domyślna wartość toPUBLIC
. Alternatywnie można ustawić tę wartość w lokalnej zmiennej środowiskowejARM_ENVIRONMENT
. Możesz też dodaćazure_environment
wartość do profilu konfiguracji, a następnie określić nazwę profilu zprofile
mapowaniem (lub za pomocą opcji lub--profile
podczas uruchamiania pakietu weryfikowania, wdrażania, uruchamiania i niszczenia poleceń za pomocą-p
interfejsu wiersza polecenia usługi Databricks).Mapowanie
azure_login_app_id
nie działa i jest zarezerwowane do użytku wewnętrznego.Mapowanie
auth_type
określa typ uwierzytelniania usługi Azure Databricks do użycia, szczególnie w przypadkach, gdy interfejs wiersza polecenia usługi Databricks wnioskowa nieoczekiwany typ uwierzytelniania. Zobacz Autoryzacja dostępu do zasobów Azure Databricks.
Uprawnienia
Mapowanie najwyższego poziomu permissions
określa co najmniej jeden poziom uprawnień, który ma być stosowany do wszystkich zasobów zdefiniowanych w pakiecie. Jeśli chcesz zastosować uprawnienia do określonego zasobu, zobacz Definiowanie uprawnień dla określonego zasobu.
Dozwolone poziomy uprawnień najwyższego poziomu to CAN_VIEW
, CAN_MANAGE
i CAN_RUN
.
Poniższy przykład w pliku konfiguracji pakietu definiuje poziomy uprawnień dla użytkownika, grupy i jednostki usługi, które są stosowane do wszystkich zadań, potoków, eksperymentów i modeli zdefiniowanych w resources
pakiecie:
permissions:
- level: CAN_VIEW
group_name: test-group
- level: CAN_MANAGE
user_name: someone@example.com
- level: CAN_RUN
service_principal_name: 123456-abcdef
Artefakty
Mapowanie najwyższego poziomu artifacts
określa co najmniej jeden artefakt, który jest automatycznie kompilowany podczas wdrożeń pakietu i może być używany w kolejnych uruchomieniach pakietu. Każdy artefakt podrzędny obsługuje następujące mapowania:
-
type
jest wymagany w przypadku kompilacji `wheel` dla Pythona. Aby skompilować plik wheel języka Python przed wdrożeniem, ustaw go nawhl
. Aby utworzyć inne artefakty, to ustawienie nie musi być określone. -
path
jest opcjonalną ścieżką. Ścieżki są zależne od lokalizacji pliku konfiguracji pakietu. W przypadku budowy Python wheel jest to ścieżka do plikusetup.py
Python wheel. Jeślipath
nie jest uwzględniona, interfejs wiersza polecenia usługi Databricks próbuje znaleźć pliksetup.py
pliku koła Python w katalogu głównym pakietu. -
files
jest opcjonalnym mapowaniem zawierającym mapowaniesource
podrzędne, którego można użyć do określenia utworzonych artefaktów. Ścieżki są powiązane z lokalizacją pliku konfiguracji pakietu. -
build
jest opcjonalnym zestawem poleceń kompilacji innych niż domyślne, które mają być uruchamiane lokalnie przed wdrożeniem. W przypadku kompilacji wheel języka Python interfejs wiersza polecenia usługi Databricks zakłada, że może znaleźć lokalną instalację pakietu języka Pythonwheel
do uruchamiania kompilacji i uruchamiapython setup.py bdist_wheel
polecenie domyślnie podczas każdego wdrożenia pakietu. Aby określić wiele poleceń kompilacji, należy oddzielić każde polecenie podwójnymi znakami i (&&
).
Poniższa przykładowa konfiguracja kompiluje koło przy użyciu poezji. Aby uzyskać kompletny przykładowy pakiet, który używa artifacts
do tworzenia koła, zobacz Develop a Python wheel file using Databricks Asset Bundles.
artifacts:
default:
type: whl
build: poetry build
path: .
Przykładowa konfiguracja, która kompiluje plik JAR i przekazuje go do Unity Catalog, zobacz pakiet, który przekazuje plik JAR do Unity Catalog.
Napiwek
Możesz zdefiniować, połączyć i zastąpić ustawienia artefaktów w pakietach zgodnie z opisem w Definiowanie ustawień artefaktów w pakietach zasobów usługi Databricks.
zawierać
Tablica include
określa listę ścieżek globs zawierających pliki konfiguracji do uwzględnienia w pakiecie. Te globy ścieżki są względem lokalizacji pliku konfiguracji pakietu, w którym określono globy ścieżki.
Interfejs wiersza polecenia usługi Databricks domyślnie nie zawiera żadnych plików konfiguracji w pakiecie. Należy użyć tablicy include
, aby określić dowolne i wszystkie pliki konfiguracji do uwzględnienia w pakiecie, innym niż databricks.yml
sam plik.
Ta include
tablica może być wyświetlana tylko jako mapowanie najwyższego poziomu.
Poniższa przykładowa konfiguracja obejmuje trzy pliki konfiguracji. Te pliki znajdują się w tym samym folderze co plik konfiguracji pakietu:
include:
- "bundle.artifacts.yml"
- "bundle.resources.yml"
- "bundle.targets.yml"
Poniższa przykładowa konfiguracja obejmuje wszystkie pliki z nazwami plików rozpoczynającymi się od i kończącymi się bundle
na .yml
. Te pliki znajdują się w tym samym folderze co plik konfiguracji pakietu:
include:
- "bundle*.yml"
zasoby
Mapowanie resources
określa informacje o zasobach usługi Azure Databricks używanych przez pakiet.
To mapowanie resources
może występować jako mapowanie poziomu najwyższego lub może być elementem podrzędnym jednego lub więcej celów w mapowaniu celów najwyższego poziomu , i obejmuje zero lub jeden z obsługiwanych typów zasobów. Każde mapowanie typu zasobu zawiera co najmniej jedną pojedynczą deklarację zasobów, która musi mieć unikatową nazwę. Te indywidualne deklaracje zasobów używają ładunku żądania operacji tworzenia odpowiadającego obiektu wyrażonego w yaML, aby zdefiniować zasób. Obsługiwane właściwości zasobu to obsługiwane pola odpowiedniego obiektu.
Ładunki żądań operacji tworzenia są udokumentowane w dokumentacji interfejsu API REST usługi Databricks, a databricks bundle schema
polecenie zwraca wszystkie obsługiwane schematy obiektów. Ponadto polecenie zwraca ostrzeżenia, databricks bundle validate
jeśli w plikach konfiguracji pakietu znajdują się nieznane właściwości zasobu.
Poniższa przykładowa konfiguracja definiuje zasób zadania:
resources:
jobs:
hello-job:
name: hello-job
tasks:
- task_key: hello-task
existing_cluster_id: 1234-567890-abcde123
notebook_task:
notebook_path: ./hello.py
Aby uzyskać więcej informacji na temat zasobów obsługiwanych w pakietach, a także typowych konfiguracji i przykładów, zobacz zasoby pakietów zasobów Databricks i przykłady konfiguracji pakietów .
synchronizacja
Mapowanie sync
umożliwia skonfigurowanie plików będących częścią wdrożeń pakietu.
dołączanie i wykluczanie
Mapowania include
i exclude
w ramach mapowania sync
określają listę plików lub folderów do uwzględnienia w ramach wdrożeń pakietów lub ich wykluczania w zależności od następujących reguł:
- Na bazie jakiejkolwiek listy wzorców plików i ścieżek znajdującej się w pliku
.gitignore
w katalogu głównym pakietu, mapowanieinclude
może zawierać listę wzorców plików, wzorców ścieżek lub obu, względem katalogu głównego pakietu, aby jednoznacznie dołączyć. - Na podstawie dowolnej listy globów plików i ścieżek w pliku
.gitignore
w katalogu głównym pakietu oraz listy globów plików i ścieżek w mapowaniuinclude
, mapowanieexclude
może zawierać listę globów plików, globów ścieżek lub obu elementów względem katalogu głównego pakietu, aby jawnie określić elementy do wykluczenia.
Wszystkie ścieżki do określonych plików i folderów są powiązane z lokalizacją pliku konfiguracji pakietu, w którym są określone.
Składnia wzorców plików include
i exclude
ścieżek są zgodne ze standardową .gitignore
składnią wzorca. Zobacz format wzorca gitignore.
Jeśli na przykład następujący .gitignore
plik zawiera następujące wpisy:
.databricks
my_package/dist
Plik konfiguracji pakietu zawiera następujące include
mapowanie:
sync:
include:
- my_package/dist/*.whl
Następnie uwzględniane są wszystkie pliki w my_package/dist
folderze z rozszerzeniem *.whl
pliku. Żadne inne pliki w folderze my_package/dist
nie są uwzględniane.
Jeśli jednak plik konfiguracji pakietu zawiera również następujące exclude
mapowanie:
sync:
include:
- my_package/dist/*.whl
exclude:
- my_package/dist/delete-me.whl
Następnie wszystkie pliki w folderze my_package/dist
z rozszerzeniem *.whl
pliku , z wyjątkiem pliku o nazwie delete-me.whl
, są uwzględniane. Wszystkie inne pliki w folderze my_package/dist
również nie są uwzględniane.
Mapowanie sync
można również zadeklarować w targets
mapowaniu dla określonego celu. Każde sync
mapowanie zadeklarowane w obiekcie docelowym jest scalane z dowolnymi deklaracjami mapowania najwyższego poziomu sync
. Na przykład kontynuując poprzedni przykład, następujące include
mapowanie na targets
poziomie scala się z include
mapowaniem na najwyższym poziomie sync
:
targets:
dev:
sync:
include:
- my_package/dist/delete-me.whl
Ścieżki
Mapowanie sync
może zawierać paths
mapowanie określające ścieżki lokalne do synchronizacji z obszarem roboczym. Mapowanie paths
umożliwia udostępnianie wspólnych plików w pakietach i może służyć do synchronizowania plików znajdujących się poza katalogem głównym pakietu. (Katalog główny pakietu jest lokalizacją pliku databricks.yml). Jest to szczególnie przydatne, gdy masz jedno repozytorium, które hostuje wiele pakietów i chce udostępniać biblioteki, pliki kodu lub konfigurację.
Określone ścieżki muszą być względne w odniesieniu do plików i katalogów zakotwiczonych w folderze, w którym ustawiono mapowanie paths
. Jeśli jedna lub więcej wartości ścieżki przechodzi w górę katalogu do przodka katalogu głównego pakietu, ścieżka główna jest dynamicznie ustalana, aby zapewnić, że struktura folderów pozostaje nienaruszona. Jeśli na przykład folder główny pakietu ma nazwę my_bundle
, ta konfiguracja jest synchronizowana databricks.yml
z common
folderem znajdującym się na jednym poziomie powyżej katalogu głównego pakietu i samym katalogem głównym pakietu:
sync:
paths:
- ../common
- .
Wdrożenie tego pakietu powoduje następującą strukturę folderów w obszarze roboczym:
common/
common_file.txt
my_bundle/
databricks.yml
src/
...
Cele
Mapowanie targets
określa co najmniej jeden kontekst, w którym mają być uruchamiane przepływy pracy usługi Azure Databricks. Każdy element docelowy to unikatowa kolekcja artefaktów, ustawień obszaru roboczego usługi Azure Databricks oraz szczegółów zadania lub potoku usługi Azure Databricks.
Mapowanie targets
składa się z co najmniej jednego mapowania docelowego, które musi mieć unikatową nazwę programową (lub logiczną).
To targets
mapowanie jest opcjonalne, ale zdecydowanie zalecane. Jeśli zostanie określony, może być wyświetlany tylko jako mapowanie najwyższego poziomu.
Ustawienia w obszarze roboczym najwyższego poziomu
Obiekt docelowy może również zastąpić wartości dowolnych zmiennych najwyższego poziomu .
domyślna
Aby określić domyślną wartość docelową dla poleceń pakietu, ustaw mapowanie default
na wartość true
. Na przykład ten obiekt docelowy o nazwie dev
jest domyślnym obiektem docelowym:
targets:
dev:
default: true
Jeśli domyślny element docelowy nie jest skonfigurowany lub chcesz zweryfikować, wdrożyć i uruchomić zadania lub potoki w określonym obiekcie docelowym, użyj -t
opcji poleceń pakietu.
Następujące polecenia weryfikują, wdrażają i uruchamiają w my_job
obiektach dev
docelowych i prod
:
databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev my_job
databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod my_job
W poniższym przykładzie zadeklarowane są dwa cele. Pierwszy element docelowy ma nazwę dev
i jest domyślnym elementem docelowym używanym, gdy dla poleceń pakietu nie określono żadnego elementu docelowego. Drugi element docelowy ma nazwę prod
i jest używany tylko wtedy, gdy ten element docelowy jest określony dla poleceń pakietu.
targets:
dev:
default: true
prod:
workspace:
host: https://<production-workspace-url>
tryb i ustawienia wstępne
Aby ułatwić rozwój i stosowanie najlepszych praktyk CI/CD, pakiety zasobów Databricks oferują tryby wdrażania dla celów, które określają domyślne zachowania dla przepływów pracy przedprodukcyjnej i produkcyjnej. Niektóre zachowania można również konfigurować. Aby uzyskać szczegółowe informacje, zobacz Tryby wdrażania pakietu zasobów usługi Databricks.
Napiwek
Aby ustawić tożsamości uruchamiania dla pakietów, można określić run_as
dla każdego obiektu docelowego, zgodnie z opisem w Określanie tożsamości przebiegu dla przepływu pracy pakietów zasobów usługi Databricks.
Aby określić, że element docelowy jest traktowany jako cel rozwoju, dodaj mapowanie mode
ustawione na development
. Aby określić, że element docelowy jest traktowany jako cel produkcyjny, dodaj mapowanie mode
ustawione na production
. Na przykład ten obiekt docelowy o nazwie prod
jest traktowany jako docelowy produkt produkcyjny:
targets:
prod:
mode: production
Niektóre zachowania można dostosować przy użyciu presets
mapowania. Aby uzyskać listę dostępnych ustawień wstępnych, zobacz Niestandardowe ustawienia wstępne. W poniższym przykładzie przedstawiono dostosowany docelowy obiekt produkcyjny, który prefiksy i tagi wszystkich zasobów produkcyjnych:
targets:
prod:
mode: production
presets:
name_prefix: "production_" # prefix all resource names with production_
tags:
prod: true
Jeśli ustawiono zarówno mode
, jak i presets
, ustawienia wstępne zastępują zachowanie trybu domyślnego. Ustawienia poszczególnych zasobów zastępują ustawienia wstępne. Jeśli na przykład harmonogram jest ustawiony na UNPAUSED
, ale ustawienie wstępne trigger_pause_status
jest ustawione na PAUSED
, harmonogram zostanie wznowiony.