Migreren van dbx naar bundels

Artikel
10/09/2024

Belangrijk

Databricks raadt u aan om Databricks Asset Bundles te gebruiken in plaats van dbx databricks Labs. Verwante artikelen over dbx zijn buiten gebruik gesteld en worden mogelijk niet bijgewerkt.

In dit artikel wordt beschreven hoe u projecten migreert voor dbx Databricks Labs naar Databricks Asset Bundles. Zie Inleiding tot dbx door Databricks Labs en wat zijn Databricks Asset Bundles?.

Voordat u migreert, moet u rekening houden met de volgende beperkingen en functievergelijkingen tussen dbx Databricks Labs en Databricks Asset Bundles.

Beperkingen

De volgende functionaliteit die wordt ondersteund in dbx Databricks Labs is beperkt, bestaat niet of vereist tijdelijke oplossingen in Databricks Asset Bundles.

Het bouwen van JAR-artefacten wordt niet ondersteund in bundels.
FUSE-notatie voor werkruimtepaden wordt niet ondersteund in bundels (bijvoorbeeld /Workspace/<path>/<filename>). U kunt echter bundels instrueren voor het genereren van FUSE-werkruimtepaden tijdens implementaties met behulp van notatie, zoals /Workspace/${bundle.file_path}/<filename>.

Functievergelijkingen

Voordat u migreert, moet u zien hoe de volgende functies voor dbx Databricks Labs worden geïmplementeerd in Databricks Asset Bundles.

Sjablonen en projecten

dbx ondersteuning bieden voor Jinja-sjablonen. U kunt Jinja-sjablonen opnemen in de implementatieconfiguratie en omgevingsvariabelen doorgeven inline of via een variabelenbestand. Hoewel dit niet wordt aanbevolen, dbx biedt ook experimentele ondersteuning voor aangepaste gebruikersfuncties.

Bundels bieden ondersteuning voor Go-sjablonen voor hergebruik van configuraties. Gebruikers kunnen bundels maken op basis van vooraf gemaakte sjablonen. Er is bijna volledige pariteit voor templating, met uitzondering van aangepaste gebruikersfuncties.

Buildbeheer

dbx biedt bouwondersteuning via pip wheel, Poëzie en Flit. Gebruikers kunnen de build-optie opgeven in de build sectie van het bestand van een project deployment.yml .

Met bundels kunnen gebruikers Python wheel-bestanden bouwen, implementeren en uitvoeren. Gebruikers kunnen gebruikmaken van de ingebouwde whl vermelding in het bestand van databricks.yml een bundel.

Code synchroniseren, implementeren en uitvoeren

dbxmaakt het uploaden van code afzonderlijk mogelijk van het genereren van werkruimtebronnen zoals Azure Databricks-taken.

Bundels uploaden altijd code en maken of bijwerken van werkruimtebronnen tegelijk. Dit vereenvoudigt implementaties en voorkomt blokkerende voorwaarden voor taken die al worden uitgevoerd.

Een dbx-project migreren naar een bundel

Nadat u de voorgaande beperkingen en functievergelijkingen hebt genoteerd tussen dbx Databricks Labs en Databricks Asset Bundles, kunt u migreren van dbx naar bundels.

Databricks raadt aan om een dbx projectmigratie te starten, uw project in de oorspronkelijke map te houden dbx en dat u een afzonderlijke, lege map hebt waarin u de inhoud van het oorspronkelijke dbx project kopieert. Deze afzonderlijke map is uw nieuwe bundel. U kunt onverwachte problemen ondervinden als u begint met het converteren van uw dbx project in de oorspronkelijke map naar een bundel en vervolgens een aantal fouten maakt of opnieuw wilt beginnen vanaf het begin,

Stap 1: De Databricks CLI installeren en instellen

Databricks Asset Bundles is algemeen beschikbaar in Databricks CLI versie 0.218.0 en hoger. Als u Databricks CLI versie 0.218.0 of hoger al hebt geïnstalleerd en ingesteld, gaat u verder met stap 2.

Notitie

Bundels zijn niet compatibel met Databricks CLI-versies 0.18 en lager.

Installeer of werk deze bij naar Databricks CLI versie 0.218.0 of hoger. Zie De Databricks CLI installeren of bijwerken.
Stel de Databricks CLI in voor verificatie met uw Azure Databricks-werkruimten, bijvoorbeeld met behulp van persoonlijke toegangstokenverificatie van Azure Databricks. Zie Verificatie voor de Databricks CLI voor andere Azure Databricks-verificatietypen.

Stap 2: het configuratiebestand voor de bundel maken

