Umgebungssystem

Verwaltet Umgebungsvariablen durch konfigurierbare Speicher-Backends.

Übersicht

Das Umgebungssystem trennt Speicherung von Zugriff:

• Speicher - Wo Werte gespeichert werden (OS, Dateien, Speicher)
• Variablen - Benannte Referenzen zu Werten in Speichern

Variablen können referenziert werden durch:

• Öffentlichen Namen - Der variable-Feldwert (muss systemweit eindeutig sein)
• Entry-ID - Vollständige namespace:name-Referenz

Wenn Sie nicht möchten, dass eine Variable öffentlich über den Namen zugänglich ist, lassen Sie das variable-Feld weg.

Entry-Typen

Speicher-Backends

Memory-Speicher

Flüchtiger In-Memory-Speicher.

- name: runtime_env
  kind: env.storage.memory

Datei-Speicher

Persistenter Speicher im .env-Dateiformat (KEY=VALUE mit #-Kommentaren).

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

OS-Speicher

Schreibgeschützter Zugriff auf Betriebssystem-Umgebungsvariablen.

- name: os_env
  kind: env.storage.os

Immer schreibgeschützt. Set-Operationen geben PERMISSION_DENIED zurück.

Statischer Speicher

Schreibgeschützter Speicher mit direkt in der Konfiguration definierten Werten. Werte werden in den Eintrag eingebettet und können zur Laufzeit nicht geändert werden. Nützlich für öffentliche Konfigurationskonstanten, die mit einem Modul oder Paket ausgeliefert werden.

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

Immer schreibgeschützt. Set-Operationen geben PERMISSION_DENIED zurück.

Router-Speicher

Verkettet mehrere Speicher. Lesevorgänge durchsuchen diese der Reihe nach, bis ein Wert gefunden wird. Schreibvorgänge gehen nur an den ersten Speicher.

- name: config
  kind: env.storage.router
  storages:
    - app.config:memory    # Primär (Schreibvorgänge hierhin)
    - app.config:file      # Fallback
    - app.config:os        # Fallback

Variablen

Variablen bieten benannten Zugriff auf Speicherwerte.

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

Variablenbenennung

Variablennamen dürfen nur enthalten: a-z, A-Z, 0-9, _

Zugriffsmuster

# Öffentliche Variable - zugänglich über Namen "PORT"
- name: port_var
  kind: env.variable
  variable: PORT
  storage: app.config:os
  default: "8080"

# Private Variable - nur über ID "app.config:internal_key" zugänglich
- name: internal_key
  kind: env.variable
  storage: app.config:secrets

Platzhalter-Interpolation

Registrierte Variablen werden mit ${env:NAME}-Platzhaltern in die Entry-Konfiguration gezogen und beim Dekodieren zentral gegen diese Registry aufgelöst. Jedes String-Feld in den Daten eines Eintrags darf eine Variable auf diese Weise referenzieren.

NAME ist der öffentliche Name einer registrierten Variable oder deren Entry-ID (Registry-ID-Form mit Punkten/Doppelpunkten, z. B. app.env:tls_cert). Es ist keine rohe Betriebssystem-Umgebungsvariable: Ein Betriebssystemwert ist nur erreichbar, wenn unter diesem Namen eine von env.storage.os gestützte Variable registriert ist.

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

Ein Feld, dessen gesamter Wert ein einzelner Platzhalter ist, übernimmt den typisierten Wert der Variable (zu bool/int/float gecastet, wenn ein typisierter Default angegeben ist); ein Platzhalter, der mit umgebendem Text gemischt ist, wird in einen String interpoliert. Der eigene default einer Variable hat Vorrang vor dem inline angegebenen |default des Platzhalters. Eine Referenz, die zu nichts aufgelöst wird und keinen Default hat, lässt das Dekodieren fehlschlagen.

Die Auflösung geschieht nur zur Dekodierzeit: Der gespeicherte Registry-Eintrag behält die rohen Platzhalter, sodass aufgelöste Secrets nie in registry.get-Ergebnissen oder persistiertem Zustand erscheinen. Einträge, die eine Variable über die Eintrags-ID referenzieren (${env:ns:name}), ordnen sich beim Boot automatisch hinter dieser Variable ein; eine Referenz über den öffentlichen Namen erzeugt keine Abhängigkeitskante.

Fehler

Laufzeitzugriff

• env-Modul - Lua-Laufzeitzugriff

Siehe auch

• Sicherheitsmodell - Zugriffskontrolle für Umgebungsvariablen
• Konfigurationsanleitung - Anwendungskonfigurationsmuster