Configura le variabili di ambiente per i processi serverless

Le variabili di ambiente forniscono una configurazione specifica per il deployment del codice applicativo nei compiti serverless Lakeflow Jobs. Definisci voci di variabili di ambiente nominate su un job, poi seleziona una voce per ogni task che ne ha bisogno.

Queste variabili ambientali si applicano solo ai lavori serverless. L'elaborazione serverless non supporta gli script di inizializzazione. Se il tuo carico di lavoro gira su calcolo classico, vedi Imposta e usa variabili di ambiente con script di init.

Come funzionano le variabili ambientali

Le voci delle variabili di ambiente sono definite a livello di lavoro. Ogni voce ha una chiave univoca e contiene variabili inline, percorsi di file .env o entrambi. Una voce è compatibile con tutti i tipi di attività serverless. Un tasto di ingresso può contenere solo lettere, numeri, trattini e sottoline. Ogni nome di variabile in linea deve iniziare con una lettera o un trattino basso e può contenere solo lettere, numeri e trattini bassi.

Ogni task seleziona una singola voce di variabile ambientale con environment_variables_key e riceve solo le variabili di quella voce. Le voci non vengono mai combinate e una voce non può ereditare da un'altra. Un compito che omette environment_variables_key non riceve variabili ambientali.

Le variabili di ambiente sono disponibili solo per il codice applicativo che viene eseguito nel processo di attività. Non sono disponibili per la logica di esecuzione di Spark.

Requirements

• Un amministratore dello spazio di lavoro ha attivato le variabili di ambiente nei processi Lakeflow nella pagina Anteprime. Vedere Gestire le anteprime di Azure Databricks.
• Attività che girano su ambienti serverless versione 5 e superiori.
• Per i file .env, l'identità del processo Esegui come deve disporre dell'accesso in lettura a ciascun file.
• Per i riferimenti ai segreti, l'identità Esegui come del processo deve avere almeno READ l'autorizzazione per ogni ambito dei segreti a cui si fa riferimento. Vedi gli ACL segreti.

Limitazioni

Le funzioni definite dall'utente (UDF) non possono leggere le variabili ambientali, perché le UDF girano nella logica di esecuzione di Spark invece che nel processo di attività.

Sono supportati solo i segreti Azure Databricks a livello di workspace. Il supporto per i segreti di Unity Catalog sta per arrivare.

Si applicano i seguenti limiti:

Usa .env file

Puoi caricare variabili di ambiente da file workspace (/Workspace/...) o file nei volumi del catalogo Unity (/Volumes/...). Aggiungi i percorsi dei file alla lista File di una voce nell'interfaccia utente o al suo spec.files array nell'API Jobs. I file vengono letti quando inizia un task, invece che quando crei o aggiorni il job.

Per i processi serverless, Azure Databricks utilizza un proprio formato .env di file. Si applicano le seguenti regole:

• Definiamo una variabile per riga come KEY=VALUE, senza spazi bianchi o spazi prima di .=
• I nomi delle variabili devono iniziare con una lettera ASCII o con un carattere di sottolineatura. I caratteri rimanenti possono essere lettere, cifre o sottolinee ASCII.
• Tutto ciò che viene dopo il primo = è il valore, inclusi spazi e caratteri aggiuntivi = . Sono permessi valori vuoti. I valori possono contenere testo Unicode. Salva il file usando la codifica UTF-8.
• Le linee vuote e solo spazi bianchi vengono ignorate. Per aggiungere un commento, metti # come primo carattere della frase.

Ad esempio, un execution.env file può contenere:

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

Questo formato non interpreta virgolette, sequenze di fuga, commenti inline o riferimenti a variabili come ${OTHER_VARIABLE}. Questi caratteri restano parte del valore. Ad esempio, APP_ENV="production" include le virgolette nel valore. Un export prefisso è invalido.

I riferimenti segreti utilizzano una sintassi separata e vengono risolti dopo che il file e le variabili inline sono stati combinati. Vedi Utilizzare i segreti.

Se una variabile ha più definizioni:

• All'interno di un file, l'ultima definizione ha la precedenza.
• Tra i file, un file elencato successivamente sovrascrive i valori dei file elencati in precedenza.
• Le variabili inline sovrascrivono i valori dai file.