Als u een IDE zoals Visual Studio Code, PyCharm Professional of IntelliJ IDEA Ultimate gebruikt die ondersteuning biedt voor YAML-bestanden en JSON-schemabestanden, kunt u uw IDE niet alleen gebruiken om het bundelconfiguratiebestand te maken, maar om de syntaxis en opmaak van het bestand te controleren en als volgt hints voor het voltooien van code op te geven.

Visual Studio Code

Voeg ondersteuning voor YAML-taalservers toe aan Visual Studio Code, bijvoorbeeld door de YAML-extensie te installeren vanuit Visual Studio Code Marketplace.
Genereer het JSON-schemabestand van de Databricks Asset Bundle-configuratie met behulp van de Databricks CLI om de bundle schema opdracht uit te voeren en de uitvoer om te leiden naar een JSON-bestand. Genereer bijvoorbeeld als volgt een bestand met de naam bundle_config_schema.json in de huidige map:
```
databricks bundle schema > bundle_config_schema.json
```
Gebruik Visual Studio Code om een bundelconfiguratiebestand te maken of te openen in de huidige map. Volgens de conventie heeft dit bestand de naam databricks.yml.
Voeg de volgende opmerking toe aan het begin van uw bundelconfiguratiebestand:
```
# yaml-language-server: $schema=bundle_config_schema.json
```
Notitie

Als het JSON-schemabestand van uw Databricks Asset Bundle-configuratie zich in een ander pad bevindt, vervangt bundle_config_schema.json u in de voorgaande opmerking het volledige pad naar uw schemabestand.
Gebruik de functies van de YAML-taalserver die u eerder hebt toegevoegd. Zie de documentatie van uw YAML-taalserver voor meer informatie.

PyCharm Professional

Genereer het JSON-schemabestand van de Databricks Asset Bundle-configuratie met behulp van de Databricks CLI om de bundle schema opdracht uit te voeren en de uitvoer om te leiden naar een JSON-bestand. Genereer bijvoorbeeld als volgt een bestand met de naam bundle_config_schema.json in de huidige map:
```
databricks bundle schema > bundle_config_schema.json
```
Configureer PyCharm om het JSON-schemabestand voor de bundelconfiguratie te herkennen en voltooi vervolgens de toewijzing van het JSON-schema door de instructies in Een aangepast JSON-schema configureren te volgen.
Gebruik PyCharm om een bundelconfiguratiebestand te maken of te openen. Volgens de conventie heeft dit bestand de naam databricks.yml. Terwijl u typt, controleert PyCharm op de syntaxis en opmaak van het JSON-schema en worden hints geboden voor het voltooien van code.

IntelliJ IDEA Ultimate

Genereer het JSON-schemabestand van de Databricks Asset Bundle-configuratie met behulp van de Databricks CLI om de bundle schema opdracht uit te voeren en de uitvoer om te leiden naar een JSON-bestand. Genereer bijvoorbeeld als volgt een bestand met de naam bundle_config_schema.json in de huidige map:
```
databricks bundle schema > bundle_config_schema.json
```
Configureer IntelliJ IDEA om het JSON-schemabestand voor bundelconfiguratie te herkennen en voltooi vervolgens de toewijzing van het JSON-schema door de instructies in Een aangepast JSON-schema configureren te volgen.
Gebruik IntelliJ IDEA om een bundelconfiguratiebestand te maken of te openen. Volgens de conventie heeft dit bestand de naam databricks.yml. Terwijl u typt, controleert IntelliJ IDEA op de syntaxis en opmaak van het JSON-schema en worden hints geboden voor het voltooien van code.

Stap 3: Dbx-projectinstellingen converteren naar databricks.yml

Converteer de instellingen in het dbx projectbestand .dbx/project.json naar de equivalente instellingen in het bestand van databricks.yml uw bundel. Zie Dbx-projectinstellingen converteren naar databricks.yml voor meer informatie.

Stap 4: Dbx-implementatie-instellingen converteren naar databricks.yml

Converteer de instellingen in de map van conf uw dbx project naar de equivalente instellingen in het bestand van databricks.yml uw bundel. Zie Dbx-implementatie-instellingen converteren naar databricks.yml voor meer informatie.

Stap 5: De bundel valideren

Voordat u artefacten implementeert of een Azure Databricks-taak, een Delta Live Tables-pijplijn of een MLOps-pijplijn uitvoert, moet u ervoor zorgen dat uw bundelconfiguratiebestand syntactisch juist is. Voer hiervoor de bundle validate opdracht uit vanuit de hoofdmap van de bundel:

databricks bundle validate

Zie Een bundel valideren voor meer informatie.bundle validate

Stap 6: De bundel implementeren

