Updates to wording about JetStream/queue-worker

Signed-off-by: Alex Ellis (OpenFaaS Ltd) <[email protected]>

Author: alexellis

docs/architecture/autoscaling.md

@@ -148,7 +148,7 @@ mean per pod = 90 / 1 = 90
 
   [Scaling to zero](/openfaas-pro/scale-to-zero) is an opt-in feature on a per function basis. It can be used in combination with any scaling mode, including *Static scaling*
 
-## Testing out the various modes
+## Examples of scaling modes
 
 A quick primer on [hey](https://github.com/rakyll/hey) a load testing tool written in Go.
 

docs/openfaas-pro/comparison.md

@@ -54,7 +54,7 @@ Did you know? OpenFaaS Pro's autoscaling engine can scale many different types o
 | Maximum replicas per function | 5                 | 1                         | No limit applied | as per Standard |
 | Scale from Zero               | Not available     | Supported                 | Supported, with additional checks for Istio | as per Standard |
 | Zero downtime updates         | Not available     | Not available             | Supported with readiness probes and rolling updates | as per Standard |
-| Autoscaling strategy          | RPS               | Not applicable            | [CPU utilization, Capacity (inflight requests), RPS, async queue-depth and Custom (e.g. Memory)](/architecture/autoscaling)      | as per Standard |
+| Autoscaling strategy          | RPS               | Not applicable            | [CPU utilization, Capacity (inflight requests), RPS, async queue-depth and Custom (e.g. Memory)](/architecture/autoscaling)      | as per Standard, plus queue-based autoscaling |
 | Autoscaling granularity       | One global rule   | Not applicable            | Configurable per function | as per Standard |
 
 Data-driven, intensive, or long running functions are best suited to capacity-based or queue-based autoscaling, which is only available in OpenFaaS Pro.
@@ -73,7 +73,7 @@ Scaling to zero is also a commercial feature, which can be opted into on a per f
 | UI Dashboard         | Legacy UI (in code-freeze)  | Dashboard is an optional add-on | [New UI dashboard](/openfaas-pro/dashboard) with metrics, logs & CI integration | as per Standard, but with support for multiple namespaces |
 | Consume secrets in `faas-cli build` for npm, Go and Pypy | Not available | Via build-time secrets | Via build-time secrets | as per Standard |
 | Kubernetes service accounts for functions      | n/a             | n/a | [Supported per function](/reference/workloads) | as per Standard |
-| Async / queueing | In-memory only, max 10 items in queue, 256KB message size | JetStream (shared queue) | JetStream (shared queue)  | JetStream (dedicated queues) |
+| Async / queueing | In-memory only, max 10 items in queue, 256KB message size | JetStream (shared queue) | JetStream (shared queue)  | JetStream (dedicated queues) and queue-based scaling |
 | Metrics         | Basic function metrics  | As per Standard  | Function, HTTP, CPU/RAM usage, and async/queue metrics      | as per Standard |
 | CPU & RAM utilization | Not available  | As per Standard | Integrated with Prometheus metrics, OpenFaaS REST API & CLI | as per Standard |
 | Grafana Dashboards      | n/a             | As per Standard | 4x dashboards supplied in [Customer Community](https://github.com/openfaas/customers) - overview, spotlight for debugging a function, queue-worker and Function Builder API | as per Standard |
@@ -83,9 +83,6 @@ Scaling to zero is also a commercial feature, which can be opted into on a per f
 | Image Pull Policy (for air-gap) | Always | As per Standard | `Always`, `IfNotPresent` or `Never` | as per Standard |
 | GPU support | Not available | Available for core services | Available for functions via Profiles | as per Standard |
 
-> Did you know? Synadia, the vendor of NATS Streaming announced the product is now deprecated, and it will receive no updates from June 2023 onwards. OpenFaaS Ltd developed an alternative based upon their newest product JetStream. [Learn more about JetStream for OpenFaaS](https://docs.openfaas.com/openfaas-pro/jetstream/)
-
-Learn how to deploy functions via kubectl: [Function CRD](/openfaas-pro/function-crd)
 
 **Advanced function configuration**
 

docs/openfaas-pro/jetstream.md

@@ -1,10 +1,16 @@
 # Queue Worker
 
-The Queue Worker is a batteries-included, scale-out queue for invoking functions asynchronously.
+> Note: This feature is included for [OpenFaaS Standard & For Enterprises](https://openfaas.com/pricing/) customers.
 
-This page is primarily concerned with how to configure the Queue Worker, you can learn about [asynchronous invocations here](/reference/async).
+The Queue Worker is part of the built-in queue system for OpenFaaS built upon NATS JetStream.
 
-> Note: This feature is included for [OpenFaaS Standard & For Enterprises](https://openfaas.com/pricing/) customers.
+It's a batteries-included solution, that's used at scale by many OpenFaaS customers in production every day.
+
+Async invocations can be submitted over HTTP by your own code or through an event-connector.
+
+This page is primarily concerned with how to configure the Queue Worker.
+
+You can learn about [asynchronous invocations here](/reference/async).
 
 ## Async use cases
 
@@ -26,15 +32,13 @@ On the blog we show reference examples built upon these architectural patterns:
 
 ## Terminology
 
-* NATS - an open source messaging system hosted by the [CNCF](https://www.cncf.io/)
-* NATS JetStream - a messaging system built on top of NATS for durable queues and message streams
+* [NATS](https://nats.io/) - an open source messaging system hosted by the [CNCF](https://www.cncf.io/)
+* [NATS JetStream](https://docs.nats.io/nats-concepts/jetstream) - a messaging system built on top of NATS for durable queues and message streams
 
 1. A JetStream Server is the original NATS Core project, running in "jetstream mode"
 2. A Stream is a message store it is used in OpenFaaS to queue async invocation messages.
 3. A Consumer is a stateful view of a stream when clients consume messages from a stream the consumer keeps track of which messages were delivered and acknowledged.
 
-Learn more about [NATS JetStream](https://docs.nats.io/nats-concepts/jetstream)
-
 ## Installation
 
 **Embedded NATS server**
@@ -67,9 +71,11 @@ Instructions for a recommended NATS production deployment are available for cust
 
 ### Queue-based scaling for functions
 
-The queue-worker uses a shared NATS Stream and NATS Consumer by default, which works well with many of the existing [autoscaling strategies](/reference/async/#autoscaling).
+The queue-worker uses a shared NATS Stream and NATS Consumer by default, which works well with many of the existing [autoscaling strategies](/reference/async/#autoscaling). Requests are processed in a FIFO order, and it is possible for certain functions to dominate or starve the queue.
 
-However, if you wish to scales functions based upon the queue depth for each, you can set up the queue-worker to scale its NATS Consumers dynamically for each function.
+A fairer approach is to scale functions based upon their respective queue depth, with a consumer created for each function as and when it is needed.
+
+The `mode` parameter can be set to `static` (default) or `function`.
 
 ```yaml
 jetstreamQueueWorker:
@@ -78,13 +84,11 @@ jetstreamQueueWorker:
     inactiveThreshold: 30s
 ```
 
-The `mode` parameter can be set to `static` or `function`.
-
-If set to `static`, the queue-worker will scale its NATS Consumers based upon the number of replicas of the queue-worker. This is the default mode, and ideal for development, or constrained environments.
+* If set to `static`, the queue-worker will scale its NATS Consumers based upon the number of replicas of the queue-worker. This is the default mode, and ideal for development, or constrained environments.
 
-If set to `function`, the queue-worker will scale its NATS Consumers based upon the number of functions that are active in the queue. This is ideal for production environments where you want to [scale your functions based upon the queue depth](/reference/autoscaling/). It also gives messages queued at different times a fairer chance of being processed earlier.
+* If set to `function`, the queue-worker will scale its NATS Consumers based upon the number of functions that are active in the queue. This is ideal for production environments where you want to [scale your functions based upon the queue depth](/reference/autoscaling/). It also gives messages queued at different times a fairer chance of being processed earlier.
 
-The `inactiveThreshold` parameter can be used to set the threshold for when a function is considered inactive. If a function is inactive for longer than the threshold, the queue-worker will delete the NATS Consumer for that function.
+* The `inactiveThreshold` parameter can be used to set the threshold for when a function is considered inactive. If a function is inactive for longer than the threshold, the queue-worker will delete the NATS Consumer for that function.
 
 ### Metrics and monitoring