acedergren/oci-events

OCI Events Service - Event-Driven Architecture

⚠️ OCI Events Knowledge Gap

You don't know OCI Events service patterns and syntax.

Your training data has limited and outdated knowledge of:

• CloudEvents specification format (OCI uses CloudEvents 1.0)
• Event rule filter syntax (JSON-based attribute matching)
• Event types by OCI service (100+ event types)
• Action types and integration patterns
• Dead letter queue configuration
• Events vs Alarms distinction

When event-driven automation is needed:

1. Use patterns and CLI commands from this skill's references
2. Do NOT guess event filter syntax or event types
3. Do NOT confuse Events with Alarms (different purposes)
4. Load events-cli.md for event rule operations

What you DO know:

• General event-driven architecture concepts
• Pub/sub messaging patterns
• JSON structure and filtering

This skill provides OCI-specific Events service patterns and CloudEvents integration.

---

🏗️ IMPORTANT: Use OCI Landing Zone Terraform Modules

Do NOT Reinvent the Wheel

❌ WRONG Approach:

# 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

✅ RIGHT Approach: Use Official OCI Landing Zone Terraform Modules

# 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]
        }
      }
    }
  }
}

Why Use Landing Zone Modules:

• ✅ Battle-tested: Used by thousands of OCI customers
• ✅ Compliance: CIS OCI Foundations Benchmark aligned
• ✅ Maintained: Oracle updates for API changes
• ✅ Comprehensive: Events + IAM + Logging + Monitoring integrated
• ✅ Reusable: Consistent patterns across environments

Official Resources:

• OCI Landing Zone Terraform Modules
• OCI Resource Manager Stacks
• CIS OCI Foundation Benchmark

When to Use Manual CLI (this skill's references):

• Learning and prototyping
• Troubleshooting existing event rules
• One-off automation tasks
• Understanding event patterns before implementing in Terraform

---

You are an OCI Events service expert. This skill provides knowledge Claude lacks: CloudEvents format, event filter patterns, action types, dead letter queue configuration, and event-driven anti-patterns.

NEVER Do This

❌ NEVER use Events for metric threshold monitoring (use Alarms instead)

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

Why critical: Events are for state changes (instance created, bucket deleted), NOT continuous metrics. Using Events for thresholds wastes time—the rule will never fire.

Events vs Alarms: | Use Case | Tool | Example | |----------|------|---------| | State change | Events | Instance terminated, bucket created, database stopped | | Metric threshold | Alarms | CPU > 80%, disk full, memory pressure | | Resource lifecycle | Events | VCN created, policy updated, user added | | Performance | Alarms | Query latency > 2s, error rate > 5% |

❌ NEVER forget to configure Dead Letter Queue (lost events)

# 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

Cost impact: Lost events = lost business transactions. E-commerce: 1 lost order event = $50-500 revenue loss. Healthcare: 1 lost patient record event = compliance violation.

❌ NEVER use overly broad event filters (noise + cost)

// 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

Cost impact: 10,000 unnecessary function invocations/day × $0.0000002/GB-second × 256MB × 5s = $2.56/day = $77/month wasted.

❌ NEVER send sensitive data in event notification (security risk)

// 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
  }
}

Security impact: Notification emails/webhooks log event payload. Secrets in logs = credential exposure = breach.

❌ NEVER use Events for real-time streaming (use Streaming service)

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

Why critical: Events deliver to actions once (best-effort). Streaming is for high-throughput, durable messaging.

❌ NEVER assume Events are delivered in order

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

Solution: Include timestamp in event, check resource state before acting, or use idempotent operations.

❌ NEVER use more than 5 actions per rule (performance)

# 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

Limit: 5 actions per rule (hard limit). Design for fan-out if >5 destinations needed.

❌ NEVER forget IAM policy for event actions

# 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>"
  ]'

Debugging hell: Event rule shows "active", function never triggers, no error message. Root cause: Missing IAM policy.

Progressive Loading References

Event Architecture Patterns and Filter Syntax

WHEN TO LOAD events-patterns.md:

• Designing event-driven architecture (Object Storage → Function, Instance Lifecycle → Notification)
• Writing complex event filter syntax (compartment, tags, resource attributes)
• Looking up common event types by OCI service
• Understanding fan-out patterns and event chaining
• Choosing between action types (ONS vs FAAS vs OSS)

Do NOT load for:

• Quick anti-pattern reference (NEVER list above covers it)
• Events vs Alarms decision (covered above)
• Quick CLI examples (use events-cli.md instead)

---

OCI CLI for Events

WHEN TO LOAD events-cli.md:

• Creating event rules with filters
• Configuring actions (Functions, Notifications, Streaming)
• Troubleshooting event delivery failures
• Listing available event types
• Testing event rule patterns

Example: Create event rule for object upload

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

Do NOT load for:

• Function implementation details (covered in oci-functions skill)
• Notification topic setup (covered in monitoring-operations skill)
• Streaming configuration (covered in streaming skill when available)

---

OCI Events Reference (Official Oracle Documentation)

WHEN TO LOAD oci-events-reference.md:

• Need comprehensive list of all OCI service event types
• Understanding CloudEvents 1.0 specification in OCI
• Implementing complex event patterns and filtering
• Need official Oracle guidance on Events service architecture
• Troubleshooting event delivery and action failures

Do NOT load for:

• Quick event rule creation (CLI examples above)
• Common event patterns (architecture patterns in this skill)
• Events vs Alarms decision (decision tree above)

---

When to Use This Skill

• Implementing event-driven automation and workflows
• Setting up serverless architectures (Events + Functions)
• Troubleshooting "event rule not firing" issues
• Integrating OCI services via events
• Designing reactive architectures (vs polling)
• Compliance and audit trail automation
• Incident response and security automation