Konfiguration von Umgebungsvariablen für serverlose Jobs

Umgebungsvariablen bieten deployment-spezifische Konfigurationen für Anwendungscode in serverlosen Lakeflow-Jobs-Aufgaben. Definiere benannte Umgebungsvariableneinträge in einem Job und wähle dann für jede Aufgabe, die sie benötigt, einen Eintrag aus.

Diese Umgebungsvariablen gelten nur für serverlose Jobs. Serverless Compute unterstützt keine Init-Skripte. Wenn deine Workload auf klassischer Berechnung läuft, siehe Set und nutze Umgebungsvariablen mit Init-Skripten.

Wie Umweltvariablen funktionieren

Umgebungsvariablen-Einträge werden auf Jobebene definiert. Jeder Eintrag hat einen einzigartigen Schlüssel und enthält Inline-Variablen, Pfade zu .env Dateien oder beides. Ein Eintrag funktioniert mit allen serverlosen Aufgabentypen. Ein Eingabeschlüssel kann nur Buchstaben, Zahlen, Bindestriche und Unterstriche enthalten. Jeder Inline-Variablenname muss mit einem Buchstaben oder Unterstrich beginnen und darf nur Buchstaben, Zahlen und Unterstriche enthalten.

Jede Aufgabe wählt einen einzigen Umgebungsvariableneintrag mit environment_variables_key und erhält nur die Variablen dieses Eintrags. Einträge werden nie kombiniert, und ein Eintrag kann nicht von einem anderen erben. Eine Aufgabe, die weglässt environment_variables_key , erhält keine Umgebungsvariablen.

Umgebungsvariablen sind nur für Anwendungscode verfügbar, der im Aufgabenprozess ausgeführt wird. Sie sind für die Spark-Ausführungslogik nicht verfügbar.

Anforderungen

• Ein Workspace-Administrator hat die Umgebungsvariablen in Lakeflow Jobs auf der Vorschau-Seite aktiviert. Siehe Manage Azure Databricks Previews.
• Aufgaben, die in der serverlosen Umgebung Version 5 und höher laufen.
• Für Dateien vom Typ .env muss die Identität Ausführen als des Jobs Lesezugriff auf jede Datei haben.
• Für geheime Referenzen muss die Ausführen-als -Identität des Auftrags mindestens READ eine Berechtigung für jeden referenzierten geheimen Bereichs haben. Siehe Secret ACLs.

Einschränkungen

Benutzerdefinierte Funktionen (UDFs) können keine Umgebungsvariablen lesen, da UDFs in der Spark-Ausführungslogik und nicht im Task-Prozess ausgeführt werden.

Es werden nur Secrets auf Azure Databricks-Arbeitsbereichsebene unterstützt. Unterstützung für Unity Catalog Secrets kommt bald.

Folgende Grenzen gelten:

Dateien verwenden .env

Man kann Umgebungsvariablen aus Workspace-Dateien (/Workspace/...) oder Dateien in Unity-Catalog-Volumes (/Volumes/...) laden. Fügen Sie die Dateipfade in der Benutzeroberfläche zur Liste Files eines Eintrags oder in der Jobs-API zum Array spec.files hinzu. Dateien werden gelesen, wenn eine Aufgabe startet, und nicht beim Erstellen oder Aktualisieren des Jobs.

Für serverlose Jobs verwendet Azure Databricks ein eigenes .env Dateiformat. Es gelten die folgenden Regeln:

• Definieren Sie eine Variable pro Zeile in der Form KEY=VALUE, ohne führende Leerzeichen oder Leerzeichen vor =.
• Variablennamen müssen mit einem ASCII-Buchstaben oder Unterstrich beginnen. Die übrigen Zeichen können ASCII-Buchstaben, Ziffern oder Unterstriche sein.
• Alles nach dem ersten = ist der Wert, einschließlich Leerzeichen und zusätzlicher = Zeichen. Leere Werte sind erlaubt. Werte können Unicode-Text enthalten. Speichere die Datei mit der UTF-8-Codierung.
• Leere und nur weiße Zeilen werden ignoriert. Um einen Kommentar hinzuzufügen, gib als erstes Zeichen der Zeile an # .

