docs: update documentation to reflect Jetstream bus (#1890)

* chore(deps): bump github.com/argoproj/pkg from 0.11.0 to 0.12.0 (#1878) Bumps [github.com/argoproj/pkg](https://github.com/argoproj/pkg) from 0.11.0 to 0.12.0. - [Release notes](https://github.com/argoproj/pkg/releases) - [Commits](argoproj/pkg@v0.11.0...v0.12.0) Signed-off-by: Julie Vogelman <[email protected]> --- updated-dependencies: - dependency-name: github.com/argoproj/pkg dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Signed-off-by: Julie Vogelman <[email protected]> * docs: fix some typos in the markdown documentation (#1880) Signed-off-by: Jesse Antoszyk <[email protected]> Signed-off-by: Julie Vogelman <[email protected]> * chore(deps): bump github.com/fsnotify/fsnotify from 1.5.2 to 1.5.3 (#1885) Bumps [github.com/fsnotify/fsnotify](https://github.com/fsnotify/fsnotify) from 1.5.2 to 1.5.3. - [Release notes](https://github.com/fsnotify/fsnotify/releases) - [Changelog](https://github.com/fsnotify/fsnotify/blob/main/CHANGELOG.md) - [Commits](fsnotify/fsnotify@v1.5.2...v1.5.3) Signed-off-by: Julie Vogelman <[email protected]> --- updated-dependencies: - dependency-name: github.com/fsnotify/fsnotify dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Signed-off-by: Julie Vogelman <[email protected]> * chore(deps): bump cloud.google.com/go/compute from 1.6.0 to 1.6.1 (#1884) Bumps [cloud.google.com/go/compute](https://github.com/googleapis/google-cloud-go) from 1.6.0 to 1.6.1. - [Release notes](https://github.com/googleapis/google-cloud-go/releases) - [Changelog](https://github.com/googleapis/google-cloud-go/blob/main/CHANGES.md) - [Commits](googleapis/google-cloud-go@pubsub/v1.6.0...pubsub/v1.6.1) Signed-off-by: Julie Vogelman <[email protected]> --- updated-dependencies: - dependency-name: cloud.google.com/go/compute dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Signed-off-by: Julie Vogelman <[email protected]> * chore(deps): bump github.com/aws/aws-sdk-go from 1.43.43 to 1.43.44 (#1886) Bumps [github.com/aws/aws-sdk-go](https://github.com/aws/aws-sdk-go) from 1.43.43 to 1.43.44. - [Release notes](https://github.com/aws/aws-sdk-go/releases) - [Changelog](https://github.com/aws/aws-sdk-go/blob/main/CHANGELOG.md) - [Commits](aws/aws-sdk-go@v1.43.43...v1.43.44) Signed-off-by: Julie Vogelman <[email protected]> --- updated-dependencies: - dependency-name: github.com/aws/aws-sdk-go dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Signed-off-by: Julie Vogelman <[email protected]> * doc: create eventbuses directory Signed-off-by: Julie Vogelman <[email protected]> * docs: new pages for stan and jetstream Signed-off-by: Julie Vogelman <[email protected]> * docs: separating anti-affinity out from the stan document Signed-off-by: Julie Vogelman <[email protected]> * docs: move some logic out of the central page into the stan-specific page Signed-off-by: Julie Vogelman <[email protected]> * docs: move some logic out of the central page into the stan-specific page Signed-off-by: Julie Vogelman <[email protected]> * docs: fix link Signed-off-by: Julie Vogelman <[email protected]> * docs: jetstream Signed-off-by: Julie Vogelman <[email protected]> * docs: moved anti-affinity into its own page Signed-off-by: Julie Vogelman <[email protected]> * docs: jetstream Signed-off-by: Julie Vogelman <[email protected]> * docs: heading size Signed-off-by: Julie Vogelman <[email protected]> * docs: moved anti-affinity into its own page Signed-off-by: Julie Vogelman <[email protected]> * Update jetstream.md Signed-off-by: Julie Vogelman <[email protected]> * docs: jetstream version Signed-off-by: Julie Vogelman <[email protected]> * docs: jetstream Signed-off-by: Julie Vogelman <[email protected]> * docs: jetstream Signed-off-by: Julie Vogelman <[email protected]> * docs: update tutorial to reflect new pages Signed-off-by: Julie Vogelman <[email protected]> * docs: eventbus overview Signed-off-by: Julie Vogelman <[email protected]> * adding another page Signed-off-by: Julie Vogelman <[email protected]> * docs: jetstream Signed-off-by: Julie Vogelman <[email protected]> * docs: changed my mind about adding the moreinfo.md page Signed-off-by: Julie Vogelman <[email protected]> * docs: stan Signed-off-by: Julie Vogelman <[email protected]> * docs: moved some STAN-specifics to the stan subpage Signed-off-by: Julie Vogelman <[email protected]> * docs: jetstream - how it works Signed-off-by: Julie Vogelman <[email protected]> * docs: distinction between NATS streaming and Jetstream for dependencies referencing same event Signed-off-by: Julie Vogelman <[email protected]> * docs: clarifying exactly once Signed-off-by: Julie Vogelman <[email protected]> * docs: quotes Signed-off-by: Julie Vogelman <[email protected]> * renaming evenbuses to eventbus for consistency with British spelling used elsewhere Signed-off-by: Julie Vogelman <[email protected]> * renaming evenbuses to eventbus for consistency with British spelling used elsewhere Signed-off-by: Julie Vogelman <[email protected]> * feat: Controller Leader Election (#1883) * Issue 1565: Controller Leader Election Signed-off-by: David Collom <[email protected]> * Fix up RBAC Signed-off-by: David Collom <[email protected]> * Adding coordination/leases to install/namespace-install Signed-off-by: David Collom <[email protected]> * Fix up rbac Signed-off-by: David Collom <[email protected]> * Adding additional RBAC for Events Signed-off-by: David Collom <[email protected]> Signed-off-by: Julie Vogelman <[email protected]> * ci: e2e build for jetstream driver (#1889) * ci: e2e build for jetstream driver Signed-off-by: Derek Wang <[email protected]> * . Signed-off-by: Derek Wang <[email protected]> Signed-off-by: Julie Vogelman <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Jesse Antoszyk <[email protected]> Co-authored-by: David Collom <[email protected]> Co-authored-by: Derek Wang <[email protected]>
argoproj · Apr 23, 2022 · 021d5b0 · 021d5b0
1 parent 928d246
commit 021d5b0
Show file tree

Hide file tree

Showing 7 changed files with 144 additions and 64 deletions.
diff --git a/docs/concepts/eventbus.md b/docs/concepts/eventbus.md
@@ -4,4 +4,4 @@ The eventbus acts as the transport layer of Argo-Events by connecting the event-
 
 Event-Sources publish the events while the sensors subscribe to the events to execute triggers.
 
-The current implementation of the eventbus is powered by NATS streaming.
+There are two implementations of the eventbus: [NATS streaming](https://docs.nats.io/legacy/stan/intro#:~:text=NATS%20Streaming%20is%20a%20data,with%20the%20core%20NATS%20platform.) and now [NATS Jetstream](https://docs.nats.io/nats-concepts/jetstream) (which will replace the former, which will be deprecated).
diff --git a/docs/eventbus/antiaffinity.md b/docs/eventbus/antiaffinity.md
@@ -0,0 +1,34 @@
+## Anti-affinity
+
+Kubernetes offers a concept of [anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/), meaning that pods are scheduled on separate nodes. The anti-affinity can either be "best effort" or a hard requirement.
+
+A best effort and a hard requirement node anti-affinity config look like
+  below, if you want to do AZ (Availability Zone) anti-affinity, change the value
+  of `topologyKey` from `kubernetes.io/hostname` to
+  `topology.kubernetes.io/zone`.
+
+```yaml
+# Best effort
+affinity:
+  podAntiAffinity:
+    preferredDuringSchedulingIgnoredDuringExecution:
+      - podAffinityTerm:
+          labelSelector:
+            matchLabels:
+              controller: eventbus-controller
+              eventbus-name: default
+          topologyKey: kubernetes.io/hostname
+        weight: 100
+```
+
+```yaml
+# Hard requirement
+affinity:
+  podAntiAffinity:
+    requiredDuringSchedulingIgnoredDuringExecution:
+      - labelSelector:
+          matchLabels:
+            controller: eventbus-controller
+            eventbus-name: default
+        topologyKey: kubernetes.io/hostname
+```
diff --git a/docs/eventbus/eventbus.md b/docs/eventbus/eventbus.md
@@ -0,0 +1,25 @@
+# EventBus
+
+![GA](../assets/ga.svg)
+
+> v0.17.0 and after
+
+EventBus is a Kubernetes
+[Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
+which is used for event transmission from EventSources to Sensors. Currently,
+EventBus is backed by [NATS](https://docs.nats.io/), including both their NATS Streaming service and their newer Jetstream service. In the future, this can be expanded to support other technologies as well.
+
+EventBus is namespaced; an EventBus object is required in a namespace to make
+EventSource and Sensor work.
+
+The common practice is to create an EventBus named `default` in the namespace. If
+you want to use a different name, or you want to have multiple EventBus in one
+namespace, you need to specify `eventBusName` in the spec of EventSource and
+Sensor correspondingly, so that they can find the right one. See EventSource
+[spec](https://github.com/argoproj/argo-events/tree/stable/api/event-source.md#eventsourcespec)
+and Sensor
+[spec](https://github.com/argoproj/argo-events/tree/stable/api/sensor.md#sensorspec).
+
+
+
+
diff --git a/docs/eventbus/jetstream.md b/docs/eventbus/jetstream.md
@@ -0,0 +1,70 @@
+## Jetstream
+
+[Jetstream](https://docs.nats.io/nats-concepts/jetstream) is the latest streaming server implemented by the NATS community, with improvements from the original NATS Streaming (which will eventually be deprecated).
+
+A simplest Jetstream EventBus example:
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: EventBus
+metadata:
+  name: default
+spec:
+  jetstream:
+    version: 2.8.1  # see 'version' section below
+```
+
+The example above brings up a Jetstream
+[StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/)
+with 3 replicas in the namespace. 
+
+Unlike with NATS Streaming, we are not offering the "exotic" option (i.e. connect to the Jetstream bus you provide), at least not now.
+
+
+## Properties
+
+Check
+[here](https://github.com/argoproj/argo-events/blob/master/api/event-bus.md#argoproj.io/v1alpha1.JetstreamBus)
+for the full spec of `jetstream`. 
+
+
+### version
+
+The version number specified in the example above is the release number for the NATS server. We will support some subset of these as we've tried them out and only plan to upgrade them as needed. To take a look at what that includes:
+```
+kubectl describe configmap argo-events-controller-config
+```
+
+### A more involved example
+
+Another example with more configuration:
+```
+apiVersion: argoproj.io/v1alpha1
+kind: EventBus
+metadata:
+  name: default
+spec:
+  jetstream:
+    version: 2.8.1
+    replicas: 5
+    persistence: # optional
+        storageClassName: standard
+        accessMode: ReadWriteOnce
+        volumeSize: 10Gi
+    streamConfig: |             # see default values in argo-events-controller-config
+      maxAge: 24h
+    settings: |
+      max_file_store: 1GB       # see default values in argo-events-controller-config
+    startArgs: 
+      - "-D"                    # debug-level logs
+```
+
+## Security
+
+For Jetstream, TLS is turned on for all client-server communication as well as between Jetstream nodes. In addition, for client-server communication we by default use password authentication (and because TLS is turned on, the password is encrypted).
+
+## How it works under the hood
+
+Jetstream has the concept of a Stream, and Subjects (i.e. topics) which are used on a Stream. From the documentation: “Each Stream defines how messages are stored and what the limits (duration, size, interest) of the retention are.” For Argo Events, we have one Stream called "default" with a single set of settings, but we have multiple subjects, each of which is named `default.<eventsourcename>.<eventname>`. Sensors subscribe to the subjects they need using durable consumers.
+
+
diff --git a/docs/eventbus.md → docs/eventbus/stan.md b/docs/eventbus.md → docs/eventbus/stan.md
@@ -1,26 +1,3 @@
-# EventBus
-
-![GA](assets/ga.svg)
-
-> v0.17.0 and after
-
-EventBus is a Kubernetes
-[Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
-which is used for events transmission from EventSources to Sensors. Currently
-EventBus is backed by
-[NATS Streaming](https://github.com/nats-io/nats-streaming-server), and it is
-open to support other technologies.
-
-EventBus is namespaced, an EventBus object is required in a namespace to make
-EventSource and Sensor work.
-
-The common practice is to create an EventBus named `default` in the namespace. If
-you want to use a different name, or you want to have multiple EventBus in one
-namespace, you need to specify `eventBusName` in the spec of EventSource and
-Sensor correspondingly, so that they can find the right one. See EventSource
-[spec](https://github.com/argoproj/argo-events/tree/stable/api/event-source.md#eventsourcespec)
-and Sensor
-[spec](https://github.com/argoproj/argo-events/tree/stable/api/sensor.md#sensorspec).
 
 ## NATS Streaming
 
@@ -130,36 +107,7 @@ for the full spec of `native`.
   [Affinity](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/)
   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 (Availability Zone) anti-affinity, change the value
-  of `topologyKey` from `kubernetes.io/hostname` to
-  `topology.kubernetes.io/zone`.
-
-```yaml
-# Best effort
-affinity:
-  podAntiAffinity:
-    preferredDuringSchedulingIgnoredDuringExecution:
-      - podAffinityTerm:
-          labelSelector:
-            matchLabels:
-              controller: eventbus-controller
-              eventbus-name: default
-          topologyKey: kubernetes.io/hostname
-        weight: 100
-```
-
-```yaml
-# Hard requirement
-affinity:
-  podAntiAffinity:
-    requiredDuringSchedulingIgnoredDuringExecution:
-      - labelSelector:
-          matchLabels:
-            controller: eventbus-controller
-            eventbus-name: default
-        topologyKey: kubernetes.io/hostname
-```
+
 
 #### More About Native NATS EventBus
 
@@ -220,5 +168,5 @@ A sample result:
 }
 ```
 
-- All the events in a namespace are published to same channel/subject/topic
+All the events in a namespace are published to same channel/subject/topic
   named `eventbus-{namespace}` in the EventBus.
diff --git a/docs/sensors/more-about-sensors-and-triggers.md b/docs/sensors/more-about-sensors-and-triggers.md
@@ -18,8 +18,8 @@ from each dependencies will be used to trigger the actions.
 
 ## Duplicate Dependencies
 
-Due to technical reasons, same `eventSourceName` and `eventName` combo can not
-be referenced twice in one `Sensor` object. For example, following dependency
+Due to technical reasons when using the NATS Streaming bus, the same `eventSourceName` and `eventName` combo can not
+be referenced twice in one `Sensor` object. For example, the following dependency
 definitions are not allowed. However, it can be referenced unlimited times in
 different `Sensor` objects, so if you do have similar requirements, use 2
 `Sensor` objects instead.
@@ -49,6 +49,8 @@ spec:
               - "50.0"
 ```
 
+Note that this is not an issue for the Jetstream bus, however.
+
 ## Events Delivery Order
 
 Following statements are based on using `NATS Streaming` as the EventBus.
@@ -60,12 +62,9 @@ acknowledge the second one before the first one is redelivered.
 
 ## Events Delivery Guarantee
 
-`NATS Streaming` offers `at-least-once` delivery guarantee. In the `Sensor`
-application, an in-memory cache is implemented to cache the events IDs delivered
-in the last 5 minutes, this is used to make sure there won't be any duplicate
-events delivered.
-
-Based on this, it is considered as `exact-once` delivery.
+`NATS Streaming` offers `at-least-once` delivery guarantee. `Jetstream` has additional features that get closer to "exactly once". In addition, in the `Sensor` application, an in-memory cache is implemented to cache the events IDs delivered
+in the last 5 minutes: this is used to make sure there won't be any duplicate
+events delivered. Based on this, we are able to achieve 1) "exactly once" in almost all cases, with the exception of pods dying while processing messages, and 2) "at least once" in all cases.
 
 ## Trigger Retries
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -38,6 +38,11 @@ nav:
       - 'tutorials/05-trigger-custom-resources.md'
       - 'tutorials/06-trigger-conditions.md'
       - 'tutorials/07-policy.md'
+  - EventBus:
+      - 'eventbus/eventbus.md'
+      - 'eventbus/stan.md'
+      - 'eventbus/jetstream.md'
+      - 'eventbus/antiaffinity.md'
   - EventSources:
       - Setup:
           - 'eventsources/setup/amqp.md'
@@ -94,7 +99,6 @@ nav:
         - 'sensors/filters/ctx.md'
         - 'sensors/filters/time.md'
       - More Information: 'sensors/more-about-sensors-and-triggers.md'
-  - 'eventbus.md'
   - 'service-accounts.md'
   - 'security.md'
   - Operator Guide:
Original file line number	Diff line number	Diff line change
Expand Up		@@ -4,4 +4,4 @@ The eventbus acts as the transport layer of Argo-Events by connecting the event-

		Event-Sources publish the events while the sensors subscribe to the events to execute triggers.

		The current implementation of the eventbus is powered by NATS streaming.
		There are two implementations of the eventbus: [NATS streaming](https://docs.nats.io/legacy/stan/intro#:~:text=NATS%20Streaming%20is%20a%20data,with%20the%20core%20NATS%20platform.) and now [NATS Jetstream](https://docs.nats.io/nats-concepts/jetstream) (which will replace the former, which will be deprecated).