Feat(Support): 36 articles various topics

.github/styles/base/Dictionary.txt

@@ -910,6 +910,7 @@ workingDir
 workqueue
 workspace
 workspace's
+workspaced
 xai
 xbox
 xcode

app/_support/code-10-error-invalid-unique-name.md

@@ -0,0 +1,83 @@
+---
+title: "Code 10 \"invalid unique name\" error when an entity name matches a reserved Admin API endpoint"
+content_type: support
+description: "This error is returned because of a pre-existing Admin API endpoint named 'auth'."
+products:
+  - gateway
+works_on:
+  - on-prem
+  - konnect
+tldr:
+  q: "Why do I get a Code 10 \"invalid unique name\" error when creating an entity named auth?"
+  a: |
+    This error is returned because of a pre-existing Admin API endpoint named `auth`. Route
+    matching prefers the existing Admin API endpoint over a newly created entity, so entity
+    names that collide with reserved endpoints (such as `auth`, `services`, `routes`, `consumers`,
+    and others listed in the error) must be avoided when creating new entities.
+related_resources: []
+---
+
+## Problem
+
+Using a fresh `kong` image in DB mode after running `kong migrations bootstrap`, you try to get an Upstream named `auth` by making the request:
+
+```bash
+curl http://localhost:8001/upstreams/auth
+```
+
+The following error is returned:
+
+```json
+{"code":10,"name":"invalid unique name","message":"must not be one of: workspaces, consumers, certificates, services, routes, snis, upstreams, targets, consumer_groups, plugins, tags, ca_certificates, clustering_data_planes, parameters, vaults, key_sets, keys, filter_chains, files, legacy_files, workspace_entity_counters, consumer_reset_secrets, credentials, audit_requests, audit_objects, rbac_users, rbac_roles, rbac_user_roles, rbac_role_entities, rbac_role_endpoints, admins, developers, document_objects, applications, application_instances, groups, group_rbac_roles, login_attempts, keyring_meta, keyring_keys, event_hooks, licenses, consumer_group_plugins, consumer_group_consumers, rbac_user_groups"}
+```
+
+## Cause
+
+This error is returned because of a pre-existing Admin API endpoint named `auth`.
+
+## Solution
+
+Along with the referenced list in the error, avoid the following entity names when creating new entities, because Route matching prefers the existing Admin API endpoint over the newly created one:
+
+```
+/keyring,
+/timers,
+/userinfo,
+/endpoints,
+/auth,
+/status,
+/cache,
+/config,
+/metrics,
+/acme,
+/ca_certificates,
+/tags,
+/vaults,
+/certificates,
+/consumers,
+/keys,
+/services,
+/routes,
+/admins,
+/groups,
+/oauth2,
+/jwts,
+/graphql_ratelimiting_advanced_cost_decoration,
+/sessions,
+/acme_storage,
+/oauth2_tokens,
+/acls,
+/degraphql_routes,
+/plugins,
+/workspaces,
+/snis,
+/upstreams,
+/targets,
+/files,
+/licenses,
+/consumer_groups,
+/developers,
+/document_objects,
+/applications,
+/login_attempts,
+```

app/_support/configuration-does-not-fit-in-lmdb-database-error.md

@@ -0,0 +1,50 @@
+---
+title: "HTTP 413 \"Configuration does not fit in LMDB database\" error when pushing config to data planes"
+content_type: support
+description: Pushing configuration to data planes fails with an HTTP 413 "Configuration does not fit in LMDB database" error; raise `lmdb_map_size` to fix it.
+products:
+  - gateway
+works_on:
+  - on-prem
+  - konnect
+tldr:
+  q: "Why do configurations fail to push to data planes with an HTTP 413 \"Configuration does not fit in LMDB database\" error?"
+  a: |
+    The default LMDB size is `128m`, and configurations that exceed it fail to get pushed to data
+    planes. Increase the size by raising `lmdb_map_size` (for example, `KONG_LMDB_MAP_SIZE=256m`,
+    or `lmdb_map_size: "256m"` on Kubernetes, along with a larger `prefixDir` `sizeLimit`).
+related_resources: []
+---
+
+## Problem
+
+We see the following error in our Kong logs:
+
+```
+time="2023-01-31T11:12:33Z" level=error msg="could not update kong admin" error="posting new config to /config: HTTP status 413 (message: \"Configuration does not fit in LMDB database, consider raising the \\\"lmdb_map_size\\\" config for Kong\")" subsystem=dataplane-synchronizer
+```
+
+We see configurations failing to get pushed to our data planes.
+
+## Solution
+
+The default size of the LMDB is `128m`. To increase the size, make the following changes to your configuration.
+
+General:
+
+```bash
+KONG_LMDB_MAP_SIZE=256m
+```
+
+Kubernetes:
+
+```yaml
+env:
+  lmdb_map_size: "256m"
+```
+
+```yaml
+deployment:
+  prefixDir:
+    sizeLimit: 1Gi
+```

