環境変数システム

環境変数エントリを使用すると、ランタイムコードは公開変数名またはレジストリエントリ ID で設定を参照できます。

このページは設定リファレンスです。YAML のコードブロックは、外側のドキュメントを含む場合を除いてエントリの断片です。

ストレージとアクセス

このモデルでは、ストレージとアクセスを分離します。

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

変数は次の方法で参照できます。

• 公開名 - variable フィールドの値
• エントリ ID - 完全な namespace:name 参照

変数をエントリ ID でのみアクセス可能にする場合は、variable フィールドを省略します。 公開名を最初に取得した変数が、その短縮名を保持します。同じ公開名を持つ後続の変数も登録され、エントリ ID では引き続きアクセスできますが、既存の短縮名を置き換えることはありません。

エントリ種別

ストレージバックエンド

メモリストレージ

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

- name: runtime_env
  kind: env.storage.memory

ファイルストレージ

単純な 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 を返します。

ルーターストレージ

ルーターは複数のストレージを連結します。キャッシュミス時、読み取りは値が見つかるまでストレージを順番に検索します。見つかった値はルーターにキャッシュされるため、それ以降にバックエンドストレージを直接変更しても、そのルーターからは変更が見えません。NOT_FOUND 以外のエラーが発生するとフォールバック検索は停止します。書き込み先は最初のストレージだけです。

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

変数

変数は、公開名またはエントリ ID をストレージバックエンド内の値にマッピングします。

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

変数の命名

変数名に使用できる文字は a-z、A-Z、0-9、_ だけです。

アクセスパターン

# 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

プレースホルダー補間

登録済み変数は ${env:NAME} プレースホルダーを使用してエントリ設定に取り込まれ、デコード時にこのレジストリに対して一元的に解決されます。エントリ種別によってフィールドが不透明と指定されていない限り、エントリ設定内の文字列は解決の対象です。template.jet.source のようなソースフィールドは不透明であるため、テンプレートやプログラムのテキストは書き換えられません。

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}

値全体が単一のプレースホルダーであるフィールドは、インラインデフォルトの型を取ります。たとえば ${env:PORT|8080} は整数を生成し、保存されている値を整数に変換します。一方、${env:PORT|"8080"} は文字列のままです。周囲のテキストと混在するプレースホルダーは常に文字列になります。変数自身の default は、プレースホルダーのインライン |default より先に適用されます。解決結果がなくデフォルトもない参照は、デコードを失敗させます。

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

エラー

ランタイムアクセス

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

関連項目

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