Umgebungssystem

Umgebungseinträge ermöglichen es Laufzeitcode, Konfiguration über einen öffentlichen Variablennamen oder eine Registry-Entry-ID zu referenzieren.

Diese Seite ist eine Konfigurationsreferenz. Ihre YAML-Blöcke sind Entry-Fragmente, sofern sie kein umschließendes Dokument zeigen.

Speicherung und Zugriff

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 Wert des Feldes variable
• Entry-ID - Vollständige namespace:name-Referenz

Lassen Sie das Feld variable weg, wenn eine Variable nur über ihre Entry-ID zugänglich sein soll. Die erste Variable, die einen öffentlichen Namen beansprucht, behält diese Kurzform. Eine spätere Variable mit demselben öffentlichen Namen wird weiterhin registriert und bleibt über ihre Entry-ID erreichbar, ersetzt die bestehende Kurzform jedoch nicht.

Entry-Typen

Speicher-Backends

Memory-Speicher

Flüchtiger In-Memory-Speicher.

- name: runtime_env
  kind: env.storage.memory

Datei-Speicher

Persistenter Speicher in einem einfachen KEY=VALUE-Format. Leerzeilen und Zeilen, die mit # beginnen, werden ignoriert; Text nach # in einer Wertzeile wird als Kommentar behandelt. Werte in Anführungszeichen und Escape-Sequenzen werden nicht speziell geparst.

- 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

Ein Router verkettet mehrere Speicher. Bei einem Cache-Miss durchsuchen Lesevorgänge sie der Reihe nach, bis ein Wert gefunden wird; ein erfolgreicher Wert wird vom Router zwischengespeichert, sodass direkte Änderungen an einem dahinterliegenden Speicher anschließend nicht über diesen Router sichtbar sind. Ein anderer Fehler als NOT_FOUND beendet die Fallback-Suche. Schreibvorgänge gehen ausschließlich an den ersten Speicher.

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

Variablen

Variablen ordnen öffentliche Namen oder Entry-IDs Werten in einem Speicher-Backend zu.

- 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

# 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

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