oci-events

OCI Events サービス - イベント駆動型アーキテクチャ

⚠️ OCI Events の知識の不足

OCI Events サービスのパターンと構文については把握していません。

トレーニングデータには、以下に関する知識が限られており、古くなっている場合もあります。

• CloudEvents 仕様の形式（OCI では CloudEvents 1.0 を使用）
• イベントルールのフィルター構文（JSON ベースの属性マッチング）
• OCI サービスごとのイベントタイプ（100 種類以上）
• アクションタイプと統合パターン
• デッドレターキューの設定
• Events と Alarms の違い

イベント駆動型の自動化が必要な場合：

1. このスキルのリファレンスに記載されたパターンと CLI コマンドを使用してください
2. イベントのフィルター構文やイベントタイプを推測しないでください
3. Events と Alarms を混同しないでください（目的が異なります）
4. イベントルールの操作については events-cli.md を読み込んでください

把握していること：

• イベント駆動型アーキテクチャの一般的な概念
• Pub/Sub メッセージングパターン
• JSON の構造とフィルタリング

このスキルでは、OCI 固有の Events サービスのパターンと CloudEvents の統合について説明します。

---

🏗️ 重要：OCI Landing Zone Terraform モジュールを使用してください

一から作り直さないでください

❌ 誤った方法：

# Manually creating event rules, functions, notifications one by one
oci events rule create ...
oci fn application create ...
oci ons topic create ...
# Result: Inconsistent, unmaintainable, no governance

✅ 正しい方法：公式の OCI Landing Zone Terraform モジュールを使用する

# Use official OCI Landing Zone modules
module "landing_zone" {
  source  = "oracle-terraform-modules/landing-zone/oci"
  version = "~> 2.0"

  # Events configuration
  events_configuration = {
    default_compartment_id = var.security_compartment_id

    event_rules = {
      compute_instance_terminated = {
        description = "Notify when compute instance terminated"
        is_enabled  = true
        condition   = jsonencode({
          "eventType" : "com.oraclecloud.computeapi.terminateinstance"
        })
        actions = {
          notifications = [ons_topic_id]
          functions     = [security_response_function_id]
        }
      }
    }
  }
}

Landing Zone モジュールを使用する理由：

• ✅ 十分にテスト済み：数千の OCI 顧客が使用
• ✅ コンプライアンス：CIS OCI Foundations Benchmark に準拠
• ✅ 保守：Oracle が API の変更に合わせて更新
• ✅ 包括的：Events + IAM + Logging + Monitoring を統合
• ✅ 再利用可能：環境全体で一貫したパターン

公式リソース：

• OCI Landing Zone Terraform モジュール
• OCI Resource Manager スタック
• CIS OCI Foundation Benchmark

手動 CLI を使用する場合（このスキルのリファレンス）：

• 学習とプロトタイピング
• 既存のイベントルールのトラブルシューティング
• 単発の自動化タスク
• Terraform で実装する前にイベントパターンを理解する

---

あなたは OCI Events サービスのエキスパートです。このスキルでは、Claude が把握していない CloudEvents 形式、イベントフィルターパターン、アクションタイプ、デッドレターキューの設定、イベント駆動型アーキテクチャのアンチパターンについて説明します。

絶対にしてはいけないこと

❌ メトリックのしきい値監視にイベントを絶対に使用しないでください（代わりにアラームを使用してください）

BAD - Events for CPU threshold:
Event Rule: "CPU utilization > 80%"
Problem: Events don't monitor metrics!

CORRECT tool: Alarms
oci monitoring alarm create \
  --metric-name CpuUtilization \
  --threshold 80

重要な理由：イベントは状態の変化（インスタンスの作成、バケットの削除など）を対象とするものであり、継続的なメトリックを対象とするものではありません。しきい値監視にイベントを使用すると、ルールが起動することはなく、時間の無駄になります。

イベントとアラームの比較：

ユースケース	ツール	例
状態の変化	イベント	インスタンスの終了、バケットの作成、データベースの停止
メトリックのしきい値	アラーム	CPU > 80%、ディスクの容量不足、メモリーへの負荷
リソースのライフサイクル	イベント	VCN の作成、ポリシーの更新、ユーザーの追加
パフォーマンス	アラーム	クエリのレイテンシ > 2s、エラー率 > 5%