app/_support/error-attempt-to-concatenate-field-authority-a-nil-value.md

@@ -0,0 +1,60 @@
+---
+title: "Error: attempt to concatenate field 'authority' (a nil value) after upgrading to 3.X"
+content_type: support
+description: Resolve the "attempt to concatenate field 'authority' (a nil value)" error after upgrading to {{site.base_gateway}} 3.X by setting a valid KONG_ADMIN_GUI_URL value.
+products:
+  - gateway
+works_on:
+  - on-prem
+  - konnect
+tldr:
+  q: "Why do I get \"attempt to concatenate field 'authority' (a nil value)\" after upgrading to {{site.base_gateway}} 3.X?"
+  a: |
+    The `KONG_ADMIN_GUI_URL` parameter holds a value that was valid in 2.X but breaks in 3.X —
+    either an asterisk (`KONG_ADMIN_GUI_URL="*"`) or a value missing the protocol
+    (`KONG_ADMIN_GUI_URL=127.0.0.1:8002`). Set it to a valid value using the format
+    `<scheme>://<IP / HOSTNAME>(:<PORT>)`, for example `KONG_ADMIN_GUI_URL=http://127.0.0.1:8002`.
+related_resources:
+  - text: "{{site.base_gateway}} `admin_gui_url` configuration"
+    url: /gateway/configuration/#admin-gui-url
+---
+
+## Problem
+
+After upgrading to {{site.base_gateway}} 3.x, I am getting the following error on start up:
+
+```
+Error: attempt to concatenate field 'authority' (a nil value)
+```
+
+## Cause
+
+The `KONG_ADMIN_GUI_URL` parameter holds a value that was valid in 2.X but breaks in 3.X — either an asterisk (`KONG_ADMIN_GUI_URL="*"`) or a value missing the protocol (`KONG_ADMIN_GUI_URL=127.0.0.1:8002`).
+
+## Solution
+
+1. Check whether you have an asterisk in your `KONG_ADMIN_GUI_URL` parameter:
+
+   ```bash
+   KONG_ADMIN_GUI_URL="*"
+   ```
+
+   This value needs to be set with the following format:
+
+   ```
+   <scheme>://<IP / HOSTNAME>(:<PORT>)
+   ```
+
+   Items within the parenthesis are optional.
+
+2. Check whether you have not written the protocol in your `KONG_ADMIN_GUI_URL` parameter as below:
+
+   ```bash
+   KONG_ADMIN_GUI_URL=127.0.0.1:8002
+   ```
+
+   Fix it by adding the protocol as below:
+
+   ```bash
+   KONG_ADMIN_GUI_URL=http://127.0.0.1:8002
+   ```

app/_support/error-nginx-kong-lua-9-expected-near-customformat-when-using-a-custom-log-format.md

@@ -0,0 +1,76 @@
+---
+title: "Error: `nginx_kong.lua:9: '=' expected near 'customformat'` when using a custom `log_format`"
+content_type: support
+description: This can occur when attempting to use `log_format` outside the http context.
+products:
+  - gateway
+works_on:
+  - on-prem
+  - konnect
+tldr:
+  q: "Why do I get `nginx_kong.lua:9: '=' expected near 'customformat'` when using a custom `log_format`?"
+  a: |
+    This occurs when `log_format` is placed outside the `http` context in a custom nginx template —
+    `log_format` can only be used within the `http` context. When using a custom template, properly
+    add the contents of `nginx_kong.lua` inside `http {}`, with the `log_format` directive defined
+    there.
+related_resources: []
+---
+
+## Problem
+
+When attempting to use a custom `log_format` in an nginx template, for example when using the Correlation ID plugin to log IDs, the following error appears on startup or reload:
+
+```
+
+ERROR: /usr/local/share/lua/5.1/luarocks/loader.lua:104: error loading module 'kong.templates.nginx_kong' from file '/usr/local/share/lua/5.1/kong/templates/nginx_kong.lua':
+        /usr/local/share/lua/5.1/kong/templates/nginx_kong.lua:9: '=' expected near 'customformat'
+stack traceback:
+        /usr/local/share/lua/5.1/luarocks/loader.lua:104: in function </usr/local/share/lua/5.1/luarocks/loader.lua:101>
+        [C]: in function 'require'
+        /usr/local/share/lua/5.1/kong/cmd/utils/prefix_handler.lua:9: in main chunk
+        [C]: in function 'require'
+        /usr/local/share/lua/5.1/kong/cmd/reload.lua:8: in main chunk
+        [C]: in function 'require'
+        /usr/local/share/lua/5.1/kong/cmd/init.lua:71: in function </usr/local/share/lua/5.1/kong/cmd/init.lua:61>
+        /usr/local/bin/kong:9: in function 'file_gen'
+        init_worker_by_lua:46: in function <init_worker_by_lua:44>
+        [C]: in function 'xpcall'
+        init_worker_by_lua:53: in function <init_worker_by_lua:51>
+```
+
+Where `customformat` is the name you've given to the `log_format`.
+
+## Cause
+
+This can occur when attempting to use `log_format` outside the `http` context. The `log_format` directive can only be used within the `http` context.
+
+## Solution
+
+When using a custom template be sure to follow the instructions as documented, properly adding the contents of the `nginx_kong.lua` within `http {}`, for example:
+
+```bash
+
+worker_processes ${{NGINX_WORKER_PROCESSES}};
+daemon ${{NGINX_DAEMON}};       
+pid pids/nginx.pid; 
+
+events {
+    use epoll;          # a custom setting
+    multi_accept on;
+}
+
+http {
+
+log_format customformat '$remote_addr - $remote_user [$time_local] '
+              '"$request" $status $body_bytes_sent  '
+              '"$http_referer" "$http_user_agent" '
+              'Kong-Request-ID="$sent_http_Kong_Request_ID"';
+
+  # contents of the nginx_kong.lua template follow:
+
+ access_log ${{PROXY_ACCESS_LOG}} customformat;
+
+  ... # etc
+}
+```

