From af2bc10932d0bfffb8fbe071651c36b21af96676 Mon Sep 17 00:00:00 2001 From: "Han Verstraete (OpenFaaS Ltd)" Date: Fri, 20 Jun 2025 16:56:40 +0200 Subject: [PATCH 1/3] Add note on function auth to invocations page Signed-off-by: Han Verstraete (OpenFaaS Ltd) --- docs/architecture/invocations.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/architecture/invocations.md b/docs/architecture/invocations.md index 437fca8..0db8a70 100644 --- a/docs/architecture/invocations.md +++ b/docs/architecture/invocations.md @@ -101,7 +101,8 @@ OpenFaaS For Enterprise offers authentication using JWT tokens obtained through * [TLS with OpenFaaS](/reference/tls-openfaas) * [Identity and Access Management (IAM)](/openfaas-pro/iam/overview/) -For functions, you should provide your own authentication mechanism, such as a shared token, OIDC, HMAC or basic authentication. +For functions, you can provide your own authentication mechanism, such as a shared token, OIDC, HMAC or basic authentication. +With [OpenFaaS Identity and Access Management (IAM)](https://docs.openfaas.com/openfaas-pro/iam/overview/) you can use the built in [function authentication](https://docs.openfaas.com/openfaas-pro/iam/function-authentication/) to protect your function endpoints. ## FAQ From 1e1e2969d4a6ebcd304d413361012fac7dc11733 Mon Sep 17 00:00:00 2001 From: "Han Verstraete (OpenFaaS Ltd)" Date: Fri, 20 Jun 2025 17:52:15 +0200 Subject: [PATCH 2/3] Add section on supported content types and streaming options Add a section to the workload page to list the supported HTTP streaming options: SSE, Websockets and NDJSON. Signed-off-by: Han Verstraete (OpenFaaS Ltd) --- docs/reference/workloads.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/reference/workloads.md b/docs/reference/workloads.md index 434d4fd..16e883e 100644 --- a/docs/reference/workloads.md +++ b/docs/reference/workloads.md @@ -240,3 +240,37 @@ fprocess=env HOME=/home/app Http_X_Forwarded_Proto=https ``` + +### Supported content types + +OpenFaaS supports workloads over HTTP, and most standard content types are supported. + +Since OpenFaaS has no hard limit on function execution duration, it allows for maintaining long-lived connections for streaming over HTTP. + +> **Important**: Always ensure OpenFaaS system and function timeouts are configured appropriately for your streaming workloads. See [Extended timeouts](https://docs.openfaas.com/tutorials/expanded-timeouts/) for details. + +Supported streaming options: + +**Server-Sent Events (SSE)** + +Server-Sent Events enable a function to push one-way event streams to a client. + +- Clients should include an `Accept: text/event-stream` header in their request when starting tht SSE request. +- The function's response `Content-Type` header must be set to `text/event-stream`. Each event data chunk should be prefixed with data: and terminated by two newline characters (\n\n). + +For more details on SSE, refer to [Using Server Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) + +**WebSockets** + +WebSockets provide bidirectional, full-duplex communication between a client and an OpenFaaS function. + +To create a WebSocket-enabled function, you can modify an existing OpenFaaS template or use the `Dockerfile` template as a starting point. + +For a comprehensive guide, check out: [How to Integrate WebSockets with Serverless Functions and OpenFaaS](https://www.openfaas.com/blog/serverless-websockets/) + +**Newline Delimited JSON (NDJSON)** + +NDJSON (or JSON Lines) is a format for streaming multiple independent JSON objects, each on a new line. + +- Clients should include an `Accept: application/x-ndjson` header in their request. +- The function's response `Content-Type` header should be set to `application/x-ndjson`. Each line in the response should be a complete JSON object followed by a newline character (\n). From edaf541d470d304f8dee76686029a89b4d06f9e1 Mon Sep 17 00:00:00 2001 From: "Alex Ellis (OpenFaaS Ltd)" Date: Thu, 24 Jul 2025 11:50:32 +0100 Subject: [PATCH 3/3] Rename Queue Worker page and explain Queue-based scaling Signed-off-by: Alex Ellis (OpenFaaS Ltd) --- docs/openfaas-pro/jetstream.md | 57 ++++++++++++++++++++++++++-------- mkdocs.yml | 2 +- 2 files changed, 45 insertions(+), 14 deletions(-) diff --git a/docs/openfaas-pro/jetstream.md b/docs/openfaas-pro/jetstream.md index 8ce2961..34ff31e 100644 --- a/docs/openfaas-pro/jetstream.md +++ b/docs/openfaas-pro/jetstream.md @@ -1,20 +1,23 @@ -# JetStream for OpenFaaS +# Queue Worker -The OpenFaaS async system used to be powered by NATS Streaming. The new generation of the [OpenFaaS async system](/reference/async) is backed by NATS JetStream. +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). +> Note: This feature is included for [OpenFaaS Standard & For Enterprises](https://openfaas.com/pricing/) customers. ## Async use cases -Async can be used for any OpenFaaS function invocation, where the response is not required immediately, but is either discarded or made available at a later time. Some use-cases include: +Every function in OpenFaaS can be invoked either synchronously or asynchronously. Asynchronous invocations are retried automatically, and can return their response to a given endpoint via a webhook. + +Popular use-cases include: - Batch processing and machine learning - Resilient data pipelines - Receiving webhooks - Long running jobs -On our blog we demo and explore some architectural patterns for these uses cases: +On the blog we show reference examples built upon these architectural patterns: - [Exploring the Fan out and Fan in pattern with OpenFaaS](https://www.openfaas.com/blog/fan-out-and-back-in-using-functions/) - [Generate PDFs at scale on Kubernetes using OpenFaaS and Puppeteer](https://www.openfaas.com/blog/pdf-generation-at-scale-on-kubernetes/) @@ -23,14 +26,15 @@ On our blog we demo and explore some architectural patterns for these uses cases ## Terminology -In JetStream ("js" for short), there are new terms that will help us all in running and debugging the product. +* 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 -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. -5. A Subscriber is what the queue-worker creates to start pulling messages from the stream. If the max_inflight is set to 25, the queue-worker will pull a maximum of 25 messages at a time. + 1. A JetStream Server is the NATS server, 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. + 5. A Subscriber is what the queue-worker creates to start pulling messages from the stream. -> You can learn more about JetStream here: [Docs for JetStream](https://docs.nats.io/nats-concepts/jetstream) +Learn more about [NATS JetStream](https://docs.nats.io/nats-concepts/jetstream) ## Installation @@ -44,9 +48,13 @@ nats: streamReplication: 1 ``` -If the NATS pod restarts, you will lose all messages that it contains. In your development or staging environment, this shouldn't happen very often. +If the NATS Pod restarts, you will lose all messages that it contains. In your development or staging environment. This could happen if you update the chart and the version of the NATS server has changed, or if a node is removed from the cluster. + +For production environments you should install NATS separately using its Helm chart. + +NATS can be configured with a quorum of at least 3 replicas so it can recover data if one of the replicas should crash. You can also enable a persistent volume in the NATS chart for additional durability. -For production environments you will need to install NATS separately using its Helm chart with at least 3 server replicas, so that if a pod crashes, the data can be recovered automatically. +If you are running with 3 replicas of the NATS server, then update the OpenFaaS chart to reflect that in the `nats.streamReplication` parameter. With this in place, the stream for queued messages will be replicated across the 3 NATS servers. ```yaml queueMode: jetstream @@ -58,8 +66,31 @@ nats: port: "4222" ``` +By default the NATS helm chart will be installed into the nats namespace with the name of `nats`, but you can customise this if you wish by setting the `nats.external.host` parameter. + ## Features +### 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). + +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. + +```yaml +jetstreamQueueWorker: + mode: static | function + consumer: + 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 `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. 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. + ### Metrics and monitoring Get insight into the behaviour of your queues with built in metrics. diff --git a/mkdocs.yml b/mkdocs.yml index a12c92b..49318d5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -160,7 +160,7 @@ nav: - Okta: ./openfaas-pro/sso/okta.md - SSO with the CLI: ./openfaas-pro/sso/cli.md - Function CRD: ./openfaas-pro/function-crd.md - - JetStream: ./openfaas-pro/jetstream.md + - Queue Worker: ./openfaas-pro/jetstream.md - Kafka events: ./openfaas-pro/kafka-events.md - Postgres events: ./openfaas-pro/postgres-events.md - AWS SQS events: ./openfaas-pro/sqs-events.md