Configurer des versions d’environnement pour les pipelines

Une version d’environnement fixe la version du langage Python et l’ensemble des bibliothèques Python préinstallées mises à la disposition du code Python de votre pipeline. Toutes les dépendances externes que vous ajoutez au pipeline sont superposées au-dessus de cette base.

Les versions d'environnement dissocient le runtime Python de votre pipeline à partir de la version databricks Runtime sur laquelle votre pipeline s'exécute. Pendant qu'une version d'environnement est définie, les mises à niveau de Databricks Runtime ne modifient pas votre version de langue Python ou les versions de bibliothèque préinstallées. Le runtime Python est également cohérent avec les travaux serverless et les notebooks qui utilisent la même version d’environnement. Pour connaître la version actuelle du runtime Databricks des pipelines Lakeflow, consultez les notes de version des pipelines Lakeflow et le processus de mise à niveau des versions.

Databricks migre automatiquement les pipelines éligibles vers une version d’environnement. Voir Migration automatique.

Requirements

Les versions d’environnement ont les exigences suivantes :

• Le pipeline doit utiliser Unity Catalog. Les pipelines de metastore Hive ne sont pas pris en charge.

Versions d’environnement prises en charge

Les pipelines Lakeflow prennent en charge les versions 3 et 4 de l’environnement sur le calcul serverless et classique. Pour connaître la version du langage Python et la liste complète des bibliothèques de Python préinstallées disponibles dans chaque version, consultez la référence de version environment.

Migration automatique

Databricks migre automatiquement les pipelines éligibles vers une version d’environnement. La migration a lieu lors de la prochaine mise à jour d’un pipeline, ne nécessite pas d’étapes manuelles, et inclut ces garanties :

• Le comportement est vérifié avant la migration. Databricks analyse votre pipeline à la recherche de motifs de code qui se comporteraient différemment sous Spark Connect et compare le plan de sortie du pipeline avant et après la migration. Voir Compatibilité des versions de l’environnement.
• Une migration ratée revient automatiquement. Si une mise à jour migrée échoue pour une raison quelconque, elle est arrêtée avant que les données ne soient écrites, et le pipeline revient automatiquement à son temps d’exécution précédent lors de la prochaine mise à jour. Aucune action n’est requise.
• Vos paramètres explicites sont toujours respectés. Si vous définissez vous-même environment_version, Databricks ne l’écrase jamais.

Une fois qu’un pipeline a été migré avec succès, il s’exécute désormais sur la version de l’environnement correspondante. Vous pouvez voir la version sélectionnée dans les paramètres du pipeline, la réponse de l’API GetPipeline et le runtime_details journal des événements.

Ce qui n’est pas migré automatiquement

Un pipeline n’est pas migré automatiquement si l’une des conditions suivantes s’applique :

• Il comporte des avertissements de compatibilité de Spark Connect non résolus issus de sa dernière mise à jour.
• Ce n’est pas un pipeline Unity Catalog.
• Il utilise une fonctionnalité que la migration automatique ne couvre pas encore : foreach_batch sinks, hooks d’événements, AUTO CDC à partir d’une source de fonction d’instantané, ou une image personnalisée.

Les pipelines qui ne sont pas migrés continuent automatiquement à fonctionner sur leur ancien runtime Python sans aucun changement. Vous pouvez activer vous-même une version de l’environnement une fois que le pipeline est éligible.

Activez vous-même une version de l’environnement

La migration automatique couvre la plupart des pipelines. Vous pouvez aussi configurer explicitement une version d’environnement, par exemple pour migrer plus tôt ou épingler une version spécifique, via l’interface de l’éditeur de pipelines, l’API REST de Pipelines ou les Declarative Automation Bundles.

Avant d’activer explicitement une version de l’environnement, vérifiez que votre pipeline est compatible avec Spark Connect. Si Databricks détecte que l’activation de la version modifierait le comportement de votre pipeline, la mise à jour échoue avant que les données ne soient écrites, avec une erreur permettant d’identifier la différence à résoudre.

