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

Tipo Descripción
env.storage.memory Almacenamiento clave-valor en memoria
env.storage.file Almacenamiento basado en archivo (formato .env)
env.storage.os Acceso de solo lectura al entorno del SO
env.storage.static Almacenamiento estático de solo lectura clave-valor
env.storage.router Encadena múltiples almacenes
env.variable Variable nombrada referenciando un almacén

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
Propiedad Tipo Por Defecto Descripción
file_path string requerido Ruta al archivo .env
auto_create boolean false Crear archivo si no existe
file_mode integer 0644 Permisos de archivo
dir_mode integer 0755 Permisos de directorio

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"
Propiedad Tipo Descripción
values map Pares clave-valor (string a string)

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
Propiedad Tipo Descripción
storages array Lista ordenada de referencias de almacenes

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
Propiedad Tipo Descripción
variable string Nombre de variable pública (opcional, debe ser único)
storage string Referencia de almacén (namespace:nombre)
default string Valor por defecto si no se encuentra
read_only boolean Prevenir modificaciones

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

Errores

Condición Tipo Reintentable
Variable no encontrada errors.NOT_FOUND no
Almacén no encontrado errors.NOT_FOUND no
Variable es de solo lectura errors.PERMISSION_DENIED no
Almacén es de solo lectura errors.PERMISSION_DENIED no
Nombre de variable inválido errors.INVALID no

Acceso en Tiempo de Ejecución

Ver También