Merge branch 'main' into DOCU-4088

app/_hub/kong-inc/acme/how-to/_index.md

@@ -29,29 +29,33 @@ If not, add a route and a dummy service to catch this route.
 
     ```sh
     curl http://localhost:8001/services \
-      -d name=acme-example \
-      -d url=http://127.0.0.1:65535
+      --data "name=acme-example" \
+      --data "url=http://127.0.0.1:65535"
     ```
 
 2. Add a sample route if needed:
 
-    ```
+    ```bash
     curl http://localhost:8001/routes \
-      -d name=acme-example \
-      -d paths[]=/.well-known/acme-challenge \
-      -d service.name=acme-example
+      --data "name=acme-example" \
+      --data "paths[]=/.well-known/acme-challenge" \
+      --data "service.name=acme-example"
     ```
 
 3. Enable the plugin:
 
     ```sh
     curl http://localhost:8001/plugins \
-      -d name=acme \
-      -d config.account_email=yourname@yourdomain.com \
-      -d config.tos_accepted=true \
-      -d config.domains[]=my.secret.domains.com
+      --data "name=acme" \
+      --data "config.account_email=yourname@yourdomain.com" \
+      --data "config.tos_accepted=true" \
+      --data "config.domains[]=my.secret.domains.com" \
+      --data "config.storage=kong"
     ```
 
+This example uses `kong` storage for demo purposes, which stores the certificate in the Kong database.
+`kong` storage is not supported in DB-less mode or {{site.konnect_short_name}}, use one of the other [storage options](/hub/kong-inc/acme/#storage-options) instead.
+
 Setting `tos_accepted` to *true* implies that you have read and accepted
 [terms of service](https://letsencrypt.org/repository/).
 
@@ -68,8 +72,8 @@ Assume Kong proxy is accessible via http://mydomain.com and https://mydomain.com
 
     ```sh
     curl http://localhost:8001/acme \
-    -d host=mydomain.com \
-    -d test_http_challenge_flow=true
+      --data "host=mydomain.com" \
+      --data "test_http_challenge_flow=true"
     ```
 
 1. Trigger certificate creation:

app/_hub/kong-inc/acme/how-to/_local-testing-development.md

@@ -3,62 +3,73 @@ nav_title: Local testing and development
 title: Local testing and development
 ---
 
-## Local testing and development
-
-### Run ngrok
+## Run ngrok
 
 [ngrok](https://ngrok.com) exposes a local URL to the internet. [Download ngrok](https://ngrok.com/download) and install.
 
-*`ngrok` is only needed for local testing or development, it's **not** a requirement for the plugin itself.*
+{:.note}
+> `ngrok` is only needed for local testing or development, it's **not** a requirement for the plugin itself.
 
-Run ngrok with:
+Run ngrok:
 
 ```bash
 ./ngrok http localhost:8000
-# Shows something like
-# ...
-# Forwarding                    http://e2e034a5.ngrok.io -> http://localhost:8000
-# Forwarding                    https://e2e034a5.ngrok.io -> http://localhost:8000
-# ...
-# Substitute "e2e034a5.ngrok.io" with the host shows in your ngrok output
-export NGROK_HOST=e2e034a5.ngrok.io
+```
+
+The output includes your generated hostname:
+```bash
+Forwarding    http://example-host-12345.ngrok.io -> http://localhost:8000
+Forwarding    https://example-host-12345.ngrok.io -> http://localhost:8000
+```
+
+Substitute `example-host-12345.ngrok.io` with the host shown in your ngrok output 
+and export the hostname to an environment variable:
+
+```bash
+export NGROK_HOST=example-host-12345.ngrok.io
 ```
 
 Leave the process running.
 
-### Configure and test the plugin
+## Configure the plugin
 
 1. Configure a service:
 
     ```bash
     curl http://localhost:8001/services \
-    -d name=acme-test \
-    -d url=https://httpbin.konghq.com
+      --data "name=acme-test" \
+      --data "url=https://httpbin.konghq.com"
     ```
 
 1. Configure a route:
-    ```
+    ```bash
     curl http://localhost:8001/routes \
-    -d service.name=acme-test \
-    -d hosts=$NGROK_HOST
+      --data "service.name=acme-test" \
+      --data "hosts=$NGROK_HOST"
     ```
 
 1. Enable the plugin:
 
     ```bash
     curl localhost:8001/plugins \
-    -d name=acme \
-    -d config.account_email=test@test.com \
-    -d config.tos_accepted=true \
-    -d config.domains[]=$NGROK_HOST
+      --data "name=acme" \
+      --data "config.account_email=test@test.com" \
+      --data "config.tos_accepted=true" \
+      --data "config.domains[]=$NGROK_HOST" \
+      --data "config.storage=kong"
     ```
 
