Argo Events

Argo Events connects external signals to actions in Kubernetes.

The durable mental model is a four-stage event path:

external system -> EventSource -> EventBus -> Sensor -> trigger

Each stage owns a different decision.

An EventSource receives or consumes an event.
The EventBus transports the event.
A Sensor decides whether the event satisfies a dependency.
A trigger requests an action.

Argo Events is useful when Kubernetes is already your automation control plane. It is not a general replacement for every message broker, integration platform, or workflow engine.

Why Argo Events exists

External systems emit useful signals. A Git provider sends a webhook. An object store reports a new file. A message arrives on Kafka. A schedule reaches its next time.

Kubernetes can run the resulting work, but it does not provide one native resource that connects all those signals to actions. Argo Events adds that connection through Kubernetes custom resources and controllers.

You declare event ingestion and routing as Kubernetes objects. Controllers create the required pods and services. Status, logs, and metrics remain visible through the cluster's operating model.

This approach gives you a consistent control surface, but it also adds infrastructure. You must operate controllers, event transport, service accounts, network exposure, retention, and downstream actions.

The event path

Consider a repository webhook that starts an Argo Workflow:

Git provider
    |
    v
Webhook EventSource
    |
    v
EventBus
    |
    v
Sensor dependency and filters
    |
    v
Argo Workflow trigger
    |
    v
Workflow resource and pods

Argo Events owns the path through the trigger request. Argo Workflows owns the workflow after submission.

That boundary matters during failures. A healthy Sensor does not prove that the triggered Workflow succeeded. A failed Workflow does not prove that event delivery failed.

EventSource receives events

An EventSource defines how Argo Events connects to an external producer or event system. Supported categories include webhooks, schedules, object stores, cloud queues, Kubernetes resources, and messaging systems.

One EventSource object can contain more than one named event configuration. The pair of EventSource name and event name identifies the stream that a Sensor depends on.

An EventSource converts an incoming event into a CloudEvents representation and sends it to the EventBus.

For a webhook, the event contains two broad areas:

context carries CloudEvents metadata such as the identifier, source, subject, type, time, and specification version;
data carries the received headers and body.

The EventSource does not decide which business action should run. It normalizes and publishes the event.

Push and pull sources differ

A webhook is a push source. Argo Events exposes an HTTP service, and the producer sends requests to it.

A queue or stream is usually a pull source. An EventSource pod connects outward and consumes messages.

This distinction changes your security and availability design. Push sources need ingress, authentication, and traffic capacity. Pull sources need credentials, connectivity, consumer identity, and restart behavior.

EventBus transports events

The EventBus is the transport between EventSources and Sensors in one namespace. EventSources publish to it. Sensors subscribe to the event streams named by their dependencies.

The default EventBus name is default. An EventSource or Sensor can reference another EventBus name through its specification.

Current EventBus options include managed NATS JetStream, an existing JetStream service, Kafka, and the older NATS Streaming option. The transport choice affects retention, authentication, scaling, delivery behavior, and failure recovery.

Managed JetStream creates a StatefulSet. Its configuration can set replica count, persistent storage, stream limits, and a pinned NATS server version. Production configuration should pin a supported version instead of using latest.

An existing JetStream service can be referenced with jetstreamExotic. Kafka uses topics for event delivery and Sensor coordination. These options let you place transport ownership either inside or outside the Argo Events installation.

The EventBus is not just an implementation detail. Its availability and retention policy determine whether events remain available while consumers fail or restart.

Sensor resolves dependencies

A Sensor declares event dependencies as inputs and triggers as outputs. It listens on the EventBus and executes a trigger after its conditions resolve.

A dependency names:

the EventSource;
the event configuration inside that EventSource;
optional transformation;
optional filters.

One dependency handles a direct event-to-action path. Multiple dependencies can express boolean conditions such as event A and event B, or event A or event B.

When a multi-event condition resolves, the Sensor uses the latest event held for each required dependency. Earlier unmatched events can be dropped. This behavior is dependency resolution, not a general stream join with an unlimited event history.

Use separate Sensors when actions have different permissions, retry policies, owners, or failure handling. A single large Sensor can hide those boundaries.

Transform before filtering

A dependency can transform event data with Lua or JQ. A transformation runs before filters.

Only event data is available to the transformation. The CloudEvents context is not. You choose either Lua or JQ for one transformation, not both. A failed transformation discards the event.

Filters then decide whether the dependency accepts the event. Argo Events provides filters for CloudEvents context, event data, expressions, scripts, and time.

The Sensor evaluates expression, data, context, and time filter types in that documented order. A filter error rejects the event.

Keep transformation and filter logic small. Complex business decisions become difficult to test and observe when embedded in event routing configuration. Trigger a workflow or service when the decision needs durable state, richer tests, or domain-specific error handling.

Trigger requests an action

A trigger is the Sensor's output. Supported targets include Argo Workflows, Kubernetes resources, HTTP endpoints, functions, and messaging systems.

