From b6c178ca4e244955633680b555b76ec6bd34ee4f Mon Sep 17 00:00:00 2001 From: Michael Martin Date: Thu, 10 Aug 2023 16:06:49 -0700 Subject: [PATCH] docs(kong.conf): add section for wasm nginx.conf directives (cherry picked from commit ef313ba5137ed5c6021f0c8d799c53c7c958cca9) --- kong.conf.default | 77 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/kong.conf.default b/kong.conf.default index 88c7fe0c4c41..d32f7a3269a2 100644 --- a/kong.conf.default +++ b/kong.conf.default @@ -1989,3 +1989,80 @@ # * No recursion is performed. Only .wasm files at the # top level are registered # * This path _may_ be a symlink to a directory. + +#------------------------------------------------------------------------------ +# WASM injected directives +#------------------------------------------------------------------------------ + +# The Nginx Wasm module (i.e. ngx_wasm_module) has its own settings, which can +# be tuned via `wasm_*` directives in the Nginx configuration file. Kong +# supports configuration of these directives via its Nginx directive injection +# mechanism. +# +# The following namespaces are supported: +# +# - `nginx_wasm_`: Injects `` into the `wasm {}` block. +# - `nginx_wasm_shm_`: Injects `shm_kv ` into the `wasm {}` block, +# allowing operators to define custom shared memory zones which are usable by +# the `get_shared_data`/`set_shared_data` Proxy-Wasm SDK functions. +# - `nginx_wasm_wasmtime_`: Injects `flag ` into the `wasmtime {}` +# block, allowing various Wasmtime-specific flags to be set. +# - `nginx__`: Injects `` into the +# `http {}` or `server {}` blocks, as specified in the Nginx injected directives +# section. +# +# The documentation for all supported directives can be found in the Nginx Wasm +# module repository: +# +# https://github.com/Kong/ngx_wasm_module/blob/main/docs/DIRECTIVES.md +# +# The Wasmtime flag documentation can be found here: +# +# https://docs.wasmtime.dev/c-api/config_8h.html +# +# There are several noteworthy ngx_wasm_module behaviors which can be tuned via +# `http {}`/`server {}` level directive injection (identical behavior in either +# level), for example: +# +# - `nginx_http_proxy_wasm_socket__timeout`: sets connection/read/send +# timeouts for Wasm dispatches. +# - `nginx_http_proxy_wasm_socket_buffer_size`: sets a buffer size for +# reading Wasm dispatch responses. +# +# The values for these settings are inherited from their `nginx_*_lua_*` +# counterparts if they have not been explicitly set. For instance, if you set +# `nginx_http_lua_socket_connect_timeout`, the value +# of this setting will be propagated to `nginx_http_wasm_socket_connect_timeout` +# unless you _also_ set `nginx_http_wasm_socket_connect_timeout`. +# +# Some TLS-related settings receive special treatment as well: +# +# - `lua_ssl_trusted_certificate`: when set, the value is propagated to the +# `nginx_wasm_tls_trusted_certificate` directive. +# - `lua_ssl_verify_depth`: when set (to a value greater than zero), several +# TLS-related `nginx_wasm_*` settings are enabled: +# * `nginx_wasm_tls_verify_cert` +# * `nginx_wasm_tls_verify_host` +# * `nginx_wasm_tls_no_verify_warn` +# +# Like other `kong.conf` fields, all injected Nginx directives documented here +# can be set via environment variable. For instance, setting: +# +# `KONG_NGINX_WASM_TLS_VERIFY_CERT=` +# +# Will inject the following in to the `wasm {}` block: +# +# `tls_verify_cert ;` +# +# There are several Nginx directives supported by ngx_wasm_module which should +# not be used because they are irrelevant to or unsupported by Kong, or they may +# conflict with Kong's own management of Proxy-Wasm. Use of these directives may +# result in unintentional breakage: +# +# - `wasm_call` +# - `module` +# - `proxy_wasm` +# - `proxy_wasm_isolation` +# - `resolver_add` +# - `proxy_wasm_request_headers_in_access` +# - `shm_queue`