app/_support/error-require-resty-http-not-allowed-within-sandbox.md

@@ -0,0 +1,58 @@
+---
+title: "\"require 'resty.http' not allowed within sandbox\" error in serverless or Exit Transformer plugins"
+content_type: support
+description: Plugins that execute arbitrary Lua code run in a sandbox that blocks require of certain modules; allow the module or disable the sandbox to resolve it.
+products:
+  - gateway
+works_on:
+  - on-prem
+  - konnect
+tldr:
+  q: "Why do I get \"require 'resty.http' not allowed within sandbox\" when using a plugin that runs Lua code?"
+  a: |
+    Plugins that execute arbitrary Lua code (such as serverless plugins or the exit transformer)
+    run in a sandbox with restricted access to the global environment, so they cannot `require`
+    certain modules like `resty.http`. To resolve it, either set `untrusted_lua_sandbox_requires`
+    to include the allowed modules (the preferred option, e.g. `untrusted_lua_sandbox_requires = resty.http`),
+    or turn off the sandbox by setting `untrusted_lua` to `on`. Allowing modules or disabling the
+    sandbox can create opportunities to escape it, so proceed with caution.
+related_resources:
+  - text: "`untrusted_lua_sandbox_requires`"
+    url: /gateway/configuration/#untrusted-lua-sandbox-requires
+  - text: "`untrusted_lua`"
+    url: /gateway/configuration/#untrusted-lua
+---
+
+## Problem
+
+When attempting to use a plugin that allows execution of arbitrary Lua code (that is, serverless plugins, exit transformer, and so on) you receive the message:
+
+```json
+{"message":"An unexpected error occurred"}
+```
+
+A review of the Kong error log shows something similar to the below:
+
+```
+2023/02/10 12:49:34 [error] 2107#0: *2582 [kong] init.lua:317 [pre-function] /usr/local/share/lua/5.1/kong/tools/kong-lua-sandbox.lua:171: /usr/local/share/lua/5.1/kong/tools/sandbox.lua:88: require 'resty.http' not allowed within sandbox, client: 192.168.64.1, server: kong, request: "GET /echo HTTP/1.1", host: "localhost:8000"
+```
+
+## Cause
+
+These types of plugins, by default, operate in a sandboxed environment. The sandbox function has restricted access to the global environment and only has access to standard Lua functions that will generally not cause harm to the {{site.base_gateway}} node. This means you cannot arbitrarily "require" certain modules, in our example here `resty.http`.
+
+## Solution
+
+There are two options to resolve this, however you should be aware of the potential risks.
+
+Warning:
+
+Allowing certain modules may create opportunities to escape the sandbox. For example, allowing `os` or `luaposix` may be unsafe. Turning off the sandbox will allow unchecked access that can cause severe damage. Proceed with extreme caution and ensure any such changes are thoroughly vetted in lower environments.
+
+1. The preferred option is to set the `untrusted_lua_sandbox_requires` parameter to include the modules allowed to be loaded with "require" inside the sandboxed environment. This will give you more control allowing you to explicitly and consciously define a list.
+
+   ```
+   untrusted_lua_sandbox_requires = resty.http
+   ```
+
+2. Turn off the sandbox environment by setting `untrusted_lua` to on. This allows functions to have unrestricted access to the global environment and can load any Lua modules.