Configure variáveis de ambiente para jobs serverless

Variáveis de ambiente provide deployment-specific configuration to application code in serverless Lakeflow Jobs tarefas. Define named variável de ambiente entries on a Job, then select an entry for each tarefa that needs it.

info

Beta

Esse recurso está em Beta. Para usá-lo, um administrador do workspace deve ativar variáveis de ambiente em Lakeflow Jobs na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.

Esta página descreve variáveis de ambiente para jobs Serverless. O compute Serverless não suporta init scripts. Se sua carga de trabalho for executada em compute clássico, consulte Definir e usar variáveis de ambiente com init scripts.

Como as variáveis de ambiente funcionam

As entradas de variável de ambiente são definidas no nível do job. Cada entrada tem uma key exclusiva e contém variáveis embutidas, caminhos para arquivos .env ou ambos. Uma entrada funciona com todos os tipos de tarefas serverless. Uma key de entrada pode conter apenas letras, números, hifens e underscores. Each inline variable name must start with a letter or underscore and can contain only letters, numbers, and underscores.

Cada tarefa seleciona uma única entrada de variável de ambiente com environment_variables_key e recebe apenas as variáveis dessa entrada. As entradas nunca são combinadas, e uma entrada não pode herdar de outra. Uma tarefa que omite environment_variables_key não recebe nenhuma variável de ambiente.

As variáveis de ambiente estão disponíveis apenas para o código do aplicativo que é executado no processo da tarefa. Elas não estão disponíveis para a lógica de execução do Spark.

Requisitos

• Um administrador do workspace ativou Variáveis de ambiente no Lakeflow Jobs na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.
• Tarefas que são executadas em ambiente serverless versão 5 ou posterior.
• Para arquivos .env, a identidade Run as do job deve ter acesso de leitura a cada arquivo.

Limitações

Funções definidas pelo usuário (UDFs) não podem ler variáveis de ambiente, pois as UDFs são executadas na lógica de execução do Spark em vez de no processo da tarefa.

Aplicam-se os seguintes limites:

Configuração	Limite
Entradas de variáveis de ambiente por job	10
Chave de entrada	1–100 caracteres; deve corresponder ^[\w\-_]+$
Variáveis embutidas por entrada	20
Nome da variável em linha	1–256 caracteres; deve corresponder ^[A-Za-z_][A-Za-z0-9_]*$
Valor da variável embutida	512 caracteres
.env arquivos por entrada	5
Caminho do arquivo	1.024 caracteres
Tamanho do Arquivo	32 KiB (32.768 bytes)
Tamanho da linha em um arquivo	1 KiB (1.024 bytes), medidos em bytes UTF-8

Configuração	Limite
Entradas de variáveis de ambiente por job	10
Chave de entrada	1–100 caracteres; deve corresponder ^[\w\-_]+$
Variáveis embutidas por entrada	20
Nome da variável em linha	1–256 caracteres; deve corresponder ^[A-Za-z_][A-Za-z0-9_]*$
Valor da variável embutida	512 caracteres
.env arquivos por entrada	5
Caminho do arquivo	1.024 caracteres
Tamanho do Arquivo	32 KiB (32.768 bytes)
Tamanho da linha em um arquivo	1 KiB (1.024 bytes), medidos em bytes UTF-8

Use arquivos .env

Você pode carregar variáveis de ambiente de arquivos de workspace (/Workspace/...) ou de arquivos em volumes do Unity Catalog (/Volumes/...). Adicione os caminhos de arquivo à lista Files de uma entrada na interface do usuário ou à matriz spec.files na Jobs API. Os arquivos são lidos quando uma tarefa inicia, em vez de quando você cria ou atualiza o job.

Para jobs serverless, o Databricks usa seu próprio formato de arquivo .env. As seguintes regras se aplicam:

• Define one variable per line as KEY=VALUE, with no leading whitespace or spaces before the =.
• Os nomes de variáveis devem começar com uma letra ASCII ou underscore. Os caracteres restantes podem ser letras ASCII, dígitos ou underscores.
• Tudo após o primeiro = é o valor, incluindo espaços e caracteres = adicionais. Valores vazios são permitidos. Os valores podem conter texto Unicode. Salve o arquivo usando a codificação UTF-8.
• Linhas em branco e apenas com espaços em branco são ignoradas. Para adicionar um comentário, coloque # como o primeiro caractere da linha.

Por exemplo, um arquivo execution.env pode conter:

Text

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

Este formato não interpreta aspas, sequências de escape, comentários em linha ou referências de variáveis, como ${OTHER_VARIABLE}. Esses caracteres continuam a fazer parte do valor. Por exemplo, APP_ENV="production" inclui as aspas no valor. Um prefixo export é inválido.

Se uma variável tiver várias definições:

• Dentro de um arquivo, a última definição tem precedência.
• Entre os arquivos, um arquivo listado posteriormente substitui os valores dos arquivos listados anteriormente.
• As variáveis embutidas substituem os valores dos arquivos.

Por exemplo, se um arquivo definir LOG_LEVEL=DEBUG e a entrada também definir a variável embutida LOG_LEVEL=INFO, a tarefa receberá LOG_LEVEL=INFO.

Se um arquivo contiver uma linha inválida ou exceder um limite de tamanho de arquivo ou linha, a tarefa falhará.

Configurar variáveis de ambiente na UI

Na tab Tarefas do job, selecione uma tarefa. Use Variáveis de ambiente para selecionar ou criar uma entrada de variável de ambiente, como production.

Em Configure variáveis de ambiente , insira um nome. Opcionalmente, adicione pares key-value em Variables , caminhos para arquivos .env em Files ou ambos. Você também pode deixar ambas as seções vazias. Clique em Salvar .

Configure variáveis de ambiente com a API de Tarefas.

Use o campo environment_variables em uma solicitação POST /api/2.2/jobs/create para definir entradas de variável de ambiente. Defina environment_variables_key em cada tarefa que usa uma entrada.

O exemplo a seguir define entradas de variável de ambiente separadas para uma tarefa de notebook e uma tarefa JAR. Cada entrada usa spec.variables para valores em linha e spec.files para caminhos de arquivos. Cada tarefa seleciona sua entrada com environment_variables_key, e qualquer tipo de tarefa serverless pode usar uma entrada da mesma forma:

JSON

{
  "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"
        },
        "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"]
      }
    }
  ]
}

Você também pode configurar entradas de variável de ambiente com as operações Atualizar um job, Substituir todas as configurações de um job e Enviar uma execução única.

Ler variáveis de ambiente no código do aplicativo

O código da aplicação lê as variáveis configuradas do ambiente do processo.

Python

Python

import os

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

Scala

Scala

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

Outros recursos

• Execute seus Lakeflow Jobs com compute serverless para fluxos de trabalho
• Configure o ambiente Serverless.