Migrer vers le moteur de déploiement direct

Declarative Automation Bundles a été initialement construit sur la base du fournisseur Databricks Terraform pour gérer les déploiements. Cependant, les versions 0,279.0 et supérieures du CLI Databricks prennent en charge deux moteurs de déploiement différents : *terraform* et *direct*. Le moteur de déploiement direct offre des avantages significatifs et ne dépend pas de Terraform.

Les nouveaux bundles créés à l'aide de Databricks CLI version 1.3.0 et supérieure utilisent par default le moteur de déploiement direct. Les bundles créés à l’aide de versions antérieures de l’interface CLI peuvent être migrés du moteur de déploiement Terraform vers le moteur de déploiement direct à l’aide des étapes de migration décrites sur cette page.

important

Databricks recommande de migrer vers le moteur direct, car le moteur de déploiement Terraform sera bientôt déprécié et le moteur de déploiement direct deviendra le default. Voir Les Declarative Automation Bundles utiliseront bientôt par default le moteur de déploiement direct.

Avantages du déploiement direct

Le nouveau moteur de déploiement direct utilise le Databricks Go SDK et présente les avantages suivants :

• Déploiements plus rapides : les déploiements groupés sont jusqu'à 40 % plus rapides.
• Validation et planification plus puissantes et détaillées : différences détaillées des modifications utilisant les rapports bundle plan -o json par champ expliquant ce qui a Trigger une action donnée.
• Plans rejouables : bundle deploy --plan plan.json exécute un plan créé précédemment, garantissant que seules les actions approuvées atteignent la production et que les déploiements sont plus rapides car le calcul du plan est ignoré.
• Configuration simple : Les problèmes liés aux pare-feu, aux proxys et aux registres de fournisseurs personnalisés sont évités.
• Ressources supplémentaires : Des ressources supplémentaires telles que des catalogues, des emplacements externes, des endpoints de recherche IA et des Genie spaces sont prises en charge.
• Dossiers immuables : Les assets peuvent être déployés en option dans un dossier immuable et en lecture seule pour la protection contre la falsification et la cohérence des déploiements. Voir immutable_folder.

Start l'utilisation du déploiement direct

Pour start à utiliser le nouveau moteur de déploiement direct :

• Pour les bundles existants, migrez-les à l'aide de databricks bundle deployment migrate. Voir Migrer un bundle existant.
• Pour les bundles nouveaux ou existants, définissez engine: direct dans votre configuration de bundle, ou définissez la variable d'environnement DATABRICKS_BUNDLE_ENGINE sur direct. Voir Déployer directement un nouveau bundle.

Migrer un bundle existant

Le moteur de déploiement direct utilise son propre fichier d'état JSON. Le schéma est différent du fichier d'état JSON Terraform. La commandebundle deployment migrate convertit le fichier d'état Terrform (terraform.tfstate) en fichier d'état de déploiement direct (resources.json). La commande lit les ID du déploiement existant.

1. Effectuez un déploiement complet avec Terraform :

   Bash

   databricks bundle deploy -t my_target

2. Migrer le déploiement :

   Bash

   databricks bundle deployment migrate -t my_target

3. Vérifiez que la migration a été réussie. La commande databricks bundle plan doit réussir et ne doit afficher aucune modification.

   Bash

   databricks bundle plan -t my_target

remarque

Le plan pourrait signaler des changements sur les Ressources même lorsque votre configuration locale correspond à la Ressource déployée. Cela peut arriver parce que le fichier d'état Terraform précédent contient des champs de métadonnées que la plateforme renseigne après le déploiement, qui ne sont pas présents dans la configuration de votre bundle. Ces différences ne sont pas de réelles configuration drift et ne modifient pas le comportement du Job. Le moteur direct les réconcilie lors du prochain bundle deploy. Pour plus de détails sur la façon dont le moteur direct calcule les différences, consultez Calcul des différences d'état des Ressources.

• Si la vérification échoue, supprimez le nouveau fichier d’état :

  Bash

  rm .databricks/bundle/my_target/resources.json

• Si la vérification réussit, déployez le bundle pour synchroniser le fichier d'état avec le workspace :

  Bash

  databricks bundle deploy -t my_target

