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 以执行事件规则操作

你确实了解的内容：

• 通用事件驱动架构概念
• 发布/订阅消息模式
• 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

成本影响：事件丢失 = 业务交易丢失。电子商务：丢失 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

成本影响：每天 10,000 次不必要的函数调用 × $0.0000002/GB-second × 256MB × 5s = 每天 $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

为何至关重要：事件只向操作目标投递一次（尽力而为）。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

解决方案：在事件中加入时间戳，操作前检查资源状态，或使用幂等操作。

❌ 绝不要在每条规则中使用超过 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

限制：每条规则最多 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、实例生命周期 → 通知）
• 编写复杂的事件筛选器语法（区间、标签、资源属性）
• 按 OCI 服务查找常见事件类型
• 了解扇出模式和事件链
• 选择操作类型（ONS、FAAS 或 OSS）

以下情况不要加载：

• 快速查阅反模式（上面的“绝不要”列表已涵盖）
• 决定使用事件还是告警（上文已介绍）
• 快速查阅 CLI 示例（请改用 events-cli.md）

---

OCI Events 的 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 规范
• 实现复杂的事件模式和筛选
• 需要 Oracle 官方提供的 Events 服务架构指南
• 排查事件投递和操作失败问题

以下情况不要加载：

• 快速创建事件规则（请参阅上面的 CLI 示例）
• 常见事件模式（本技能中的架构模式）
• 决定使用事件还是告警（上面的决策树）

---

何时使用此技能

• 实现事件驱动的自动化和工作流
• 设置无服务器架构（事件 + 函数）
• 排查“事件规则未触发”问题
• 通过事件集成 OCI 服务
• 设计响应式架构（而非轮询）
• 合规性和审计跟踪自动化
• 事件响应和安全自动化