Ad esempio, se un file definisce LOG_LEVEL=DEBUG e l'entrata definisce anche la variabile LOG_LEVEL=INFOinline , il compito riceve LOG_LEVEL=INFO.

Se un file contiene una riga non valida o supera un limite di dimensione di file o linea, il compito fallisce.

Usa segreti

Le variabili di ambiente per i job serverless supportano i segreti di Azure Databricks a livello di workspace, che sono organizzati in ambiti dei segreti. Usa un riferimento segreto per passare credenziali o token al codice applicativo senza memorizzare il valore segreto nella configurazione del lavoro o in un .env file. Per creare un ambito dei segreti e aggiungerne uno, vedi Gestione segreti.

Imposta il valore di una variabile ambientale su un riferimento segreto nel seguente formato:

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

Sostituisci <scope-name> con il nome dell'ambito segreto e <secret-name> con la chiave del segreto in quell'ambito. Il riferimento deve essere l'intero valore. I riferimenti incorporati in una stringa più grande, come Bearer {{secrets/production/service-token}}, rimangono testo letterale.

Nell'interfaccia utente, inserisci il riferimento come valore sotto Variabili. Nell'API Jobs, usalo come valore in spec.variables:

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

Per fare riferimento allo stesso segreto in un .env file, aggiungi la seguente riga senza virgolette o spazi attorno al riferimento:

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

Azure Databricks risolve i riferimenti ai segreti quando l'attività viene avviata, usando l'identità Run as del processo. L'attività riceve il valore segreto risolto nel suo ambiente di processo. Il codice applicativo lo os.environ["SERVICE_TOKEN"] legge in Python o sys.env("SERVICE_TOKEN") in Scala.

Azure Databricks cerca di oscurare i valori segreti nell'output del notebook, ma l'oscuramento è effettuato nei limiti del possibile. I segreti che la tua applicazione stampa o scrive nei log possono apparire in testo in chiaro nei compute log, anche quando l'output del notebook mostra [REDACTED]. Evita di stampare valori segreti o scriverli nei log. Consulta Redazione segreta.

Le stesse regole di precedenza si applicano ai riferimenti segreti. Vengono risolti solo i valori risultanti. Le impostazioni del processo mantengono i riferimenti ai segreti, non i valori dei segreti risolti.

Se un segreto referenziato non esiste o l'identità Run as non ha il permesso di leggerlo, il compito fallisce prima che il codice applicativo venga eseguito. Controlla il nome dell'ambito, la chiave segreta e le autorizzazioni dello scope segreto.

Configura le variabili dell'ambiente nell'interfaccia utente

Nella scheda Compiti del lavoro, seleziona un compito. Usa variabili di ambiente per selezionare o creare una voce di variabile di ambiente, come production.

In Configura variabili di ambiente, inserisci un nome. Opzionalmente, aggiungi coppie chiave-valore sotto Variabili, percorsi verso .env file sotto File, o entrambi. Puoi anche lasciare entrambe le sezioni vuote. Fare clic su Salva.

Configura le variabili dell'ambiente con l'API Jobs

Usa il campo environment_variables in una richiesta POST /api/2.2/jobs/create per definire le voci di variabile d'ambiente. Imposta environment_variables_key su ogni attività che utilizza un elemento.

Prima di eseguire il seguente esempio, crea il service-token secret nell'ambito production e concedi all'identità Run as del processo l'accesso a esso. Vedi Usare i segreti. L'esempio definisce voci separate per variabili ambientali per un compito di notebook e per un task JAR. Ogni voce utilizza spec.variables per i valori inline e spec.files per i percorsi dei file. Ogni compito seleziona la propria voce con 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"]
      }
    }
  ]
}

Puoi anche configurare le voci delle variabili dell'ambiente con Aggiorna un lavoro, Sovrascrive tutte le impostazioni di un lavoro e Invia un'esecuzione una tantum .

Leggi le variabili ambientali nel codice applicativo

Il codice applicativo legge le variabili configurate dall'ambiente di processo.

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")

Risorse aggiuntive

• Esegui i Lakeflow Jobs con compute serverless per i flussi di lavoro
• Configurare l'ambiente serverless
• Gestione dei segreti