環境変数システム

設定可能なストレージバックエンドを通じて環境変数を管理します。

概要

環境変数システムはストレージとアクセスを分離します：

• ストレージ - 値が保存される場所（OS、ファイル、メモリ）
• 変数 - ストレージ内の値への名前付き参照

変数は以下で参照できます：

• パブリック名 - variableフィールドの値（システム全体で一意である必要があります）
• エントリID - 完全なnamespace:name参照

変数を名前でパブリックにアクセス可能にしたくない場合は、variableフィールドを省略してください。

エントリ種別

ストレージバックエンド

メモリストレージ

揮発性インメモリストレージ。

- name: runtime_env
  kind: env.storage.memory

ファイルストレージ

.envファイル形式（#コメント付きKEY=VALUE）を使用した永続ストレージ。

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

OSストレージ

オペレーティングシステムの環境変数への読み取り専用アクセス。

- name: os_env
  kind: env.storage.os

常に読み取り専用。Set操作はPERMISSION_DENIEDを返します。

静的ストレージ

設定に直接定義された値を持つ読み取り専用ストレージ。値はエントリに組み込まれ、実行時に変更できません。モジュールやパックに同梱する公開設定定数に便利です。

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

常に読み取り専用。Set操作はPERMISSION_DENIEDを返します。

ルーターストレージ

複数のストレージをチェーン。読み取りは見つかるまで順番に検索。書き込みは最初のストレージにのみ送信。

- name: config
  kind: env.storage.router
  storages:
    - app.config:memory    # プライマリ（ここに書き込み）
    - app.config:file      # フォールバック
    - app.config:os        # フォールバック

変数

変数はストレージ値への名前付きアクセスを提供します。

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

変数の命名

変数名には次の文字のみ含めることができます：a-z、A-Z、0-9、_

アクセスパターン

# パブリック変数 - 名前"PORT"でアクセス可能
- name: port_var
  kind: env.variable
  variable: PORT
  storage: app.config:os
  default: "8080"

# プライベート変数 - ID "app.config:internal_key"でのみアクセス可能
- name: internal_key
  kind: env.variable
  storage: app.config:secrets

プレースホルダ補間

登録された変数は${env:NAME}プレースホルダによってエントリ設定に取り込まれ、デコード時にこのレジストリに対して一元的に解決されます。エントリのデータ内の任意の文字列フィールドは、この方法で変数を参照できます。

NAMEは登録された変数のパブリック名またはそのエントリID（ドットやコロンを含むレジストリID形式、例：app.env:tls_cert）です。これは生のOS環境変数ではありません。OSの値は、env.storage.osベースの変数がその名前で登録されている場合にのみ到達可能です。

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

フィールドの値全体が単一のプレースホルダである場合、変数の型付きの値がそのまま使われます（型付きデフォルトが指定されている場合はbool/int/floatに変換されます）。周囲のテキストと混在するプレースホルダは文字列として補間されます。変数自身のdefaultは、プレースホルダのインライン|defaultより先に適用されます。解決結果がなくデフォルトもない参照はデコードに失敗します。

解決はデコード時にのみ行われます。保存されるレジストリエントリは生のプレースホルダを保持するため、解決されたシークレットがregistry.getの結果や永続化された状態に現れることはありません。${env:...}を参照するエントリは、ブート時に依存するenvストレージと変数の後に自動的に順序付けられます。

エラー

ランタイムアクセス

• envモジュール - Luaランタイムアクセス

関連項目

• セキュリティモデル - 環境変数のアクセス制御
• 設定ガイド - アプリケーション設定パターン