環境抽象化 & Feature Flag 駆動切替¶

対象フェーズ: Closed Beta 〜 GA 全体 作成日: 2026-04-19 最終更新: 2026-04-19 ステータス: 承認待ち 前提ドキュメント: デプロイメント戦略

1. 目的¶

Recerdo のコードベースを 単一リポジトリ（single codebase, many deploys） として維持し、以下の切替操作をすべて コード変更なし で実現する。

• Beta（XServer VPS + CoreServerV2 CORE+X、全て OSS） → 本番（OCI ファースト）への移行
• メッセージキュー実装の切替（Redis+BullMQ → OCI Queue Service（AMQP 1.0））
• オブジェクトストレージの切替（Garage → OCI Object Storage）
• 認証プロバイダの多重化（Cognito 単独 → Cognito + 別 IdP の併用を将来検討）
• 特定機能の段階的ロールアウト（%ベース／組織ベース／IP ベース）
• 障害時の即時機能停止（Kill Switch）

2. 設計原則¶

2.1 三層の "差し替え可能性"¶

Recerdo では、環境差異を以下の 3 層 に分解して管理する。いずれもコード変更を伴わない。

2.2 Twelve-Factor Config への準拠¶

12-factor config に準拠し、以下を遵守する：

• ✅ 環境変数で設定を渡す（設定ファイルではなく）
• ✅ コードと設定を厳密に分離（コードを即 OSS 公開してもシークレットが漏れない）
• ✅ "環境"（dev/beta/prod）をグループ化しない（個々の環境変数は独立管理）
• ❌ if env == "production" のような分岐禁止（値の差ではなく動作の差で判断する）
• ❌ クラウド事業者名をドメイン層にハードコードしない（"oci" / "aws" / "garage" を書かない）

// ❌ BAD: 環境名で動作を切り替える
if os.Getenv("APP_ENV") == "production" {
    useOCIQueue()
} else {
    useRedisBullMQ()
}

// ✅ GOOD: 具体的な設定値で判断（Port/Adapter 経由）
queue := NewQueue(cfg.QueueProvider) // "redis-bullmq" | "oci-queue"

2.3 Feature Flag の評価ポリシー¶

• 全サービスは Feature Flag Svc（recerdo-feature-flag） に EvaluateFlag で問い合わせる
• 評価結果は ローカルキャッシュ TTL 30 秒（障害時のフォールバックは "最後の既知値" を維持）
• すべての評価は FlagEvaluation テーブルに記録（§4.3 参照）

3. 環境変数カタログ¶

3.1 命名規約¶

• UPPER_SNAKE_CASE
• ドメイン別プレフィックス：QUEUE_*、STORAGE_*、MAIL_*、AUTH_*、DB_*、MEDIA_*
• シークレット接尾辞：_SECRET、_TOKEN、_KEY（ログから自動マスク対象）

3.2 主要な環境変数（抜粋）¶

3.3 シークレット管理¶

• Beta: XServer VPS の .env.local（ファイルパーミッション 600）+ sops + age 暗号化で Git 管理
• 本番: OCI Vault から起動時に環境変数へ注入
• CI/CD: GitHub Actions の Environment Secrets

4. Feature Flag カタログ（インフラ系）¶

機能系フラグは 機能仕様：Feature Flag 管理 を参照。本節では インフラ・アーキテクチャ切替 専用のフラグを記載する。

4.1 インフラ切替フラグ¶

4.2 段階的ロールアウトの例¶

本番切替時は、Percentage Rollout を使う：

# Flipt config (例)
flag: infra.storage.provider
rules:
  - priority: 1
    segment: internal-team  # 社内テスター
    variant: oci-oss
  - priority: 2
    rollout:
      percentage: 10        # 一般ユーザー 10%
      variant: oci-oss
  - priority: 3
    variant: garage         # 残り 90% は Beta 継続

ダッシュボードで 10 → 30 → 50 → 100 % と段階的に増やし、エラー率悪化を検知したら即ロールバック。

4.3 評価ログとコンプライアンス¶

すべての Feature Flag 評価は FlagEvaluation テーブルに記録し、以下を満たす：

• 7 日間のホットストレージ保持（問題調査用）
• 30 日経過後は Audit 冷蔵バケットへ移送
• Kill Switch 発動は Audit Svc へ同期通知（監査要件）

5. アダプタパターン実装（Hexagonal Architecture）¶

5.1 ポートとアダプタ¶

ドメイン層は "Port"（インタフェース）のみを知り、"Adapter"（具象実装）は起動時に DI で差し込む。クラウド事業者名やプロダクト名はドメイン層に出現しない。

flowchart LR
  subgraph Domain["ドメイン層 (インフラ非依存)"]
    UC["UseCase: EnqueueEvent"]
    Port["Port: QueuePort"]
  end

  subgraph Adapters["アダプタ層 (差し替え可能)"]
    A1["BullMQ Adapter (Redis)"]
    A2["asynq Adapter (Redis)"]
    A3["OCI Queue Adapter (AMQP 1.0)"]
  end

  subgraph Config["起動時DIコンテナ"]
    DI["infra.queue.provider を見て Adapter を選択"]
  end

  UC -->|呼び出し| Port
  DI -->|注入| Port
  Port -.実装.-> A1
  Port -.実装.-> A2
  Port -.実装.-> A3