Zum Beispiel kann eine execution.env Datei enthalten:

# Application configuration
APP_ENV=production
REGION=us-west-2
GREETING=こんにちは
OPTIONAL_VALUE=

Dieses Format interpretiert keine Anführungszeichen, Escape-Sequenzen, Inline-Kommentare oder Variablenreferenzen wie ${OTHER_VARIABLE}. Diese Charaktere bleiben Teil des Wertes. Zum Beispiel enthält APP_ENV="production" die Anführungszeichen im Wert. Ein export Präfix ist ungültig.

Geheime Referenzen verwenden eine separate Syntax und werden aufgelöst, nachdem Datei- und Inline-Variablen kombiniert wurden. Weitere Informationen unter Geheimnisse verwenden.

Wenn eine Variable mehrere Definitionen hat:

• Innerhalb einer Datei hat die letzte Definition Vorrang.
• Über alle Dateien hinweg überschreibt eine später aufgeführte Datei Werte aus zuvor aufgeführten Dateien.
• Inline-Variablen überschreiben Werte aus Dateien.

Wenn zum Beispiel eine Datei LOG_LEVEL=DEBUG definiert und der Eintrag auch die Inline-Variable LOG_LEVEL=INFO definiert, erhält die Aufgabe LOG_LEVEL=INFO.

Wenn eine Datei eine ungültige Zeile enthält oder eine Datei- oder Zeilengrößenbegrenzung überschreitet, schlägt die Aufgabe fehl.

Verwenden von Geheimnissen

Umgebungsvariablen für serverlose Jobs unterstützen Azure Databricks-Geheimnisse auf Arbeitsbereichsebene, die in Secret-Scopes organisiert sind. Verwenden Sie eine geheime Referenz, um Zugangsdaten oder Token an den Anwendungscode weiterzugeben, ohne den geheimen Wert in der Jobkonfiguration oder einer .env Datei zu speichern. Um einen Secret-Bereich zu erstellen und ein Secret hinzuzufügen, siehe Secret-Verwaltung.

Setzen Sie den Wert einer Umgebungsvariable auf eine geheime Referenz im folgenden Format:

{{secrets/<scope-name>/<secret-name>}}

Ersetzen Sie <scope-name> durch den Namen des geheimen Bereichs und <secret-name> durch den Schlüssel des Geheimnisses in diesem Bereich. Die Referenz muss der gesamte Wert sein. Referenzen, die in eine größere Zeichenkette eingebettet sind, wie Bearer {{secrets/production/service-token}}, bleiben wörtlicher Text.

Geben Sie in der Benutzeroberfläche die Referenz als Wert unter Variablen ein. In der Jobs-API verwenden Sie ihn als Wert in spec.variables:

{
  "SERVICE_TOKEN": "{{secrets/production/service-token}}"
}

Um dasselbe Geheimnis in einer .env Datei zu referenzieren, fügen Sie folgende Zeile ohne Anführungszeichen oder Leerzeichen um die Referenz hinzu:

SERVICE_TOKEN={{secrets/production/service-token}}

Azure Databricks löst geheime Referenzen auf, wenn die Aufgabe startet, unter Verwendung der Ausführen-als-Identität des Auftrags. Die Aufgabe erhält den aufgelösten Geheimniswert in ihrer Prozessumgebung. Anwendungscode liest sie mit os.environ["SERVICE_TOKEN"] in Python oder sys.env("SERVICE_TOKEN") in Scala.

Azure Databricks versucht, geheime Werte in der Notebook-Ausgabe zu schwärzen, aber Schwärzung ist Best Effort. Geheimnisse, die Ihre Anwendung druckt oder in Logs schreibt, können im Klartext in Compute-Logs erscheinen, selbst wenn die Notebook-Ausgabe [REDACTED] anzeigt. Vermeide es, geheime Werte auszudrucken oder sie in Logs zu schreiben. Siehe "Geheime Redaction".

Die gleichen Prioritätsregeln gelten für Verweise auf Secrets. Nur die resultierenden Werte werden aufgelöst. Job-Einstellungen behalten die geheimen Referenzen, nicht die aufgelösten Secret-Werte.