Déployer directement un nouveau bundle

La commande bundle migrate ne fonctionne pas sur les bundles qui n'ont jamais été déployés car il n'y a pas de fichier d'état. Au lieu de cela, effectuez l'une des opérations suivantes :

• Définissez bundle.engine dans votre databricks.yml :

  YAML

  bundle:
    engine: direct

• Définissez la variable d'environnement DATABRICKS_BUNDLE_ENGINE et déployez :

  Bash

  DATABRICKS_BUNDLE_ENGINE=direct databricks bundle deploy -t my_target

Si la configuration et la variable d'environnement sont toutes deux définies, la configuration a priorité.

Comparaison des moteurs de déploiement.

Le nouveau moteur de déploiement direct se comporte en grande partie de la même manière que le moteur de déploiement Terraform, mais il existe quelques différences.

Calcul de la différence d'état des ressources

Contrairement à Terraform, qui maintient un état de ressource unique (un mélange de configuration locale et d'état distant), le nouveau moteur les maintient séparés et n'enregistre que la configuration locale dans son fichier d'état.

Le calcul de la différence d'état des ressources s'effectue en deux étapes :

1. La configuration du bundle local est comparée à la configuration de l'instantané utilisée pour le déploiement le plus récent. L'état distant ne joue aucun rôle.
2. L'état distant est comparé à la configuration d'instantané utilisée pour le déploiement le plus récent.

Le résultat est que :

• databricks.yml les modifications de ressources ne sont jamais ignorées et déclencheront toujours une mise à jour.
• Les champs de ressources non gérés par l'implémentation ne trigger pas d'erreur de résultat incohérent. Ces ressources sont déployées avec succès par le moteur direct, mais cela peut entraîner un drift. Les Ressources déployées sont mises à jour lors du prochain plan ou déploiement.

Paramètres de configuration supprimés

Les deux moteurs gèrent différemment les paramètres que vous supprimez de votre configuration de bundle :

• Avec le moteur Terraform, la suppression d'un champ défini de votre databricks.yml laisse la valeur correspondante inchangée dans la plateforme. Terraform ne gère que les champs explicitement présents dans la configuration, de sorte qu'un champ supprimé conserve la valeur qu'il avait au moment du dernier déploiement.
• Avec le moteur direct, la suppression d'un champ défini de votre databricks.yml réinitialise la valeur default de la ressource. Étant donné que le moteur direct compare votre configuration locale à l'instantané précédent, un champ qui n'est plus présent est traité comme une modification, et la ressource est mise à jour à sa valeur par default lors du prochain déploiement.

Pour rendre une valeur persistante, définissez-la explicitement dans votre configuration plutôt que de vous fier à la valeur précédemment déployée.

Recherche de substitution de ressource

Les substitutions de Ressources sont disponibles pour résoudre les ID de ressources, par exemple, ${resources.jobs.my_job.id}. Voir Substitutions. La résolution des substitutions de ressources dans le moteur de déploiement direct s'effectue en deux étapes :

1. Les références pointant vers des champs présents dans la configuration locale sont résolues à la valeur fournie dans la configuration locale.
2. Les références absentes de la configuration locale sont résolues à partir de l'état distant. Ceci est l'état récupéré à l'aide de la requête GET appropriée pour une Ressource donnée.

Le schéma utilisé pour résoudre une substitution ${resource.*} se trouve dans le fichier out.fields.txt. Les champs marqués comme ALL et STATE peuvent être utilisés pour la résolution locale. Les champs marqués comme ALL ou REMOTE peuvent être utilisés pour la résolution à distance.

Compatibilité des ressources

Les ressources suivantes nécessitent le moteur de déploiement direct et ne sont pas prises en charge par le moteur de déploiement Terraform :

• Catalogues d'Unity Catalog
• Emplacements externes Unity Catalog
• Genie spaces
• AI Search Endpoint

De plus, le champ lifecycle.started n'est disponible que dans le moteur de déploiement direct, et uniquement pour apps, clusters et sql_warehouses. Lorsqu'il est défini sur true, il déploie la ressource en mode start. Voir cycle de vie.