Sistema de Ambiente

Entradas de ambiente permitem que o código em runtime referencie configurações pelo nome público da variável ou pelo ID da entrada no registro.

Esta página é uma referência de configuração. Seus blocos YAML são fragmentos de entradas, salvo quando mostrarem um documento externo.

Armazenamento e Acesso

O sistema de ambiente separa armazenamento de acesso:

• Armazenamentos - Onde valores são armazenados (SO, arquivos, memória)
• Variáveis - Referências nomeadas a valores em armazenamentos

Variáveis podem ser referenciadas por:

• Nome público - O valor do campo variable
• ID de entrada - Referência completa namespace:name

Omita o campo variable quando a variável só deva ser acessível pelo ID da entrada. A primeira variável a reivindicar um nome público mantém esse atalho. Outra variável com o mesmo nome ainda é registrada e acessível por ID, mas não substitui o atalho existente.

Tipos de Entradas

Backends de Armazenamento

Armazenamento em Memória

Armazenamento volátil em memória.

- name: runtime_env
  kind: env.storage.memory

Armazenamento em Arquivo

Armazenamento persistente em formato simples KEY=VALUE. Linhas vazias e linhas iniciadas por # são ignoradas; texto após # em uma linha de valor é tratado como comentário. Valores entre aspas e sequências de escape não recebem tratamento especial.

- name: app_config
  kind: env.storage.file
  file_path: /etc/app/config.env
  auto_create: true
  file_mode: 0600
  dir_mode: 0700

Armazenamento do SO

Acesso somente leitura a variáveis de ambiente do sistema operacional.

- name: os_env
  kind: env.storage.os

Sempre somente leitura. Operações de escrita retornam PERMISSION_DENIED.

Armazenamento Estático

Armazenamento somente leitura com valores definidos diretamente na configuração. Os valores são incorporados na entrada e não podem ser alterados em tempo de execução. Útil para constantes de configuração públicas que acompanham um módulo ou pacote.

- name: defaults
  kind: env.storage.static
  values:
    PUBLIC_API_HOST: "https://api.example.com"
    PUBLIC_WS_HOST: "wss://api.example.com/ws"
    APP_ENV: "production"

Sempre somente leitura. Operações de escrita retornam PERMISSION_DENIED.

Armazenamento Router

Um router encadeia vários armazenamentos. Em um cache miss, as leituras os consultam em ordem até encontrar um valor; valores encontrados são armazenados no cache do router, portanto alterações diretas no backend deixam de ser visíveis por ele. Um erro diferente de NOT_FOUND interrompe a busca. Escritas vão apenas para o primeiro armazenamento.

- name: config
  kind: env.storage.router
  storages:
    - app.config:memory    # Primary (writes here)
    - app.config:file      # Fallback
    - app.config:os        # Fallback

Variáveis

Variáveis mapeiam nomes públicos ou IDs de entrada a valores de um backend de armazenamento.

- name: DATABASE_URL
  kind: env.variable
  variable: DATABASE_URL
  storage: app.config:file
  default: postgres://localhost/app
  readonly: false

Nomenclatura de Variáveis

Nomes de variáveis devem conter apenas: a-z, A-Z, 0-9, _

Padrões de Acesso

# Public variable - accessible by name "PORT"
- name: port_var
  kind: env.variable
  variable: PORT
  storage: app.config:os
  default: "8080"

# Private variable - accessible only by ID "app.config:internal_key"
- name: internal_key
  kind: env.variable
  storage: app.config:secrets

Interpolação de Placeholders

Variáveis registradas são trazidas para a configuração com placeholders ${env:NAME}, resolvidos centralmente durante o decode. Strings de configuração são resolvidas, exceto quando o tipo da entrada marca o campo como opaco. Campos de código como template.jet.source são opacos, impedindo a reescrita de templates ou programas.

NAME é o nome público de uma variável registrada ou seu ID de entrada (forma de id de registro com pontos/dois-pontos, p. ex. app.env:tls_cert). Não é uma variável de ambiente crua do SO: um valor do SO só é alcançável quando uma variável com backend env.storage.os está registrada sob esse nome.

- name: api
  kind: http.service
  addr: ":443"
  tls:
    mode: manual
    cert: ${env:app.env:tls_cert}
    key:  ${env:app.env:tls_key}

Um campo cujo valor inteiro é um único placeholder recebe o tipo de seu default inline. Por exemplo, ${env:PORT|8080} produz um inteiro e converte o valor armazenado para inteiro, enquanto ${env:PORT|"8080"} permanece string. Um placeholder misturado a outro texto sempre produz string. O default da própria variável prevalece sobre o |default inline. Uma referência sem valor nem default falha no decode.

A resolução acontece apenas no momento do decode: a entrada armazenada no registro mantém os placeholders crus, então segredos resolvidos nunca aparecem em resultados de registry.get nem em estado persistido. Entradas que referenciam uma variável pelo ID da entrada (${env:ns:name}) são ordenadas automaticamente depois dessa variável no boot; uma referência pelo nome público não cria aresta de dependência.

Erros

Acesso em Tempo de Execução

• módulo env - Acesso em runtime pelo Lua

Veja Também

• Modelo de Segurança - Controle de acesso para variáveis de ambiente
• Guia de Configuração - Padrões de configuração da aplicação