Wenn ein referenziertes Geheimnis nicht existiert oder die Ausführen als-Identität keine Leseberechtigung hat, schlägt die Aufgabe fehl, bevor der Anwendungscode ausgeführt wird. Überprüfen Sie den Namen des Scope, den geheimen Schlüssel und die Berechtigungen für den geheimen Scope.

Konfiguration von Umweltvariablen in der Benutzeroberfläche

Wählen Sie im Reiter "Aufgaben " des Jobs eine Aufgabe aus. Verwenden Sie Environment-Variablen, um einen Eintrag für Umweltvariablen auszuwählen oder zu erstellen, wie zum Beispiel production.

Geben Sie in "Umgebungsvariablen konfigurieren" einen Namen ein. Optional fügen Sie Schlüssel-Wert-Paare unter Variablen, Pfade zu .env Dateien unter Dateien oder beides hinzu. Du kannst auch beide Bereiche leer lassen. Klicke auf Speichern.

Konfiguration von Umweltvariablen mit der Jobs-API

Verwenden Sie das Feld environment_variables in einer POST /api/2.2/jobs/create Anfrage, um Einträge für Umgebungsvariablen zu definieren. Legen Sie environment_variables_key für jede Aufgabe fest, die einen Eintrag verwendet.

Bevor Sie das folgende Beispiel ausführen, erstellen Sie das service-token Secret im Scope production und gewähren Sie der Run as-Identität des Jobs Zugriff darauf. Weitere Informationen unter Geheimnisse verwenden. Das Beispiel definiert separate Umgebungsvariableneinträge für eine Notebook-Aufgabe und eine JAR-Aufgabe. Jeder Eintrag verwendet spec.variables für Inline-Werte und spec.files für Dateipfade. Jede Aufgabe wählt ihren Eintrag mit environment_variables_key:

{
  "name": "serverless-environment-variables-example",
  "tasks": [
    {
      "task_key": "process_orders",
      "notebook_task": {
        "notebook_path": "/Workspace/Shared/process-orders"
      },
      "environment_key": "default",
      "environment_variables_key": "production"
    },
    {
      "task_key": "summarize",
      "spark_jar_task": {
        "main_class_name": "com.company.main"
      },
      "environment_key": "summary_env",
      "environment_variables_key": "summary_vars"
    }
  ],
  "environments": [
    {
      "environment_key": "default",
      "spec": {
        "environment_version": "5",
        "dependencies": []
      }
    },
    {
      "environment_key": "summary_env",
      "spec": {
        "environment_version": "5",
        "java_dependencies": ["/Volumes/company/default/prod/summarize.jar"]
      }
    }
  ],
  "environment_variables": [
    {
      "environment_variables_key": "production",
      "spec": {
        "variables": {
          "APP_ENV": "production",
          "REGION": "us-west-2",
          "SERVICE_TOKEN": "{{secrets/production/service-token}}"
        },
        "files": ["/Volumes/company/default/prod/execution.env", "/Volumes/company/default/prod/format.env"]
      }
    },
    {
      "environment_variables_key": "summary_vars",
      "spec": {
        "variables": {
          "APP_ENV": "production",
          "LOG_LEVEL": "INFO",
          "LOG_FILE": "service.log"
        },
        "files": ["/Volumes/company/default/prod/format.env"]
      }
    }
  ]
}

Du kannst Einträge für Umgebungsvariablen auch über die Vorgänge Job aktualisieren, Alle Einstellungen für einen Job überschreiben und Einmalige Ausführung übermitteln konfigurieren.

Umgebungsvariablen im Anwendungscode lesen

Anwendungscode liest konfigurierte Variablen aus der Prozessumgebung aus.

Python

import os

app_environment = os.environ["APP_ENV"]
region = os.environ["REGION"]

Scala

val appEnvironment = sys.env("APP_ENV")
val region = sys.env("REGION")

Weitere Ressourcen

• Ausführen von Lakeflow-Aufträgen mit serverloser Berechnung für Workflows
• Konfigurieren der Serverless-Umgebung
• Verwaltung von Geheimnissen