❌ デッドレターキューの設定を絶対に忘れないでください（イベントの消失を防ぐため）

# BAD - no DLQ, failed events disappear
oci events rule create \
  --display-name "Invoke-Function" \
  --condition '{"eventType": "com.oraclecloud.objectstorage.createobject"}' \
  --actions '{
    "actions": [{
      "actionType": "FAAS",
      "isEnabled": true,
      "functionId": "ocid1.fnfunc.oc1..xxx"
    }]
  }'
# If function fails, event is LOST

# GOOD - DLQ configured
oci events rule create \
  --display-name "Invoke-Function-with-DLQ" \
  --condition '{"eventType": "com.oraclecloud.objectstorage.createobject"}' \
  --actions '{
    "actions": [{
      "actionType": "FAAS",
      "isEnabled": true,
      "functionId": "ocid1.fnfunc.oc1..xxx",
      "description": "Process uploaded file"
    }]
  }' \
  --compartment-id $COMPARTMENT_ID

# Separately configure DLQ (requires Streaming)
# Events that fail delivery go to stream for retry/analysis

コストへの影響：イベントの消失は、ビジネストランザクションの損失につながります。E コマースでは、注文イベントを 1 件失うと、50～500 ドルの売上損失になります。医療では、患者記録イベントを 1 件失うと、コンプライアンス違反になります。

❌ 範囲が広すぎるイベントフィルターを絶対に使用しないでください（ノイズとコストの原因になります）

// BAD - matches ALL compute events
{
  "eventType": "com.oraclecloud.computeapi.*"
}
// Fires for: launch, terminate, reboot, resize, metadata change
// Result: 1000s of events/day, function invocations cost $$$

// GOOD - specific event types
{
  "eventType": [
    "com.oraclecloud.computeapi.terminateinstance",
    "com.oraclecloud.computeapi.launchinstance"
  ]
}
// Fires only for critical lifecycle events

コストへの影響：1 日あたり 10,000 件の不要な関数呼び出し × 0.0000002 ドル/GB 秒 × 256MB × 5s = 1 日あたり 2.56 ドル = 月あたり 77 ドルの無駄になります。

❌ イベント通知に機密データを絶対に含めないでください（セキュリティリスクになります）

// BAD - event includes passwords, keys
Event payload forwarded to notification:
{
  "data": {
    "resourceName": "db-prod-1",
    "adminPassword": "SecurePass123!",  // EXPOSED!
    "apiKey": "sk_live_xxxxx"           // EXPOSED!
  }
}

// GOOD - reference-only events
{
  "data": {
    "resourceId": "ocid1.database.oc1..xxx",
    "resourceName": "db-prod-1"
    // Function retrieves secrets from Vault using resourceId
  }
}

セキュリティへの影響：通知メールや Webhook にはイベントペイロードが記録されます。ログ内のシークレットは、認証情報の漏えい、ひいてはセキュリティ侵害につながります。

❌ リアルタイムストリーミングにイベントを絶対に使用しないでください（代わりに Streaming サービスを使用してください）

BAD use case: Process 10,000 transactions/second via Events
Events service limits: 50 requests/second per rule
Result: Throttling, dropped events

CORRECT: OCI Streaming
- Throughput: 1 MB/second per partition
- Retention: 7 days (vs Events = deliver-once)
- Consumer groups: Multiple consumers per stream

重要な理由：イベントはアクションに 1 回だけ配信されます（ベストエフォート）。Streaming は高スループットで永続性のあるメッセージング向けです。

❌ イベントが順番どおりに配信されると絶対に思い込まないでください

Event Timeline:
1. Object created at 10:00:00
2. Object updated at 10:00:01
3. Object deleted at 10:00:02

Events may arrive:
- Delete event at 10:00:03
- Create event at 10:00:04  // Out of order!
- Update event at 10:00:05

Function logic must handle out-of-order events

解決策：イベントにタイムスタンプを含め、アクションを実行する前にリソースの状態を確認するか、冪等性のある操作を使用してください。

❌ パフォーマンス上の理由から、1 つのルールに 5 つを超えるアクションを絶対に設定しないでください

# BAD - 10 actions on one rule
Event Rule → 10 different functions
Latency: 10 serial invocations = 50+ seconds

