Skip to main content
Let’s dive into the EventBus and the components around it. Think of the EventBus as the central highway or nervous system for your events. It is a publish/subscribe system that lets different parts of your infrastructure communicate without tight coupling: event sources publish events to the EventBus and sensors (or other consumers) subscribe to those events. This decoupling enables many producers and many consumers to coexist and evolve independently. Under the hood, Argo Events uses NATS technologies as the transport layer for the EventBus:
  • Historically NATS Streaming (STAN) has been used.
  • JetStream is the newer NATS offering and provides advanced streaming and durability features.
See the official Argo Events documentation for the CRD reference and the NATS docs for transport specifics:
Argo Events supports two general EventBus deployment modes: a managed (native) mode where Argo Events installs and manages a NATS cluster for you, and an external mode where Argo Events connects to an existing NATS/JetStream cluster you already operate.

​
What the EventBus spec configures

The EventBus Custom Resource (CRD) declares whether Argo Events should:
  • install and manage a NATS cluster (native/managed), or
  • connect to an already-running NATS/JetStream cluster (external/existing).
Typical configuration areas in the EventBus spec:
Resource areaPurpose
ModeChoose managed (native) or external (existing)
Replication / HANumber of NATS replicas to run for resilience
AuthenticationToken-based auth, TLS, or no-auth for quick tests
PersistenceDisk-backed storage for durable messaging (recommended for production)
Network / ConnectionURLs, ports, TLS and secret references for external clusters
Below are representative examples for both managed and external modes. These snippets are illustrative—consult your Argo Events release docs for the exact CRD fields supported by your version.

​
Native (managed) example

This instructs Argo Events to create and manage a NATS Streaming or JetStream cluster for you. Typical fields set here include replica count, authentication, and persistence. 
apiVersion: argoproj.io/v1alpha1
kind: EventBus
metadata:
  name: my-eventbus
spec:
  native:
    replicas: 3
    # Authentication: token, or "none" for simple test clusters
    auth:
      type: token
      token: my-nats-token
    # Persistence: enable disk storage for durability
    persistence:
      enabled: true
      # Typical storage class and size for durable message storage
      storage:
        size: 10Gi
        storageClassName: standard
    # (Optional) resources, image or other native-specific fields...
Notes:
  • Running at least three replicas is a common high-availability pattern for production clusters.
  • Persistence (disk-backed storage) prevents message loss if NATS instances restart; in-memory-only clusters can lose messages on crash/restart.
Always enable persistence and select an appropriate storageClass and size for production. If you plan to use JetStream, persistent storage is required to meet durability guarantees.

​
External / existing cluster example

If you already run a NATS or JetStream cluster, configure the EventBus to connect to it by supplying connection endpoints and any TLS/auth settings required. 
apiVersion: argoproj.io/v1alpha1
kind: EventBus
metadata:
  name: my-external-eventbus
spec:
  # Use an existing external cluster rather than creating one natively
  existingNats:
    url: "nats://nats.example.com:4222"
    # Optional TLS configuration or authentication information:
    tls:
      enabled: true
      # references to Kubernetes secrets for certs/keys would go here
    auth:
      type: token
      token: "external-nats-token"
Notes:
  • Use this mode when you operate a centralized messaging layer shared across teams or already manage a hardened NATS/JetStream cluster.
  • Ensure correct network routing, TLS certificates, and credentials so Argo Events can reliably connect to the external cluster.

​
Managed vs External — quick comparison

ModeWhen to useKey considerations
Managed / nativeSingle-tenant Argo Events deployments or quick setupsArgo manages lifecycle; convenient but you’re responsible for cluster sizing, persistence, and backups
External / existingWhen a central messaging platform is already in placeIntegrate with existing security, observability, and HA practices; network & TLS must be configured

​
JetStream vs NATS Streaming (STAN)

  • JetStream provides modern streaming semantics, richer retention and persistence options, and improved operator features.
  • STAN is legacy NATS Streaming and may be present in older Argo Events setups; check compatibility of your Argo Events version.
  • Prefer JetStream for production-grade durability and advanced streaming features when supported by your Argo Events release.

​
Best practices

  • Development / demos:
    • Use native mode with minimal replicas and optional no-auth for rapid iteration.
    • Persistence can be disabled for ephemeral test clusters.
  • Production:
    • Use native mode with at least three replicas or connect to a hardened external NATS/JetStream cluster.
    • Enable persistence with an appropriate storageClass and capacity.
    • Secure the cluster with TLS and token-based auth (or more advanced auth mechanisms).
    • Use JetStream when you need durable message storage, advanced retention, or streaming guarantees—confirm Argo Events version support.
  • Observability and operations:
    • Monitor NATS instance metrics and JetStream stream state.
    • Plan backups or retention policies for stored messages if they are business-critical.
This covers the key concepts and configuration choices when setting up the EventBus in Argo Events. Adjust the example fields above to match the exact EventBus CRD for the Argo Events release you are running.

Watch Video