Dépanner la CLI Databricks

remarque

L'utilisation de Databricks CLI est soumise à la licence Databricks et à la politique de confidentialité Databricks, y compris toutes les dispositions relatives aux données d'utilisation.

Utilisez les informations suivantes pour dépanner les problèmes avec la CLI Databricks.

Activer la journalisation

Si une commande échoue ou ne produit pas le résultat attendu, vous pouvez utiliser la journalisation pour aider à identifier ce qui a pu mal tourner. Vous pouvez logger les messages que le CLI Databricks génère concernant divers événements de commande, avertissements et erreurs. Pour journaliser ces messages, spécifiez les options de commande Databricks CLI suivantes :

Drapeau	Description
--log-file	Une chaîne représentant le fichier vers lequel écrire les Logs de sortie. Si cet indicateur n'est pas spécifié, la default est d'écrire les logs de sortie dans stderr.
--log-format	text pour écrire des logs de sortie vers un texte ou json : pour écrire des logs de sortie vers un JSON. Si cet indicateur n'est pas spécifié, les logs de sortie sont écrits sous forme de texte.
--log-level	Une chaîne représentant le niveau de format des Logs. Les niveaux de Logs valides sont error, warn, info, debug, trace et disabled. Le niveau par default est disabled, ce qui signifie que rien n'est journalisé. --debug équivaut à --log-level debug.

Drapeau	Description
--log-file	Une chaîne représentant le fichier vers lequel écrire les Logs de sortie. Si cet indicateur n'est pas spécifié, la default est d'écrire les logs de sortie dans stderr.
--log-format	text pour écrire des logs de sortie vers un texte ou json : pour écrire des logs de sortie vers un JSON. Si cet indicateur n'est pas spécifié, les logs de sortie sont écrits sous forme de texte.
--log-level	Une chaîne représentant le niveau de format des Logs. Les niveaux de Logs valides sont error, warn, info, debug, trace et disabled. Le niveau par default est disabled, ce qui signifie que rien n'est journalisé. --debug équivaut à --log-level debug.

La commande d'exemple suivante Logs les messages de trace de la commande spécifiée dans un fichier nommé databricks-cli.log au format JSON.

Bash

databricks clusters list --log-file databricks-cli.log --log-format json --log-level trace

Erreur de download de Terraform

Une clé expirée dans certaines versions de la CLI Databricks entraîne l'erreur suivante lors de l'exécution de databricks bundle deploy:

error downloading Terraform: unable to verify checksums signature: openpgp: key expired

Pour résoudre cette erreur, mettez à niveau la CLI Databricks vers une dernière version corrigée, ce qui met à jour le mécanisme de vérification pour fonctionner avec une clé plus récente. Mettez à niveau vers la version corrigée correspondant à votre version mineure actuelle de la CLI :

• Installation binaire : download la version corrigée depuis la page des versions du Databricks CLI sur GitHub.

• setup-cli (en tant que script d'installation ou GitHub Action) : mettez à jour la version de votre configuration vers une version corrigée à partir de la page des versions de Databricks CLI sur GitHub.

  Par exemple, pour utiliser 0.296.1 avec GitHub Actions :

  YAML

  - uses: databricks/setup-cli@main
    with:
      version: 0.296.1

Erreur d’identifiants enregistrés

À partir de la version 1.0.0 de Databricks CLI, Databricks CLI stocke les jetons d'authentification utilisateur-machine (U2M) dans un stockage sécurisé natif du système d'exploitation (trousseau sur macOS, Credential Manager sur Windows, D-Bus Secret Service sur Linux) au lieu d'un fichier JSON. Voir Stockage des jetons. Si votre workflow est basé sur le fichier JSON, il ne fonctionnera pas avec la nouvelle méthode de stockage et vous pourriez rencontrer des problèmes dans les scénarios suivants :

• Mise à niveau vers la disponibilité générale (GA), pas encore reconnecté(e). La CLI Databricks ne lit plus les informations d'identification stockées par les anciennes versions et renvoie une erreur :

  Stored credentials from older CLI versions are no longer used.
  Run "databricks auth login" to sign in again.
  
  If secure storage is not available in this environment, set
  DATABRICKS_AUTH_STORAGE=plaintext and re-run login.

  Exécutez databricks auth login pour résoudre ce problème.

• Échec de la vérification du stockage sécurisé à la connexion Pendant databricks auth login, la CLI Databricks vérifie le stockage sécurisé avant de démarrer le flux OAuth. Si la vérification échoue (le cas le plus fréquent dans les conteneurs Linux, les sessions SSH, WSL1 et les serveurs sans interface où D-Bus n’est pas en cours d’exécution), le comportement dépend du fait que le stockage sécurisé ait été explicitement configuré :

  • Mode default, sans paramètre de stockage explicite : le CLI Databricks utilise en arrière-plan du texte brut et écrit auth_storage = plaintext dans la section [__settings__] de ~/.databrickscfg. Les commandes suivantes utilisent du texte brut sans vérification ultérieure.
  • Mode sécurisé explicite (DATABRICKS_AUTH_STORAGE=secure ou auth_storage = secure dans le profil de configuration) : la CLI Databricks renvoie une erreur pointant vers le fallback DATABRICKS_AUTH_STORAGE=plaintext.

  Si la vérification se termine par un délai d'attente au lieu d'échouer complètement (par exemple, si le trousseau est verrouillé mais accessible), l'interface CLI de Databricks conserve le backend du trousseau et l'invite de déverrouillage du système d'exploitation s'exécute en parallèle avec le flux OAuth du navigateur.

  Pour confirmer le mode de stockage utilisé par la CLI Databricks après la connexion, exécutez databricks auth describe.

• **Trousseau de clés non atteignable lors de la lecture d'un jeton stocké.** Contrairement à la connexion, la CLI Databricks ne revient pas silencieusement en mode fallback lorsqu'elle ne peut pas atteindre le trousseau de clés au moment de la lecture du jeton. Par exemple, si vous avez effectué une connexion sur une machine de bureau et que vous vous êtes ensuite connecté via SSH dans une session sans interface graphique, les commandes qui nécessitent le jeton stocké échouent avec une erreur. Utilisez le fallback en texte brut pour résoudre ceci. Consultez Utiliser le fallback en texte clair.

Commandes qui ne se terminent pas

Si vous exécutez une commande telle que databricks cluster list et qu'elle semble bloquer, mettez à jour votre version de Databricks CLI vers la version la plus récente. Les versions antérieures de la CLI tentaient de charger des listes complètes même si le nombre d'éléments dans la liste était élevé, et la commande semblait ne pas se terminer.