# GOOD - fan-out pattern
Event Rule → 1 function → Publishes to Streaming → 10 consumers
Latency: Parallel processing = 5 seconds

上限：1 つのルールにつきアクションは 5 つまで（厳格な上限）。5 つを超える宛先が必要な場合は、ファンアウトする設計にしてください。

❌ イベントアクション用の IAM ポリシーを絶対に設定し忘れないでください

# BAD - event rule created, but no permission to invoke function
oci events rule create ... --actions function-id
# Events fire but silently fail (403 Forbidden)

# GOOD - grant Events service permission to invoke function
oci iam policy create \
  --compartment-id $COMPARTMENT_ID \
  --name "Events-Invoke-Functions-Policy" \
  --statements '[
    "Allow service cloudEvents to use functions-family in compartment <compartment-name>"
  ]'

デバッグ地獄：イベントルールは「active」と表示されるのに、関数が起動せず、エラーメッセージもありません。根本原因は、IAM ポリシーの不足です。

段階的な読み込みの参照資料

イベントアーキテクチャのパターンとフィルター構文

次の場合に読み込んでください events-patterns.md：

• イベント駆動型アーキテクチャを設計する場合（Object Storage → Function、Instance Lifecycle → Notification）
• 複雑なイベントフィルター構文を記述する場合（コンパートメント、タグ、リソース属性）
• OCI サービス別の一般的なイベントタイプを調べる場合
• ファンアウトのパターンやイベントチェーンを理解する場合
• アクションタイプ（ONS、FAAS、OSS のいずれか）を選択する場合

次の場合は読み込まないでください：

• アンチパターンを手早く確認する場合（上記の「絶対にしてはいけないこと」で確認できます）
• イベントとアラームのどちらを選ぶか判断する場合（上記で説明しています）
• CLI の簡単な例を確認する場合（代わりに events-cli.md を使用してください）

---

OCI CLI を使用したイベント操作

次の場合に読み込んでください events-cli.md：

• フィルターを指定してイベントルールを作成する場合
• アクション（Functions、Notifications、Streaming）を設定する場合
• イベント配信の失敗をトラブルシューティングする場合
• 利用可能なイベントタイプを一覧表示する場合
• イベントルールのパターンをテストする場合

例：オブジェクトのアップロードを対象とするイベントルールの作成

oci events rule create \
  --display-name "Process-CSV-Uploads" \
  --condition '{
    "eventType": "com.oraclecloud.objectstorage.createobject",
    "data": {"resourceName": "*.csv"}
  }' \
  --actions '{
    "actions": [{
      "actionType": "FAAS",
      "isEnabled": true,
      "functionId": "ocid1.fnfunc.oc1..xxx"
    }]
  }' \
  --compartment-id $COMPARTMENT_ID

次の場合は読み込まないでください：

• 関数の実装の詳細（oci-functions スキルで説明しています）
• 通知トピックの設定（monitoring-operations スキルで説明しています）
• Streaming の設定（利用可能になり次第、streaming スキルで説明します）

---

OCI Events リファレンス（Oracle 公式ドキュメント）

次の場合に読み込んでください oci-events-reference.md：

• OCI サービスのすべてのイベントタイプを網羅した一覧が必要な場合
• OCI における CloudEvents 1.0 仕様を理解する場合
• 複雑なイベントパターンやフィルタリングを実装する場合
• Events サービスのアーキテクチャに関する Oracle 公式のガイダンスが必要な場合
• イベント配信やアクションの失敗をトラブルシューティングする場合

次の場合は読み込まないでください：

• イベントルールをすばやく作成する場合（上記の CLI の例を参照してください）
• 一般的なイベントパターンを確認する場合（このスキルのアーキテクチャパターンを参照してください）
• イベントとアラームのどちらを選ぶか判断する場合（上記の判断ツリーを参照してください）

---

このスキルを使用する場面

• イベント駆動型の自動化とワークフローを実装する場合
• サーバーレスアーキテクチャ（イベント＋関数）を構築する場合
• 「イベントルールが発火しない」問題をトラブルシューティングする場合
• イベントを介して OCI サービスを統合する場合
• リアクティブアーキテクチャ（ポーリング方式ではなく）を設計する場合
• コンプライアンスと監査証跡の自動化
• インシデント対応とセキュリティの自動化