コンテンツにスキップ

環境変数運用方針 (EvoSpikeNet)

[!NOTE] 最新の実装状況は 機能実装ステータス (Remaining Functionality) を参照してください。

このドキュメントは、EvoSpikeNet リポジトリで使用する運用上重要な環境変数の意味と、各環境（CI／開発／ステージング／本番）での推奨設定を定めます。

目的: - モック/スタブの誤使用を防ぐ - データ出所（mock vs real）を明確にし、本番での欺瞞的データ混入を防止する - CI と本番で一貫した運用手順を提供する

対象の環境変数

EVOSPIKENET_ALLOW_STUBS

  • 説明: プロセス内のスタブ/モック実装（例: in-memory Zenoh スタブ、CARLA mock 等）を明示的に許可するフラグ。
  • 受け取り値: 0|1, false|true, no|yes, off|on（大文字小文字不問）
  • デフォルト: 0（無効）
  • 動作: 1 の場合、コードは依存ライブラリが存在しないときに"mock を用いて正常に起動する"ことを許容します。0 の場合は mock を許可せず、多くの統合ポイントは接続失敗で停止します。

推奨設定

  • CI（ユニットテスト）: 1（ユニットテストでスタブを使用するため）
  • 開発ローカル: 1（開発効率のため許可）
  • ステージング: 0（本番に近い検証を行うため非許可を推奨）
  • 本番: 0（必ず無効）

運用注意

  • 本番イメージ・本番デプロイ前に EVOSPIKENET_ALLOW_STUBS が 0 であることをデプロイ前チェックリストで確認してください。
  • 1 を本番で誤って有効化すると、依存サービスの不在を隠してしまい重大な運用リスクになります。

EVOSPIKENET_DATA_STRICT_REAL

  • 説明: データ起源の厳格性を強制するフラグ。1 の場合、source_type が mock のデータを受け取ったコンポーネントは例外を投げる/エラーとして扱います。
  • 受け取り値: 0|1, false|true, no|yes, off|on
  • デフォルト: 0（無効）

推奨設定

  • CI（ユニットテスト）: 0（ユニットテストはモックデータを利用するため）
  • 開発ローカル: 0（ローカル開発はモックを多用）
  • ステージング: 1（本番近似の検証を行うため推奨）
  • 本番: 1（必須。モック混入を防止）

運用注意

  • EVOSPIKENET_DATA_STRICT_REAL=1 を有効にすると、テストジョブでは失敗しうるため、CI のテストマトリクスで "mock 許可ジョブ" と "strict 実データ検証ジョブ" を分けて実行することを推奨します。

EVOSPIKENET_FAIL_ON_COMM_FALLBACK

  • 説明: 通信層で real Zenoh backend が利用できない場合の動作を制御します。
  • 受け取り値: 0|1, false|true, no|yes, off|on
  • デフォルト: 0（無効）
  • 動作:
  • 1: 通信 fallback（SDK relay / in-memory stub）を許可せず fail-closed で例外停止。
  • 0: EVOSPIKENET_ALLOW_STUBS の条件下で fallback を許可。

推奨設定

  • CI（ユニットテスト）: 0
  • 開発ローカル: 0
  • ステージング: 1
  • 本番: 1

EVOSPIKENET_ALLOW_COMPAT_FALLBACKS

  • 説明: compatibility API (/datasets, /images, /audio, /state, /training) の synthetic fallback 応答を許可します。
  • 受け取り値: 0|1, false|true, no|yes, off|on
  • デフォルト: 開発系環境では 1、production/staging 判定時は 0。
  • 動作: 0 の場合は 503 と compat_fallback_disabled を返却。

推奨設定

  • CI（ユニットテスト）: 1
  • 開発ローカル: 1
  • ステージング: 0
  • 本番: 0

EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS

  • 説明: 動画解析で transcript/narrative を生成できない場合のプレースホルダ応答を許可します。
  • 受け取り値: 0|1, false|true, no|yes, off|on
  • デフォルト: 開発系環境では 1、production/staging 判定時は 0。
  • 動作:
  • 1: transcript/narrative の synthetic 応答を返す。
  • 0: ジョブを failed として終了（fail-closed）。

推奨設定

  • CI（ユニットテスト）: 1
  • 開発ローカル: 1
  • ステージング: 0
  • 本番: 0