+    This example uses `kong` storage for demo purposes, which stores the certificate in the Kong database.
+    `kong` storage is not supported in DB-less mode or {{site.konnect_short_name}}, use one of the other [storage options](/hub/kong-inc/acme/#storage-options) instead.
+
+## Validate
+
 1. Trigger certificate creation:
 
     ```bash
     curl https://$NGROK_HOST:8443 --resolve $NGROK_HOST:8443:127.0.0.1 -vk
-    # Wait for several seconds
     ```
+    This might take a few seconds.
 
 1. Check the new certificate:
 

app/_hub/kong-inc/acme/overview/_index.md

@@ -13,9 +13,39 @@ IP and a resolvable DNS. Kong also needs to accept proxy traffic from port `80`.
 > * A wildcard or star (`*`) certificate is not supported. Each domain must have its
 own certificate.
 
+## Supported storage types
+
+You can set the backend storage for the plugin using the [`config.storage`](/hub/kong-inc/acme/configuration/#config-storage) parameter.
+The backend storage available depends on the [topology](/gateway/latest/production/deployment-topologies/) of your {{site.base_gateway}} environment: 
+
+Storage type | Description   | Traditional mode | Hybrid mode | DB-less | {{site.konnect_short_name}}
+-------------|---------------|------------------|-------------|---------|----------------------------
+`shm` | Lua shared dict storage. <br> This storage is volatile between Nginx restarts (not reloads). | ✅ | ❌ | ✅ | ❌
+`kong`| Kong database storage. | ✅ | ✅ <sup>1</sup> | ❌ | ❌
+`redis` | [Redis-based](https://redis.io/docs/latest/) storage.    | ✅ | ✅ | ✅ | ✅
+`consul` | [HashiCorp Consul](https://www.consul.io/) storage.    | ✅ | ✅ | ✅ | ✅
+`vault` | [HashiCorp Vault](https://www.vaultproject.io/) storage. <br> Only the [KV V2](https://www.vaultproject.io/api/secret/kv/kv-v2.html) backend is supported. | ✅ | ✅ | ✅ | ✅
+
+{:.note .no-icon}
+> **\[1\]**: Due to current the limitations of hybrid mode, `kong` storage only supports certificate generation from
+the Admin API but not the proxy side, as the data planes don't have access to the Kong database. 
+See the [hybrid mode workflow](#hybrid-mode-workflow) for details. 
+
+To configure a storage type other than `kong`, see [lua-resty-acme](https://github.com/fffonion/lua-resty-acme#storage-adapters) for example configurations.
+
+## Running with or without a database
+
+In a database-backed deployment, the plugin creates an SNI and certificate entity in Kong to
+serve the certificate. If the SNI or certificate for the current request is already set
+in the database, it will be overwritten.
+
+In DB-less mode, the plugin takes over certificate handling. If the SNI or
+certificate entity is already defined in Kong, it will be overridden by the
+response.
+
 ## Workflow
 
-A `http-01` challenge workflow between the {{site.base_gateway}} and the ACME server is described below:
+An `http-01` challenge workflow between the {{site.base_gateway}} and the ACME server is described below:
 
 1. The client sends a proxy or Admin API request that triggers certificate generation for `mydomain.com`.
 2. The {{site.base_gateway}} sends a request to the ACME server to start the validation process.
@@ -27,53 +57,38 @@ A `http-01` challenge workflow between the {{site.base_gateway}} and the ACME se
 
 ### Hybrid mode workflow
 
-`"shm"` storage type is not available in Hybrid Mode.
-
-Due to current the limitations of Hybrid Mode, `"kong"` storage only supports certificate generation from
-the Admin API but not the proxy side.
-
-`"kong"` storage in Hybrid Mode works in following flow:
+`kong` storage in hybrid mode works in following flow:
 
 1. The client sends an Admin API request that triggers certificate generation for `mydomain.com`.
-2. The Kong Control Plane requests the ACME server to start the validation process.
-3. The ACME server returns a challenge response detail to the Kong Control Plane.
-4. The Kong Control Plane propagates the challenge response detail to the Kong Data Plane.
-5. `mydomain.com` is publicly resolvable to the Kong Data Plane that serves the challenge response.
+2. The Kong control plane requests the ACME server to start the validation process.
+3. The ACME server returns a challenge response detail to the Kong control plane.
+4. The Kong control plane propagates the challenge response detail to the Kong data plane.
+5. `mydomain.com` is publicly resolvable to the Kong data plane that serves the challenge response.
 6. The ACME server checks if the previous challenge has a response at `mydomain.com`.
-7. The Kong Control Plane checks the challenge status and if passed, downloads the certificate from the ACME server.
-8. The Kong Control Plane propagates the new certificates to the Kong Data Plane.
-9. The Kong Data Plane uses the new certificate to serve TLS requests.
+7. The Kong control plane checks the challenge status and if passed, downloads the certificate from the ACME server.
+8. The Kong control plane propagates the new certificates to the Kong data plane.
+9. The Kong data plane uses the new certificate to serve TLS requests.
 
-All external storage types work as usual in Hybrid Mode. Note both the Control Plane and Data Planes
-need to connect to the same external storage cluster. It's also a good idea to setup replicas to avoid
+All external storage types work as usual in hybrid mode. Both the control plane and data planes
+need to connect to the same external storage cluster. It's also a good idea to set up replicas to avoid
 connecting to same node directly for external storage.
 
-External storage in Hybrid Mode works in following flow:
+External storage in hybrid mode (`redis`, `consul`, or `vault`) works in the following way:
 
 1. The client send a proxy or Admin API request that triggers certificate generation for `mydomain.com`.
-2. The Kong Control Plane or Data Plane requests the ACME server to start the validation process.
+2. The Kong control plane or data plane requests the ACME server to start the validation process.
 3. The ACME server returns a challenge response detail to the {{site.base_gateway}}.
-4. The Kong Control Plane or Data Plane stores the challenge response detail in external storage.
-5. `mydomain.com` is publicly resolvable to the Kong Data Plane that reads and serves the challenge response from external storage.
+4. The Kong control plane or data plane stores the challenge response detail in external storage.
+5. `mydomain.com` is publicly resolvable to the Kong data plane that reads and serves the challenge response from external storage.
 6. The ACME server checks if the previous challenge has a response at `mydomain.com`.
-7. The Kong Control Plane or Data Plane checks the challenge status and if passed, downloads the certificate from the ACME server.
-8. The Kong Control Plane or Data Plane stores the new certificates in external storage.
-9. The Kong Data Plane reads from external storage and uses the new certificate to serve TLS requests.
+7. The Kong control plane or data plane checks the challenge status and if passed, downloads the certificate from the ACME server.
+8. The Kong control plane or data plane stores the new certificates in external storage.
+9. The Kong data plane reads from external storage and uses the new certificate to serve TLS requests.
 
 
-## Running with or without a database
-
-In database mode, the plugin creates an SNI and Certificate entity in Kong to
-serve the certificate. If SNI or Certificate for the current request is already set
-in the database, they will be overwritten.
-
-In DB-less mode, the plugin takes over certificate handling. If the SNI or
-Certificate entity is already defined in Kong, they will be overridden by the
-response.
-
 ## EAB support
 
-External account binding (EAB) is supported as long as `eab_kid` and `eab_hmac_key` are provided.
+External account binding (EAB) is supported as long as the `eab_kid` and `eab_hmac_key` values are provided.
 
 The following CA provider's external account can be registered automatically, without specifying
 the `eab_kid` or `eab_hmac_key`:
@@ -125,7 +140,6 @@ the `eab_kid` or `eab_hmac_key`:
     }
 ```
 
-To configure a storage type other than `kong`, refer to [lua-resty-acme](https://github.com/fffonion/lua-resty-acme#storage-adapters).
 
 ## Get started with the ACME plugin
 

app/_hub/kong-inc/grpc-gateway/how-to/_index.md

@@ -69,7 +69,7 @@ service HelloService {
       }
       post: "/v1/messages/"
       body: "*"
-    }
+    };
   }
 }
 

app/_hub/optum/kong-spec-expose/examples/_index.yml

@@ -1,3 +1,3 @@
 name: kong-spec-expose
 config:
-  spec_url: https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v2.0/json/petstore.json
+  spec_url: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v2.0/json/petstore.json

app/_src/deck/faqs.md

@@ -87,7 +87,7 @@ upgrading to decK 1.12 to take advantage of the new `--konnect` CLI flags.
 ### I use Cassandra as a data store for Kong, can I use decK?
 
 As of {{site.base_gateway}} 3.4, you can't use Cassandra as a data store, 
-as it is longer supported by Kong.
+as it is no longer supported by Kong.
 
 You can use decK with earlier versions of Kong backed by Cassandra.
 However, if you observe errors during a sync process, you will have to

app/_src/gateway/get-started/proxy-caching.md

@@ -109,7 +109,7 @@ will potentially be cached.
    |State| Description                                                                                                                                          |
    |---|------------------------------------------------------------------------------------------------------------------------------------------------------|
    |Miss| The request could be satisfied in cache, but an entry for the resource was not found in cache, and the request was proxied upstream.                 |
-   |Hit| The request was satisfied and served from the cache.                                                                                                 |
+   |Hit| The request was satisfied. The resource was found in cache.                                                                                            |
    |Refresh| The resource was found in cache, but could not satisfy the request, due to Cache-Control behaviors or reaching its hard-coded `cache_ttl` threshold. |
    |Bypass| The request could not be satisfied from cache based on plugin configuration.                                                                         |
 

app/_src/gateway/kong-enterprise/secrets-management/backends/azure-key-vaults.md

@@ -27,7 +27,7 @@ You need to specify the following values:
 - `vault_URI`
 - Azure Client Secret: This value can only be configured as an environment variable.
 
-You can configure these values with environment variables before starting {{site.base_gateway}}:
+You can configure these values with environment variables before starting {{site.base_gateway}}. If you are using an Instance Managed Identity Token, setting the environment variables isn't necessary.
 
 ```bash
 export KONG_VAULT_AZURE_VAULT_URI=https://my-vault.vault.azure.com
@@ -37,7 +37,9 @@ export AZURE_CLIENT_SECRET=client_secret
 ```
 
 {:.note}
-> With `Instance Managed Identity Token`, setting the environment variables isn't necessary.
+> Secrets management via Azure Vault is supported on Azure Instance (VM) and the Azure Function App.
+> It is not currently supported on Azure Container App.
+
 
 
 ### Examples

app/_src/gateway/kong-enterprise/secrets-management/backends/env.md

@@ -35,7 +35,7 @@ This allows you to reference the secrets separately:
 ```
 
 {:.note}
-> When adding an environment variable with Helm, ensure that the variable being passed has `kong-` appended to it. 
+> When adding an environment variable with Helm, ensure that the variable being passed has `kong-` prepended to it. 
 
 ## Configuration via vaults entity
 

app/_src/gateway/plugin-development/custom-entities.md

@@ -60,7 +60,7 @@ containing the initial migrations. We'll see how this is done in a minute.
 Sometimes it is necessary to introduce changes after a version of a plugin has already been
 released. A new functionality might be needed. A database table row might need changing.
 
-When this happens, *you must* create a new migrations file. You *must not* of modify the
+When this happens, *you must* create a new migrations file. You *must not* modify the
 existing migration files once they are published (you can still make them more robust and
 bulletproof if you want, e.g. always try to write the migrations reentrant).
 

app/_src/gateway/production/networking/firewall.md

@@ -51,19 +51,6 @@ Below are the recommended firewall settings:
   For example, if you want Kong to manage traffic on port `4242`, your firewall will need to allow traffic
   on said port.
 
-#### Transparent Proxying
-
-It is worth mentioning that the `transparent` listen option may be applied to [proxy_listen]
-and [stream_listen] configuration. With packet filtering such as `iptables` (Linux) or `pf` (macOS/BSDs)
-or with hardware routers/switches, you can specify pre-routing or redirection rules for TCP packets that
-allow you to mangle the original destination address and port. For example a HTTP request with a destination
-address of `10.0.0.1`, and a destination port of `80` can be redirected to `127.0.0.1` at port `8000`.
-To make this work, you need (with Linux) to add the `transparent` listen option to Kong proxy,
-`proxy_listen=8000 transparent`. This allows Kong to see the original destination for the request
-(`10.0.0.1:80`) even when Kong didn't actually listen to it directly. With this information,
-Kong can route the request correctly. The `transparent` listen option should only be used with Linux.
-macOS/BSDs allow transparent proxying without `transparent` listen option. With Linux you may also need
-to start Kong as a `root` user or set the needed capabilities for the executable.
 
 
 [proxy_listen]: /gateway/{{page.release}}/reference/configuration/#proxy_listen

app/_src/gateway/production/running-kong/secure-admin-api.md

@@ -121,8 +121,9 @@ services:
 - name: admin-api
   url: http://127.0.0.1:8001
   routes:
-    - paths:
-      - /admin-api
+  - name: admin-api
+    paths:
+    - /admin-api
   plugins:
   - name: key-auth
 

app/_src/kubernetes-ingress-controller/get-started/rate-limiting.md

@@ -13,7 +13,7 @@ Rate limiting is used to control the rate of requests sent to an upstream servic
 
 ## Create a rate-limiting KongPlugin
 
-Configuring plugins with {{ site.kic_product_name }} is different compared to how you'd do it with {{ kic.base_gateway }}. Rather than attaching a configuration directly to a service or route, you create a `KongPlugin` definition and then annotate your Kubernetes resource with the `konghq.com/plugins` annotation.
+Configuring plugins with {{ site.kic_product_name }} is different compared to how you'd do it with {{ site.base_gateway }}. Rather than attaching a configuration directly to a service or route, you create a `KongPlugin` definition and then annotate your Kubernetes resource with the `konghq.com/plugins` annotation.
 
 {:.note}
 > This tutorial uses the [Rate Limiting](/hub/kong-inc/rate-limiting/) <span class="badge free"></span> plugin. The [Rate Limiting Advanced](/hub/kong-inc/rate-limiting-advanced) <span class="badge enterprise"></span> plugin is also available. The advanced version provides additional features such as support for the sliding window algorithm and advanced Redis support for greater performance.