diff --git a/docs/openfaas-pro/jetstream.md b/docs/openfaas-pro/jetstream.md index 6d5a7bec..b8939004 100644 --- a/docs/openfaas-pro/jetstream.md +++ b/docs/openfaas-pro/jetstream.md @@ -143,6 +143,12 @@ OpenFaaS ships with a “mixed queue”, where all invocations run in the same q See: [multiple queues](/reference/async/#multiple-queues) +### Whitelist callback URLs + +The queue-worker can restrict async callback URLs to trusted endpoints only, helping prevent untrusted callback destinations in production. + +See: [restrict async callback URLs](/reference/async/#whitelist-callback-urls) + ### Retries Users can specify a list of HTTP codes that should be retried a number of times using an exponential back-off algorithm to mitigate the impact associated with retrying messages. diff --git a/docs/reference/async.md b/docs/reference/async.md index 6ac4b2f4..35baf098 100644 --- a/docs/reference/async.md +++ b/docs/reference/async.md @@ -54,6 +54,8 @@ If you would like to receive a value from an asynchronous call you should pass a $ faas invoke figlet -H "X-Callback-Url=https://request.bin/mybin" ``` +For production use it is recommended to [restrict async callback URLs](#whitelist-callback-urls) to trusted endpoints. + It will pass back the X-Call-Id you had when you sent the initial request. You can use `netcat` to check the Call Id during invocation: @@ -84,6 +86,25 @@ X-Start-Time: 1543915495384346700 Alternatively you can specify another asynchronous or synchronous function to run instead. +### Whitelist callback URLs + +For production use, restrict async callbacks to trusted endpoints. The queue-worker accepts a list of callback URL glob patterns and will only send callbacks to matching URLs. In the OpenFaaS Helm chart this is configured with `queueWorkerPro.allowedCallbackURLs`: + +```yaml +queueWorkerPro: + allowedCallbackURLs: + - "http://gateway.openfaas:8080/function/printer" + - "https://example.com/callback" +``` + +Common patterns include: + +- `http://gateway.openfaas:8080/function/*` allows callbacks to any function through the gateway. +- `http://gateway.openfaas:8080/function/*.dev` allows callbacks to any function in the `dev` namespace. +- `https://example.com/callback` allows callbacks to one specific external endpoint. + +The default value is `["*"]`, which allows all callback URLs. Explicitly set `allowedCallbackURLs` to an empty list, `[]`, to deny all callbacks. + ### Cancel async invocations Sometimes you might need to cancel an ongoing or queued invocation. Asynchronous invocations can be cancelled by making an HTTP `DELETE` request to `/async-function/`. The call id is the X-Call-Id header that was returned when submitting the async invocation. @@ -115,7 +136,7 @@ For a synchronous call, use `http://gateway.openfaas.svc.cluster.local:8080/func The same URL applies for any `X-Callback-Url` that you wish to pass. -#### Configuration & Limits +### Configuration & Limits There are limits for asynchronous functions, which you should understand before using them: @@ -129,7 +150,7 @@ The maximum execution time for an asynchronous function is controlled by the gat `ack_wait` (default `60s`) is a NATS-level heartbeat that lets the JetStream server detect a dead queue-worker and redeliver the message. While a function is in flight, the queue-worker extends the lease automatically, so the function can run for as long as the gateway and function timeouts allow (effectively indefinitely). **Leave `ack_wait` at its default.** Increasing it does not extend how long your function may run; it only delays redelivery if a queue-worker dies mid-invocation. -#### Parallelism +### Parallelism > OpenFaaS CE supports max_inflight of 1, OpenFaaS Pro supports a custom value. @@ -145,7 +166,7 @@ Kubernetes users can tune this in the values.yaml file of the openfaas helm char The official eBook for OpenFaaS has more details on the async system in OpenFaaS. See also: [Training](/tutorials/training/) -#### Dedicated queues +### Dedicated queues > OpenFaaS Pro supports a single shared queue for asynchronous requests. OpenFaaS Enterprise supports dedicated queues per function. @@ -174,11 +195,11 @@ Then, you can invoke the function asynchronously and the queue's name will be lo faas-cli invoke --async figlet <<< "OpenFaaS" ``` -#### Verbose Output +### Verbose Output The Queue Worker component enables asynchronous processing of function requests. The default verbosity level hides the message content, but this can be viewed by setting write_debug to true when deploying. -#### Callback request headers +### Callback request headers The following additional request headers will be set when invoking the callback URL: @@ -193,4 +214,3 @@ The following additional request headers will be set when invoking the callback | X-Retry-Max | The maximum number of retries allowed for the original function or queue-worker (whichever is set) | If the X-Retry value is the same as the X-Retry-Max value, then the function has been retried the maximum number of times and will not be retried again. -