Event-driven workflow automation for Kubernetes

Component Information

Why Argo Events?

Argo Events is the shared nervous system of the IDP Blueprint. It listens to Kubernetes, Git, and external systems, then fans out triggers to Argo Workflows, ArgoCD, or any HTTP target. The stack is deployed from K8s/events/* and synchronized through task stacks:events, so every environment boots the same event bus, governance objects, and controller configuration.

The event-driven model decouples producers from consumers. Event sources emit events to a bus, sensors listen to the bus and trigger actions. This pattern enables reactive automation: Git pushes trigger CI/CD workflows, certificate renewals trigger application restarts, and SLO breaches trigger remediation workflows.

Argo Events integrates with the Argo ecosystem (Workflows and ArgoCD), making it a natural fit for GitOps-based platforms. Event sources and sensors are Kubernetes resources, so they’re versioned in Git and deployed declaratively.

Architecture Role

Argo Events operates at Layer 2 of the platform, the Automation & Governance layer. It provides event-driven orchestration across all platform components.

Key integration points:

• Argo Workflows: Sensors trigger workflow templates based on events
• ArgoCD: Events can trigger intelligent application syncs
• Git Providers: Webhook event sources listen to repository events
• Prometheus/Alertmanager: Alert events trigger remediation workflows
• NATS EventBus: Internal message bus for event distribution

The configuration uses a three-node NATS cluster as the default EventBus. All event sources publish to this bus, and all sensors subscribe to it. This provides reliable event delivery with at-least-once semantics.

See CI/CD Model for how Argo Events integrates into the platform automation.

Scheduling & Reliability

• Both controller and webhook use the platform-events PriorityClass and pin to control-plane nodes through node affinity and tolerations so automation continues even if worker nodes are under pressure (values.yaml).
• Rolling updates use maxUnavailable: 0 / maxSurge: 1 to enforce zero-downtime restarts for the controller.
• The EventBus (eventbus.yaml) provisions a three-node NATS cluster with token auth; it is the single default bus referenced by all Sensors.

Building Sensors and Event Sources

1. Create a folder under K8s/events/<source>-<purpose>/.
2. Add EventSource and Sensor manifests that point to the default EventBus.
3. Label everything with the canonical metadata (app.kubernetes.io/part-of: idp, owner: platform-team, etc.) and include governance files if the folder introduces its own namespace.
4. Commit and let the ApplicationSet reconcile it—no manual registration is required.

Common recipes:

• Git webhooks → trigger Argo Workflows templates or invoke the ArgoCD API for intelligent syncs.
• Alertmanager or Prometheus burn-rate alerts → Sensor that dispatches remediation workflows.
• Cron-style schedules → Calendar trigger to fan out maintenance jobs.

Event Source Types

Argo Events supports multiple event source types:

Sensor Patterns

Sensors define what happens when events occur:

Trigger Argo Workflow

apiVersion: argoproj.io/v1alpha1
kind: Sensor
metadata:
  name: git-push-workflow
spec:
  dependencies:
    - name: github-push
      eventSourceName: github-webhook
      eventName: push
  triggers:
    - template:
        name: build-workflow
        argoWorkflow:
          operation: submit
          source:
            resource:
              apiVersion: argoproj.io/v1alpha1
              kind: Workflow
              metadata:
                generateName: build-
              spec:
                workflowTemplateRef:
                  name: docker-build-push

Trigger ArgoCD Sync

triggers:
  - template:
      name: argocd-sync
      http:
        url: http://argocd-server.argocd/api/v1/applications/my-app/sync
        method: POST
        headers:
          Authorization: Bearer <token>
```text

### Fan-Out Pattern

```yaml
triggers:
  - template:
      name: workflow-1
      argoWorkflow: {...}
  - template:
      name: workflow-2
      argoWorkflow: {...}
  - template:
      name: notification
      http: {...}

Observability & Operations

• Metrics: the controller exposes /metrics on port 7777; a ServiceMonitor with selector prometheus: kube-prometheus is created automatically so Prometheus scrapes it.
• Health: kubectl -n argo-events get pods verifies controller/webhook readiness; kubectl -n argo-events get eventbus shows NATS replicas.
• Event Sources: kubectl -n argo-events get eventsource lists configured event sources
• Sensors: kubectl -n argo-events get sensor lists active sensors
• EventBus Status: kubectl -n argo-events get eventbus default -o yaml shows NATS cluster health
• Redeploy: task stacks:events reapplies the ApplicationSet and Helm release; use it after changing values or adding new sources.
• Cleanup/testing: task deploy already includes the Events stack; task destroy removes it with the rest of the platform.

Extending to Other Stacks

Treat Events as a cross-cutting concern:

• CI/CD: Workflows triggered by Sensor payloads instead of manual submissions.
• Security: Stream Trivy or Kyverno reports into Sensors for auto-ticketing or rollback automation.
• SRE automation: Watch Gateway/Certificate events and run recovery flows.

Design Sensors so they emit structured CloudEvents (or JSON payloads) that downstream tasks can parse consistently.

Security Considerations

• EventBus Authentication: The NATS EventBus uses token-based authentication to prevent unauthorized event publishing
• RBAC: Event sources and sensors require specific ServiceAccounts with minimal RBAC permissions
• Network Policies: Cilium network policies restrict event source webhook endpoints to authorized sources
• Secret Management: Webhook tokens and API keys are stored in Vault and synced via External Secrets Operator

Common Use Cases

Continuous Deployment Pipeline

GitHub Push Event → EventSource (webhook)
                  → Sensor (filters by branch)
                  → Argo Workflow (build + test + push image)
                  → ArgoCD Sync (deploy to cluster)

Automated Incident Response

Prometheus Alert → Alertmanager webhook → EventSource
                                        → Sensor (filters by severity)
                                        → Argo Workflow (remediation script)
                                        → Slack notification

Scheduled Maintenance

Calendar EventSource (cron: 0 2 * * *)
  → Sensor
  → Argo Workflow (database backup)
  → Argo Workflow (cleanup old resources)
  → Notification on completion

Configuration Values