Activer via l’interface utilisateur

1. Dans l’éditeur de pipeline, cliquez sur Paramètres.
2. Sous Environnement de pipeline, sélectionnez Modifier l’environnement.
3. Sélectionnez une version d’environnement dans la liste déroulante.
4. Enregistrez les paramètres du pipeline.

Les dépendances externes ajoutées dans la section Environnement de pipeline sont superposées aux bibliothèques incluses dans la version d’environnement sélectionnée. Consultez Gestion des dépendances Python pour les pipelines.

Activer via l’API

L’API REST Pipelines accepte un environment bloc sur la création et la mise à jour du pipeline. L’authentification par jeton d’accès personnel doit être activée pour l’espace de travail.

Pour créer un pipeline avec une version d’environnement :

curl --request POST \
  --url 'https://<workspace-host>/api/2.0/pipelines' \
  --header 'Authorization: Bearer <personal-access-token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "<pipeline-name>",
    "catalog": "<catalog>",
    "schema": "<schema>",
    "channel": "CURRENT",
    "environment": {
      "environment_version": "4",
      "dependencies": [
        "simplejson==3.19.*"
      ]
    }
  }'

Pour définir la version de l’environnement sur un pipeline existant, envoyez le même environment bloc avec PUT /api/2.0/pipelines/<pipeline-id>.

Activer à l’aide de Bundles d’automatisation déclarative

Lorsque vous créez un pipeline à l’aide de bundles Automation déclaratifs, vous pouvez définir une version d’environnement dans la définition YAML du pipeline.

1. Vérifiez que votre interface CLI Databricks est à la version v0.294.0 ou ultérieure. Si ce n’est pas le cas, effectuez une mise à niveau en suivant le guide d’installation.
2. Configurez un bundle en suivant le tutoriel sur les bundles de pipelines.
3. Recherchez le YAML du pipeline dans votre package, généralement <bundle-folder>/resources/<pipeline_name>_pipeline.yml.
4. Définissez les champs environment_version et dependencies dans le pipeline YAML :

resources:
  pipelines:
    my_pipeline:
      name: my_pipeline
      catalog: ${var.catalog}
      schema: ${var.schema}
      root_path: '../src/my_pipeline'
      libraries:
        - glob:
            include: ../src/my_pipeline/transformations/**
      environment:
        environment_version: 4
        dependencies:
          - --editable ${workspace.file_path}

Vérifier la version de l’environnement sur un pipeline

Pour vérifier quelle version d’environnement un pipeline exécute, que vous l’ayez définie explicitement ou que Databricks l’ait sélectionnée lors de la migration automatique :

• Interface utilisateur : ouvrez les paramètres du pipeline et vérifiez la section Environnement de pipeline , ou inspectez le volet JSON du environment.environment_version champ.
• API : Appeler GET /api/2.0/pipelines/<pipeline-id> et rechercher environment.environment_version dans la réponse. Cela montre une version que vous avez définie explicitement ; Pour voir une version sélectionnée par migration automatique, utilisez le journal des événements ci-dessous.
• Journal d’événements : Inspectez l’événement runtime_details , qui rapporte la version de l’environnement utilisée pour la mise à jour. Voir les détails de l’événement runtime_details.

Désactiver ou revenir en arrière sur une version d’environnement

Vous n’avez pas besoin de revenir manuellement sur une migration automatique. Une migration qui échoue est automatiquement annulée lors de la prochaine mise à jour. Lorsque la version de l’environnement est supprimée, le pipeline retourne à sa configuration précédente Python runtime. Si quelque chose d’imprévu arrive, contactez le support Azure Databricks.

Ressources additionnelles

• Compatibilité des versions de l’environnement — limitations, changements de comportement, le scan de compatibilité et la migration automatique.
• Gérer les dépendances Python pour les pipelines — superposer des dépendances Python externes sur une version d’environnement.