Trigger parameters can copy values from an event dependency into the target definition. This is how a webhook field can become a Workflow parameter or part of a Kubernetes object.

A trigger request is a boundary, not proof of business completion. An HTTP success response, a created Kubernetes object, and a completed Workflow represent different levels of completion.

Define the completion contract before choosing a trigger:

Does success mean that the request was accepted?
Must a created resource later become healthy?
Can the action run more than once?
Who observes and repairs a downstream failure?

Delivery and idempotency

Do not assume that every event produces exactly one business action.

The official Sensor guidance describes at-least-once delivery as the durable baseline. It also documents cases where a pod can fail while processing a message. Trigger retries are disabled by default because Argo Events cannot know whether repeating an action is safe.

You can configure a trigger retry strategy. Do so only after the target action is idempotent or carries a deduplication key.

An idempotent action produces the same intended result when repeated with the same event identifier. Examples include creating a resource with a stable unique name or recording processed event identifiers in durable storage.

Rate limits and dead-letter triggers provide additional control, but they do not make a non-idempotent action safe. Design for duplicate delivery, delayed delivery, and partial failure across every handoff.

High availability is source-specific

Setting spec.replicas above one enables EventSource high availability. Do not scale the generated Deployment manually.

The resulting behavior depends on the source type:

active-active sources let all replicas serve traffic;
active-passive sources elect one active replica because multiple consumers could conflict or duplicate events.

Argo Events normally uses NATS for EventSource leader election. A Kafka EventBus uses Kubernetes leader election. Other EventBus choices can opt into Kubernetes leader election with the documented annotation and Lease permissions.

Sensor and EventBus availability are separate concerns. A redundant EventSource cannot compensate for unavailable transport. A healthy EventBus cannot repair an unreachable webhook endpoint.

Map the whole path before calling the system highly available.

Security follows the event path

Every stage has a different trust boundary.

Protect EventSources

Authenticate exposed webhook endpoints.
Validate the producer and expected payload.
Limit ingress by network and policy where possible.
Store source credentials in Kubernetes Secrets or the documented identity mechanism.
Give a resource EventSource only list and watch access to the resources it needs.

Protect the EventBus

Enable the transport's authentication and encryption controls.
Restrict network access to producers and consumers.
Separate buses when teams need different trust, retention, or throughput boundaries.
Protect persistent volumes and external broker credentials.

Protect Sensors and triggers

A Sensor needs a service account when it creates Kubernetes resources or submits Argo Workflows. Grant only the required verbs on the required resource types.

Submitting a Workflow requires access to Workflow resources. The Workflow itself can use another service account for its pods. Keep trigger authority separate from workload authority.

Treat event data as untrusted input. Parameter substitution can move producer-controlled values into resource definitions, URLs, messages, and workload arguments. Validate at the boundary that owns the domain rule.

Observe each stage

Generated EventSource, Sensor, and EventBus pods expose Prometheus metrics. The metrics cover activity such as generated events and triggered actions.

Metrics need resource status and logs for diagnosis. Trace an incident in order:

Confirm the EventBus resource exists in the namespace.
Check controller and generated pod status.
Confirm the EventSource received or consumed the event.
Check whether the event reached the EventBus.
Inspect Sensor dependency, transformation, and filter behavior.
Inspect trigger status and retries.
Follow the downstream resource or service independently.

Monitor backlog, rejected events, transformation failures, trigger failures, retry volume, pod restarts, transport storage, and downstream saturation.

Good fits and poor fits

Argo Events fits when:

Kubernetes is the natural control plane for the action;
event routes benefit from declarative resources and Kubernetes operations;
you need to connect supported event sources to Workflows or Kubernetes objects;
dependency conditions are small and explicit;
your team can operate the EventBus and controllers.

Argo Events is a weaker fit when:

most actions and state live outside Kubernetes;
you need long-lived business process state or human workflow;
you need arbitrary stream processing, windowing, or historical joins;
a managed event service already performs the routing with less operational cost;
the team cannot design idempotency, permissions, and recovery across the event path.

Use Argo Events to decide when to request work. Use Argo Workflows when that work is a Kubernetes task graph. Use another system when its state and failure model better match the problem.

A practical learning path

Learn the four-component architecture and trace one event on paper.
Install a pinned Argo Events release in a test cluster.
Create the default EventBus and inspect its generated resources.
Run the official webhook example with a harmless log or test trigger.
Inspect the CloudEvents context and data passed to the Sensor.
Add one data filter and test accepted, rejected, and malformed events.
Parameterize a target from the event payload.
Add a second dependency and verify which event instances resolve the condition.
Design an idempotent target, then test duplicate delivery and trigger retry.
Apply least-privilege service accounts, authentication, network controls, metrics, and alerts.
Test EventSource, EventBus, Sensor, and downstream failures independently.
Rehearse transport recovery, controller upgrade, and source reconnection before production use.