Als u opgegeven lokale artefacten wilt implementeren in de externe werkruimte, voert u de bundle deploy opdracht uit vanuit de hoofdmap van de bundel. Als er geen opdrachtopties zijn opgegeven, wordt het standaarddoel gebruikt dat is gedeclareerd in het configuratiebestand van de bundel:

databricks bundle deploy

Als u de artefacten in de context van een specifiek doel wilt implementeren, geeft u de -t optie (of --target) op, samen met de naam van het doel, zoals gedeclareerd in het bundelconfiguratiebestand. Bijvoorbeeld voor een doel dat is gedeclareerd met de naam development:

databricks bundle deploy -t development

Zie Een bundel implementeren voor meer informatie.bundle deploy

Tip

U kunt bundelgedefinieerde taken en pijplijnen koppelen aan bestaande taken en pijplijnen in de Azure Databricks-werkruimte om ze gesynchroniseerd te houden. Zie Bind-bundelbronnen.

Stap 7: De bundel uitvoeren

Als u een specifieke taak of pijplijn wilt uitvoeren, voert u de bundle run opdracht uit vanuit de hoofdmap van de bundel. U moet de taak of pijplijn opgeven die in het bundelconfiguratiebestand is gedeclareerd. Als de -t optie niet is opgegeven, wordt het standaarddoel gebruikt dat is gedeclareerd in het configuratiebestand van de bundel. Als u bijvoorbeeld een taak wilt uitvoeren met de naam hello_job in de context van het standaarddoel:

databricks bundle run hello_job

Als u een taak wilt uitvoeren die is benoemd hello_job in de context van een doel dat is gedeclareerd met de naam development:

databricks bundle run -t development hello_job

Zie Een taak of pijplijn uitvoeren voor meer informatie.bundle run

(Optioneel) Stap 8: De bundel voor CI/CD configureren met GitHub

Als u GitHub voor CI/CD gebruikt, kunt u GitHub Actions gebruiken om de databricks bundle deploy en databricks bundle run opdrachten automatisch uit te voeren, op basis van specifieke GitHub-werkstroomevenementen en andere criteria. Zie Een CI/CD-werkstroom uitvoeren met een Databricks Asset Bundle en GitHub Actions.

Dbx-projectinstellingen converteren naar databricks.yml

Projectinstellingen dbxzijn standaard in een bestand met de naam project.json in de map van .dbx het project. Zie de projectbestandsreferentie.

Voor bundels zijn bundelconfiguraties standaard in een bestand met de naam in databricks.yml de hoofdmap van de bundel. Zie de configuratie van Databricks Asset Bundle.

Voor een conf/project.json bestand met de volgende voorbeeldinhoud:

{
  "environments": {
    "default": {
      "profile": "charming-aurora",
      "storage_type": "mlflow",
      "properties": {
        "workspace_directory": "/Workspace/Shared/dbx/charming_aurora",
        "artifact_location": "/Workspace/Shared/dbx/projects/charming_aurora"
      }
    }
  },
  "inplace_jinja_support": true
}

Het bijbehorende databricks.yml bestand is als volgt:

bundle:
  name: <some-unique-bundle-name>

targets:
  default:
    workspace:
      profile: charming-aurora
      root_path: /Shared/dbx/charming_aurora
      artifact_path: /Shared/dbx/projects/charming_aurora
    resources:
      # See an example "resources" mapping in the following section.

De volgende objecten in het voorgaande conf/project.json voorbeeldbestand worden niet ondersteund in databricks.yml bestanden en hebben geen tijdelijke oplossingen:

inplace_jinja_support
storage_type

De volgende aanvullende toegestane objecten in conf/project.json bestanden worden niet ondersteund in databricks.yml bestanden en hebben geen tijdelijke oplossingen:

enable-context-based-upload-for-execute
enable-failsafe-cluster-reuse-with-assets

Dbx-implementatie-instellingen converteren naar databricks.yml

Implementatie-instellingen dbxbevinden zich standaard in een bestand in de map van conf het project. Zie naslaginformatie over implementatiebestanden. Het bestand met implementatie-instellingen heeft standaard een van de volgende bestandsnamen:

deployment.yml
deployment.yaml
deployment.json
deployment.yml.j2
deployment.yaml.j2
deployment.json.j2

Voor bundels zijn implementatie-instellingen standaard in een bestand met de naam databricks.yml in de hoofdmap van de bundel. Zie de configuratie van Databricks Asset Bundle.

Voor een conf/deployment.yml bestand met de volgende voorbeeldinhoud:

build:
  python: "pip"

environments:
  default:
    workflows:
      - name: "workflow1"
        tasks:
          - task_key: "task1"
            python_wheel_task:
              package_name: "some-pkg"
              entry_point: "some-ep"