Argo EventBus is a Custom Resource controller used to create NATS Streaming clusters. It is not intended to compete with NATS Streaming Operator, but provides an easy way for Argo projects who want to use NATS Streaming as a message transmission middleware.

Run following command to install Argo EventBus controller in the namespace argo-eventbus, if you wish to install it in a different namespace, please check here to see how to do it.

kubectl create ns argo-eventbus
kubectl apply -f https://raw.githubusercontent.com/argoproj-labs/argo-eventbus/stable/manifests/install.yaml

You can create a native EventBus, or connect to an existing NATS Streaming service with exotic EventBus.

A simplest native NATS EventBus example:

apiVersion: argoproj.io/v1alpha1
kind: EventBus
metadata:
  name: default
spec:
  nats:
    native: {}

The example above brings up a NATS Streaming StatefulSet with 3 replicas in the namespace.

The following example shows an EventBus with token auth strategy and persistent volumes.

apiVersion: argoproj.io/v1alpha1
kind: EventBus
metadata:
  name: default
spec:
  nats:
    native:
      replicas: 3 # optional, defaults to 3, and requires minimal 3
      auth: token # optional, default to none
      persistence: # optional
        storageClassName: standard
        accessMode: ReadWriteOnce
        volumeSize: 10Gi

Check here for the full spec of native.

• replicas - StatefulSet replicas, defaults to 3, and requires minimal 3. According to NATS Streaming doc, the size should probably be limited to 3 to 5, and odd number is recommended.

• auth - The strategy that clients connect to NATS Streaming service, none or token is currently supported, defaults to none.

  If token strategy is used, the system will generate a token and store it in K8s secrets (one for client, one for server), EventSource and Sensor PODs will automatically load the client secret and use it to connect to the EventBus.

• antiAffinity - Whether to create the StatefulSet PODs with anti-affinity rule. Deprecated in v1.3, will be removed in v1.5, use affinity instead.

• nodeSelector - Node selector for StatefulSet PODs.

• tolerations - Tolerations for the PODs.

• persistence - Whether to use a persistence volume for the data.

• securityContext - POD level security attributes and common container settings.

• maxAge - Max Age of existing messages, i.e. 72h, 4h35m, defaults to 72h.

• imagePullSecrets - Secrets used to pull images.

• serviceAccountName - In case your firm requires to use a service account other than default.

• priority - Priority of the StatefulSet PODs.

• priorityClassName - PriorityClassName of the StatefulSet PODs.

• affinity - Affinity settings for the StatefulSet PODs.

  A best effort and a hard requirement node anti-affinity config look like below, if you want to do AZ (Availablity Zone) anti-affinity, change the value of topologyKey from kubernetes.io/hostname to topology.kubernetes.io/zone.

# Best effort
affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - podAffinityTerm:
          labelSelector:
            matchLabels:
              controller: eventbus-controller
              eventbus-name: default
          topologyKey: kubernetes.io/hostname
        weight: 100

# Hard requirement
affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchLabels:
            controller: eventbus-controller
            eventbus-name: default
        topologyKey: kubernetes.io/hostname

• Messages limit per channel defaults to 1,000,000. It could be customized by setting spec.nats.native.maxMsgs, 0 means unlimited.

• Message bytes per channel defaults to 1GB, setting spec.nats.native.maxBytes to customize it, 0 means unlimited.

• Max age of messages is 72 hours, which means messages over 72 hours will be deleted automatically. It can be cutomized by setting spec.nats.native.maxAge, i.e. 240h.

• Max subscription number is 1000.

To use an existing NATS Streaming service, follow the example below.

apiVersion: argoproj.io/v1alpha1
kind: EventBus
metadata:
  name: default
spec:
  nats:
    exotic:
      url: nats://xxxxx:xxx
      clusterID: cluster-id
      auth: token
      accessSecret:
        name: my-secret-name
        key: secret-key

Access information to a NATS Streaming EventBus can be found by running below command:

kubectl get eventbus default  -o json | jq '.status.config'

A sample result:

{
  "nats": {
    "accessSecret": {
      "key": "client-auth",
      "name": "eventbus-default-client"
    },
    "auth": "token",
    "clusterID": "eventbus-default",
    "url": "nats://eventbus-default-stan-svc:4222"
  }
}

The access token in the secret has a format like below:

token: "FcGYEn234nzHJ9BNfot8bf95N6fRx08jeXutxfFHMyvLyFJfnzxM4qVxoN1hDBJt"

Then you can use a NATS client with your preferred language to access the cluster.