5.2 Go での実装サンプル¶

// ドメイン層 (domain/port/queue.go)
type QueuePort interface {
    Enqueue(ctx context.Context, job Job) error
    Dequeue(ctx context.Context) (Job, error)
}

// UseCase (application/enqueue_event.go)
type EnqueueEvent struct {
    queue QueuePort // <- ドメインは Port のみ知る
}

func (u *EnqueueEvent) Execute(ctx context.Context, ev Event) error {
    return u.queue.Enqueue(ctx, Job{Type: "event", Payload: ev})
}

// アダプタ (adapter/queue/bullmq_adapter.go)
type BullMQAdapter struct { /* Redis 接続 */ }
func (a *BullMQAdapter) Enqueue(...) error { /* BullMQ API */ }

// アダプタ (adapter/queue/oci_queue_adapter.go)
type OCIQueueAdapter struct { /* AMQP 1.0 接続 */ }
func (a *OCIQueueAdapter) Enqueue(...) error { /* OCI Queue SendMessage */ }

// DIコンテナ (cmd/main.go)
func buildQueue(cfg Config, ff FeatureFlagClient) QueuePort {
    provider := ff.StringVariant("infra.queue.provider", cfg.QueueProvider)
    switch provider {
    case "redis-bullmq": return NewBullMQAdapter(cfg)
    case "redis-asynq":  return NewAsynqAdapter(cfg)
    case "oci-queue":    return NewOCIQueueAdapter(cfg)
    default:             log.Fatalf("unknown provider: %s", provider)
    }
    return nil
}

5.3 参考実装¶

• omniqueue-rs（Rust）: Redis / RabbitMQ を統一インタフェースで抽象化した OSS
• CloudEvents SDK（CNCF）: クラウド間で互換のあるイベントフォーマット
• OpenFeature SDK（CNCF）: Feature Flag プロバイダの統一インタフェース

6. 変更の影響範囲テスト¶

アダプタ差替えの正しさは、ドメイン層の単体テストは差し替えても同じく PASS することで検証する。

6.1 テストマトリクス（CI 実行）¶

6.2 契約テスト（Contract Test）¶

各 Adapter は 同一の Port 契約 を満たすことを保証する：

// adapter/queue/contract_test.go
func TestQueuePortContract(t *testing.T) {
    providers := []QueuePort{
        NewBullMQAdapter(testCfg),
        NewAsynqAdapter(testCfg),
        NewOCIQueueAdapter(testCfg),
    }
    for _, p := range providers {
        t.Run(fmt.Sprintf("%T", p), func(t *testing.T) {
            // Enqueue / Dequeue / 冪等性 / DLQ 挙動を検証
            assertQueueContract(t, p)
        })
    }
}

7. セキュリティ考慮¶

7.1 シークレットのローテーション¶

• 目標: 四半期ごとに全シークレットをローテーション
• 実装: OCI Vault のローテーション機能を使用、アプリは起動時再読み込み
• Feature Flag 認証: Flipt は**読み取り専用トークン**を各 Svc に配布し、書き込みは Admin Console からのみ

7.2 Feature Flag の改ざん対策¶

• Flipt への書き込みは Admin Console Svc 経由 に限定
• すべての変更は Permission Svc の RBAC と Audit Svc への同期記録を伴う
• 本番環境のフラグ変更は 二段階承認（申請者 + 承認者）を Admin Console に実装

7.3 Kill Switch 発動の監査¶

• エラー率閾値超過で自動発動した場合、Slack + Email（Postfix 経由）で即時通知
• 手動発動は承認ワークフローを経由、発動者を監査ログに記録

8. ロールアウト／ロールバック手順¶

8.1 標準ロールアウト¶

1. 新 Adapter 実装を PR でマージ
2. staging 環境で `infra.*.provider` を新値に切替 → 統合テスト
3. 本番で Percentage Rollout 5% → 監視 → 20% → 50% → 100%
4. 旧 Adapter の環境変数を削除、次リリースでコード削除

8.2 緊急ロールバック¶

1. Flipt ダッシュボードで Kill Switch `infra.*.killswitch=true` 発動
2. アプリは即座に旧 Adapter へフォールバック（30秒以内）
3. インシデント調査と原因修正
4. 修正後、Kill Switch を解除して段階再開

9. 参考文献¶

• The Twelve-Factor App — Config
• OpenFeature — CNCF 標準の Feature Flag 仕様
• Flipt — セルフホスト OSS Feature Flag
• Hexagonal Architecture — AWS Prescriptive Guidance
• omniqueue-rs — Queue 抽象化実装例
• Garage Documentation
• MariaDB vs MySQL Compatibility

10. 関連ドキュメント¶

• デプロイメント戦略
• キュー抽象化設計（MS）
• Feature Flag 管理システム（MS）
• Feature Flag 管理（機能仕様）

最終更新: 2026-04-19 ポリシー適用