EVOSPIKENET_ALLOW_DUMMY_SERVICES

  • 説明: import 失敗時に有効化される dummy service 代替実装を許可します。
  • 受け取り値: 0|1, false|true, no|yes, off|on
  • デフォルト: 開発系環境では 1、production/staging 判定時は 0。
  • 動作: 0 の場合、dummy 実装は synthetic 応答を返さず例外を送出します。

推奨設定

  • CI（ユニットテスト）: 1
  • 開発ローカル: 1
  • ステージング: 0
  • 本番: 0

設定例（.env）

# 例: 本番向け
EVOSPIKENET_ALLOW_STUBS=0
EVOSPIKENET_DATA_STRICT_REAL=1
EVOSPIKENET_FAIL_ON_COMM_FALLBACK=1
EVOSPIKENET_ALLOW_COMPAT_FALLBACKS=0
EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS=0
EVOSPIKENET_ALLOW_DUMMY_SERVICES=0

# 例: CI / 開発向け
EVOSPIKENET_ALLOW_STUBS=1
EVOSPIKENET_DATA_STRICT_REAL=0
EVOSPIKENET_FAIL_ON_COMM_FALLBACK=0
EVOSPIKENET_ALLOW_COMPAT_FALLBACKS=1
EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS=1
EVOSPIKENET_ALLOW_DUMMY_SERVICES=1

Docker Compose での設定例

services:
  api:
    environment:
      - EVOSPIKENET_ALLOW_STUBS=0
      - EVOSPIKENET_DATA_STRICT_REAL=1
      - EVOSPIKENET_FAIL_ON_COMM_FALLBACK=1
      - EVOSPIKENET_ALLOW_COMPAT_FALLBACKS=0
      - EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS=0
      - EVOSPIKENET_ALLOW_DUMMY_SERVICES=0

デプロイ前チェックリスト（推奨）

  • 本番デプロイ前に以下を実行:
  • EVOSPIKENET_ALLOW_STUBS が 0 であることを確認
  • EVOSPIKENET_DATA_STRICT_REAL が 1 であることを確認
  • EVOSPIKENET_FAIL_ON_COMM_FALLBACK が 1 であることを確認
  • EVOSPIKENET_ALLOW_COMPAT_FALLBACKS が 0 であることを確認
  • EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS が 0 であることを確認
  • EVOSPIKENET_ALLOW_DUMMY_SERVICES が 0 であることを確認
  • スモークテストを実行し、外部依存（DB、API、CARLA 等）への接続が成功することを確認

関連コード（実装参照）

  • future_apps/smart_city_infrastructure/src/urban_data_api.py — EVOSPIKENET_DATA_STRICT_REAL を利用
  • future_apps/climate_change_prediction/src/climate_data_api.py — EVOSPIKENET_DATA_STRICT_REAL を利用
  • future_apps/brain_machine_interface/src/services/distributed_connector.py — EVOSPIKENET_ALLOW_STUBS を利用（in-memory stub の許可）
  • EvoSpikeNet-Core/evospikenet/communication.py — EVOSPIKENET_FAIL_ON_COMM_FALLBACK を利用
  • EvoSpikeNet-Core/evospikenet/api_modules/future_apps_compat_api.py — EVOSPIKENET_ALLOW_COMPAT_FALLBACKS を利用
  • EvoSpikeNet-Core/evospikenet/video_scene_service.py — EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS を利用
  • EvoSpikeNet-Core/evospikenet/services/__init__.py — EVOSPIKENET_ALLOW_DUMMY_SERVICES を利用

監査方法

  • リポジトリ全体で設定がどう使われているか確認する:
grep -R "EVOSPIKENET_ALLOW_STUBS\|EVOSPIKENET_DATA_STRICT_REAL\|EVOSPIKENET_FAIL_ON_COMM_FALLBACK\|EVOSPIKENET_ALLOW_COMPAT_FALLBACKS\|EVOSPIKENET_ALLOW_MEDIA_PLACEHOLDERS\|EVOSPIKENET_ALLOW_DUMMY_SERVICES" -n || true

最後に: この方針はセキュリティと運用健全性を高めるための最低限のガイドラインです。組織の運用ルールや CI/CD ポリシーに合わせて調整してください。