Sistema de Entorno

Gestiona variables de entorno a través de backends de almacenamiento configurables.

Visión General

El sistema de entorno separa el almacenamiento del acceso:

• Almacenes - Donde se guardan los valores (SO, archivos, memoria)
• Variables - Referencias nombradas a valores en almacenes

Las variables pueden referenciarse por:

• Nombre público - El valor del campo variable (debe ser único en el sistema)
• ID de Entrada - Referencia completa namespace:nombre

Si no desea que una variable sea accesible públicamente por nombre, omita el campo variable.

Tipos de Entrada

Backends de Almacenamiento

Almacén de Memoria

Almacenamiento volátil en memoria.

- name: runtime_env
  kind: env.storage.memory

Almacén de Archivo

Almacenamiento persistente usando formato de archivo .env (KEY=VALUE con comentarios #).

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

Almacén del SO

Acceso de solo lectura a variables de entorno del sistema operativo.

- name: os_env
  kind: env.storage.os

Siempre de solo lectura. Las operaciones de escritura retornan PERMISSION_DENIED.

Almacén Estático

Almacenamiento de solo lectura con valores definidos directamente en la configuración. Los valores se integran en la entrada y no pueden cambiarse en tiempo de ejecución. Útil para constantes de configuración públicas que se distribuyen con un módulo o paquete.

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

Siempre de solo lectura. Las operaciones de escritura retornan PERMISSION_DENIED.

Almacén Router

Encadena múltiples almacenes. Las lecturas buscan en orden hasta encontrar. Las escrituras van solo al primer almacén.

- name: config
  kind: env.storage.router
  storages:
    - app.config:memory    # Primario (escribe aquí)
    - app.config:file      # Respaldo
    - app.config:os        # Respaldo

Variables

Las variables proporcionan acceso nombrado a valores de almacenes.

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

Nomenclatura de Variables

Los nombres de variables deben contener solo: a-z, A-Z, 0-9, _

Patrones de Acceso

# Variable pública - accesible por nombre "PORT"
- name: port_var
  kind: env.variable
  variable: PORT
  storage: app.config:os
  default: "8080"

# Variable privada - accesible solo por ID "app.config:internal_key"
- name: internal_key
  kind: env.variable
  storage: app.config:secrets

Interpolación de Placeholders

Las variables registradas se incorporan a la configuración de las entradas con placeholders ${env:NAME}, resueltos centralmente en el momento de la decodificación contra este registro. Cualquier campo string en los datos de una entrada puede referenciar una variable de esta forma.

NAME es el nombre público de una variable registrada o su ID de entrada (forma de id de registro con puntos/dos puntos, ej. app.env:tls_cert). No es una variable de entorno cruda del SO: un valor del SO solo es alcanzable cuando una variable respaldada por env.storage.os está registrada bajo ese nombre.

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

Un campo cuyo valor completo es un único placeholder toma el valor tipado de la variable (convertido a bool/int/float cuando se da un valor por defecto tipado); un placeholder mezclado con texto circundante se interpola en un string. El default propio de la variable se respeta antes que el |default en línea del placeholder. Una referencia que no resuelve a nada y no tiene valor por defecto hace fallar la decodificación.

La resolución ocurre solo en el momento de la decodificación: la entrada almacenada en el registro conserva los placeholders sin resolver, de modo que los secretos resueltos nunca aparecen en los resultados de registry.get ni en el estado persistido. Las entradas que referencian ${env:...} se ordenan automáticamente en el arranque después de los almacenes env y las variables de las que dependen.

Errores

Acceso en Tiempo de Ejecución

• módulo env - Acceso en tiempo de ejecución Lua

Ver También

• Modelo de Seguridad - Control de acceso para variables de entorno
• Guía de Configuración - Patrones de configuración de aplicación