diff --git a/app/_data/docs_nav_gateway_3.0.x.yml b/app/_data/docs_nav_gateway_3.0.x.yml
index 4cf70647c14c..5c494c05d91e 100644
--- a/app/_data/docs_nav_gateway_3.0.x.yml
+++ b/app/_data/docs_nav_gateway_3.0.x.yml
@@ -11,60 +11,54 @@ items:
absolute_url: true
- text: Version Support Policy
url: /support-policy
- - text: Stages of Software Availability
- url: /availability-stages
+ - text: Stability
+ url: /stability
- text: Release Notes
url: /gateway/changelog
absolute_url: true
- - text: Understanding Kong
+ - text: Key Concepts
items:
- - text: Guides
+ - text: Services
+ url: /key-concepts/services
+ - text: Routes
items:
- - text: Run Kong Gateway in Minutes
- url: /understanding-kong/how-to/kong-gateway
- - text: Request Transformations
- url: /understanding-kong/how-to/request-transformations
- - text: Securing the Database with AWS Secrets Manager
- url: /understanding-kong/how-to/aws-secrets-manager
+ - text: Overview
+ url: /key-concepts/routes
- text: Configure Routes with Expressions
- url: /understanding-kong/how-to/router-atc
- - text: Key Concepts
- items:
- - text: Services
- url: /understanding-kong/key-concepts/services
- - text: Routes
- url: /understanding-kong/key-concepts/routes
- - text: Upstreams
- url: /understanding-kong/key-concepts/upstreams
- - text: Plugins
- url: /understanding-kong/key-concepts/plugins
- - text: Routing in Kong
- url: /understanding-kong/proxy
+ url: /key-concepts/routes/expressions
+ - text: Upstreams
+ url: /key-concepts/upstreams
+ - text: Plugins
+ url: /key-concepts/plugins
+ - text: Manage Kong Gateway with decK
+ url: /key-concepts/manage-kong-with-deck
+ - text: How Kong Works
+ items:
+ - text: Routing Traffic
+ url: /how-kong-works/proxy
- text: Load Balancing
- url: /understanding-kong/loadbalancing
+ url: /how-kong-works/loadbalancing
- text: Health Checks and Circuit Breakers
- url: /understanding-kong/health-checks-circuit-breakers
- - text: Manage Kong Gateway with decK
- url: /understanding-kong/manange-kong-with-deck
+ url: /how-kong-works/health-checks-circuit-breakers
- text: Kong Performance Testing
- url: /understanding-kong/kong-performance-testing
- - text: Glossary
- url: /understanding-kong/glossary
+ url: /how-kong-works/performance-testing
+ - text: Glossary
+ url: /glossary
- title: Get Started with Kong
icon: /assets/images/icons/documentation/icn-learning.svg
items:
- text: Get Kong
- url: /get-started/get-kong
+ url: /get-started/
- text: Services and Routes
url: /get-started/services-and-routes
- text: Rate Limiting
url: /get-started/rate-limiting
- text: Proxy Caching
url: /get-started/proxy-caching
- - text: Configure Key Authentication
+ - text: Key Authentication
url: /get-started/secure-services
- - text: Configure Load-Balancing
+ - text: Load-Balancing
url: /get-started/load-balancing
- text: Workspaces and Teams
url: /get-started/manage-teams
@@ -74,119 +68,133 @@ items:
- text: Deployment Topologies
items:
- text: Overview
- url: /kong-production/deployment-topologies/
+ url: /production-deployment/deployment-topologies/
- text: Hybrid Mode
items:
- text: Overview
- url: /kong-production/deployment-topologies/hybrid-mode/
+ url: /production-deployment/deployment-topologies/hybrid-mode/
- text: Deploy Kong Gateway in Hybrid mode
- url: /kong-production/deployment-topologies/hybrid-mode/hybrid-mode-setup
+ url: /production-deployment/deployment-topologies/hybrid-mode/setup
- text: DB-less Deployment
- url: /kong-production/deployment-topologies/db-less-and-declarative-config
+ url: /production-deployment/deployment-topologies/db-less-and-declarative-config
- text: Traditional
- url: /kong-production/deployment-topologies/traditional
+ url: /production-deployment/deployment-topologies/traditional
- text: Installation Options
items:
- text: Overview
- url: /kong-production/install-options/
+ url: /install/
- text: Kubernetes
- url: /kong-production/install-options/kubernetes
- - text: Install Kong Gateway with Helm
- url: /kong-production/install-options/helm-quickstart
- - text: OpenShift with Helm
- url: /kong-production/install-options/openshift
+ items:
+ - text: Install Kong Gateway with Kubernetes
+ url: /install/kubernetes/kubernetes
+ - text: Install Kong Gateway with Helm
+ url: /install/kubernetes/helm-quickstart
+ - text: OpenShift with Helm
+ url: /install/kubernetes/openshift
+ - text: Kubernetes Deployment Options
+ url: /install/kubernetes/deployment-options
- text: Docker
items:
- text: Install Kong with Docker
- url: /kong-production/install-options/docker
+ url: /install/docker
- text: Build your own Docker images
- url: /kong-production/install-options/docker/build-custom-images/
+ url: /install/docker/build-custom-images/
- text: Linux
items:
- text: Supported Distributions
- url: /kong-production/install-options/linux/os-support
+ url: /install/linux/os-support
- text: Amazon Linux
- url: /kong-production/install-options/linux/amazon-linux
+ url: /install/linux/amazon-linux
- text: Debian
- url: /kong-production/install-options/linux/debian
+ url: /install/linux/debian
- text: Red Hat
- url: /kong-production/install-options/linux/rhel
+ url: /install/linux/rhel
- text: Ubuntu
- url: /kong-production/install-options/linux/ubuntu
+ url: /install/linux/ubuntu
- text: macOS
- url: /kong-production/install-options/macos
+ url: /install/macos
- text: Running Kong
items:
- - text: Start Kong Gateway Securely
- url: /kong-production/running-kong/start-kong-securely
- text: Running Kong as a non-root user
- url: /kong-production/running-kong/kong-user
- - text: Configure Kong Gateway and SystemD
- url: /kong-production/running-kong/systemd
- - text: Kubernetes
+ url: /production-deployment/running-kong/kong-user
+ - text: Securing the Admin API
+ url: /production-deployment/running-kong/secure-admin-api
+ - text: Configure Kong Gateway and Systemd
+ url: /production-deployment/running-kong/systemd
+ - text: Access Control
items:
- - text: Kubernetes Deployment Options
- url: /kong-production/kubernetes/kubernetes-deployment-options
+ - text: Start Kong Gateway Securely
+ url: /production-deployment/access-control/start-securely
+ - text: Programatically Creating Admins
+ url: /production-deployment/access-control/register-admin-api
+ - text: Enabling RBAC
+ url: /production-deployment/access-control/enable-rbac
- text: Licenses
items:
- text: Overview
- url: /kong-production/licenses/
- - text: Access your license
- url: /kong-production/licenses/access-license
+ url: /licenses/
+ - text: Download your License
+ url: /licenses/download
- text: Deploy Enterprise License
- url: /kong-production/licenses/deploy-license
- - text: Monitor Licenses usuage
- url: /kong-production/licenses/report
+ url: /licenses/deploy
+ - text: Using the License API
+ url: /licenses/examples
+ - text: Monitor Licenses Usage
+ url: /licenses/report
- text: Networking
items:
- text: Default Ports
- url: /kong-production/networking/default-ports
- - text: DNS considerations
- url: /kong-production/networking/dns-considerations
+ url: /production-deployment/networking/default-ports
+ - text: DNS Considerations
+ url: /production-deployment/networking/dns-considerations
- text: Network and Firewall
- url: /kong-production/networking/network
+ url: /production-deployment/networking/firewall
- text: Kong Configuration File
- url: /kong-production/kong-conf
+ url: /production-deployment/kong-conf
- text: Kong Gateway Environment Variables
- url: /kong-production/environment-variables
+ url: /production-deployment/environment-variables
- text: Embedding Kong in Open Resty
- url: /kong-production/kong-openresty
- - text: Serving a website and API's from Kong
- url: /kong-production/website-api-serving
+ url: /production-deployment/kong-openresty
+ - text: Serving a Website and APIs from Kong
+ url: /production-deployment/website-api-serving
- text: Monitoring
items:
- - text: Introduction
- url: /kong-production/monitoring/
- - text: How to monitor with Prometheus
- url: /kong-production/monitoring/prometheus
- - text: How to monitor with Statsd
- url: /kong-production/monitoring/statsd
+ - text: Overview
+ url: /production-deployment/monitoring/
+ - text: How To Monitor with Prometheus
+ url: /production-deployment/monitoring/prometheus
+ - text: How To Monitor with Statsd
+ url: /production-deployment/monitoring/statsd
- text: Collect Metrics with Datadog
- url: /kong-production/monitoring/datadog
+ url: /production-deployment/monitoring/datadog
- text: Tracing
items:
- text: Overview
- url: /kong-production/tracing/
- - text: How to Write a Custom Trace Exporter
- url: /kong-production/tracing/write-custom-trace-exporter
- - text: Tracing API reference
- url: /kong-production/tracing/api
+ url: /production-deployment/tracing/
+ - text: How To Write a Custom Trace Exporter
+ url: /production-deployment/tracing/write-custom-trace-exporter
+ - text: Tracing API Reference
+ url: /production-deployment/tracing/api
- text: Resource Sizing Guidelines
- url: /kong-production/sizing-guidelines
- - text: Kong security update process
- url: /kong-production/kong-security-update-process
- - text: Blue-green deployments
- url: /kong-production/blue-green
+ url: /production-deployment/sizing-guidelines
+ - text: Security Update Process
+ url: /production-deployment/security-update-process
+ - text: Blue-Green Deployments
+ url: /production-deployment/blue-green
- text: Canary Deployments
- url: /kong-production/canary
+ url: /production-deployment/canary
+ - text: Clustering Reference
+ url: /production-deployment/clustering
- text: Logging Reference
- url: /kong-production/logging
+ url: /production-deployment/logging
- text: Upgrade Kong Gateway
- url: /kong-production/upgrade-enterprise
- - text: Upgrade Kong Gateway OSS
- url: /kong-production/upgrade-oss
- - text: Migrate from OSS to EE
- url: /kong-production/migrate-ce-to-ke
+ items:
+ - text: Upgrade Kong Enterprise
+ url: /upgrade/enterprise
+ - text: Upgrade Kong Gateway OSS
+ url: /upgrade/oss
+ - text: Migrate from OSS to EE
+ url: /upgrade/migrate-ce-to-ke
- title: Kong Enterprise
icon: /assets/images/icons/documentation/icn-enterprise-blue.svg
items:
@@ -197,15 +205,15 @@ items:
- text: Overview
url: /kong-enterprise/vitals/
- text: Metrics
- url: /kong-enterprise/vitals/vitals-metrics
+ url: /kong-enterprise/vitals/metrics
- text: Reports
- url: /kong-enterprise/vitals/vitals-reports
+ url: /kong-enterprise/vitals/reports
- text: Vitals with InfluxDB
- url: /kong-enterprise/vitals/vitals-influx-strategy
+ url: /kong-enterprise/vitals/influx-strategy
- text: Vitals with Prometheus
- url: /kong-enterprise/vitals/vitals-prometheus-strategy
+ url: /kong-enterprise/vitals/prometheus-strategy
- text: Estimate Vitals Storage in PostgreSQL
- url: /kong-enterprise/vitals/vitals-estimates
+ url: /kong-enterprise/vitals/estimates
- text: Secrets Management
items:
- text: Overview
@@ -226,6 +234,10 @@ items:
url: /kong-enterprise/secrets-management/backends/gcp-sm
- text: Hashicorp Vault
url: /kong-enterprise/secrets-management/backends/hashicorp-vault
+ - text: How-To
+ items:
+ - text: Securing the Database with AWS Secrets Manager
+ url: /kong-enterprise/secrets-management/how-to/aws-secrets-manager
- text: Reference Format
url: /kong-enterprise/secrets-management/reference-format
- text: Dynamic Plugin Ordering
@@ -234,12 +246,12 @@ items:
url: /kong-enterprise/plugin-ordering/
- text: Get Started with Dynamic Plugin Ordering
url: /kong-enterprise/plugin-ordering/get-started
- - text: Kong Dev Portal
+ - text: Dev Portal
items:
- text: Overview
url: /kong-enterprise/developer-portal/
- text: Enable the Dev Portal
- url: /kong-enterprise/developer-portal/enable-dev-portal
+ url: /kong-enterprise/developer-portal/enable
- text: Publish an API Spec to the Dev Portal
url: /kong-enterprise/developer-portal/publish-spec
- text: Structure and File Types
@@ -250,7 +262,7 @@ items:
url: /kong-enterprise/developer-portal/working-with-templates
- text: Using the Editor
url: /kong-enterprise/developer-portal/using-the-editor
- - text: Access and Approval
+ - text: Authentication and Authorization
items:
- text: Basic Auth
url: /kong-enterprise/developer-portal/authentication/basic-auth
@@ -266,7 +278,7 @@ items:
url: /kong-enterprise/developer-portal/authentication/managing-developers
- text: Developer Roles and Content Permissions
url: /kong-enterprise/developer-portal/authentication/developer-permissions
- - text: Working with Applications
+ - text: Application Registration
items:
- text: Authorization Provider Strategy
url: /kong-enterprise/developer-portal/applications/auth-provider-strategy
@@ -278,7 +290,7 @@ items:
items:
- text: External OAuth2 Support
url: /kong-enterprise/developer-portal/authentication/3rd-party-oauth
- - text: Set up Okta and Kong for external Oauth
+ - text: Set up Okta and Kong for External Oauth
url: /kong-enterprise/developer-portal/authentication/okta-config
- text: Set up Azure AD and Kong for External Authentication
url: /kong-enterprise/developer-portal/authentication/azure-oidc-config
@@ -286,8 +298,8 @@ items:
url: /kong-enterprise/developer-portal/applications/managing-applications
- text: Customize Dev Portal
items:
- - text: Easy Theme editing
- url: /kong-enterprise/developer-portal/customize/easy-theme-editing
+ - text: Theme Editing
+ url: /kong-enterprise/developer-portal/customize/theme-editing
- text: Migrating Templates Between Workspaces
url: /kong-enterprise/developer-portal/customize/migrating-templates
- text: Markdown Rendering Module
@@ -312,11 +324,17 @@ items:
url: /kong-enterprise/audit-log
- text: Keyring and Data Encryption
url: /kong-enterprise/db-encryption
+ - text: Workspaces
+ url: /kong-enterprise/workspaces
+ - text: Consumer Groups
+ url: /kong-enterprise/consumer-groups
+ - text: Event Hooks
+ url: /kong-enterprise/event-hooks
- title: Kong Manager
icon: /assets/images/icons/documentation/icn-manager-color.svg
items:
- text: Overview
- url: /kong-manager/overview
+ url: /kong-manager/
- text: Enable Kong Manager
url: /kong-manager/enable
- text: Get Started with Kong Manager
@@ -334,7 +352,7 @@ items:
- text: Authentication and Authorization
items:
- text: Overview
- url: /kong-manager/auth/overview
+ url: /kong-manager/auth/
- text: Create a Super Admin
url: /kong-manager/auth/super-admin
- text: Workspaces and Teams
@@ -381,23 +399,23 @@ items:
items:
- text: Overview
url: /plugin-development/
- - text: File structure
+ - text: File Structure
url: /plugin-development/file-structure
- - text: Implementing custom logic
+ - text: Implementing Custom Logic
url: /plugin-development/custom-logic
- - text: Plugin configuration
- url: /plugin-development/plugin-configuration
- - text: Accessing the datastore
+ - text: Plugin Configuration
+ url: /plugin-development/configuration
+ - text: Accessing the Data Store
url: /plugin-development/access-the-datastore
- - text: Storing custom entities
+ - text: Storing Custom Entities
url: /plugin-development/custom-entities
- - text: Caching custom entities
+ - text: Caching Custom Entities
url: /plugin-development/entities-cache
- text: Extending the Admin API
url: /plugin-development/admin-api
- - text: Writing tests
+ - text: Writing Tests
url: /plugin-development/tests
- - text: (un)Installing your plugin
+ - text: (un)Installing your Plugin
url: /plugin-development/distribution
- text: Plugin Development Kit
items:
@@ -431,22 +449,20 @@ items:
url: /plugin-development/pdk/kong.service.request
- text: kong.service.response
url: /plugin-development/pdk/kong.service.response
-
- text: kong.table
url: /plugin-development/pdk/kong.table
-
- text: kong.vault
url: /plugin-development/pdk/kong.vault
- text: Plugins in Other Languages
items:
- text: Go
- url: /plugin-development/other/go
+ url: /plugin-development/pluginserver/go
- text: Javascript
- url: /plugin-development/other/javascript
+ url: /plugin-development/pluginserver/javascript
- text: Python
- url: /plugin-development/other/python
+ url: /plugin-development/pluginserver/python
- text: Running Plugins in Containers
- url: /plugin-development/other/plugins-kubernetes
+ url: /plugin-development/pluginserver/plugins-kubernetes
- title: Kong Plugins
icon: /assets/images/icons/documentation/icn-api-plugins-color.svg
items:
@@ -454,45 +470,49 @@ items:
url: /kong-plugins/
- text: Authentication
items:
- - text: Authenticate with Plugins
+ - text: Open ID Connect Plugin
items:
- - text: Open ID Connect Plugin
- items:
- - text: Overview
- url: /kong-plugins/authentication/oidc/oidc-use-case
- - text: OpenID Connect with Curity
- url: /kong-plugins/authentication/oidc/oidc-curity
- - text: OpenID Connect with Azure AD
- url: /kong-plugins/authentication/oidc/oidc-azuread
- - text: OpenID Connect with Google
- url: /kong-plugins/authentication/oidc/oidc-google
- - text: OpenID Connect with Okta
- url: /kong-plugins/authentication/oidc/oidc-okta
- - text: OpenID Connect with Auth0
- url: /kong-plugins/authentication/oidc/oidc-auth0
- - text: OpenID Connect with Cognito
- url: /kong-plugins/authentication/oidc/oidc-cognito
- - text: Authentication Reference
- url: /kong-plugins/authentication/auth-reference
- - text: Rate-limiting
+ - text: Overview
+ url: /kong-plugins/authentication/oidc/
+ - text: OpenID Connect with Curity
+ url: /kong-plugins/authentication/oidc/curity
+ - text: OpenID Connect with Azure AD
+ url: /kong-plugins/authentication/oidc/azure-ad
+ - text: OpenID Connect with Google
+ url: /kong-plugins/authentication/oidc/google
+ - text: OpenID Connect with Okta
+ url: /kong-plugins/authentication/oidc/okta
+ - text: OpenID Connect with Auth0
+ url: /kong-plugins/authentication/oidc/auth0
+ - text: OpenID Connect with Cognito
+ url: /kong-plugins/authentication/oidc/cognito
+ - text: Authentication Reference
+ url: /kong-plugins/authentication/reference
+ - text: Rate Limiting Plugin
+ url: /kong-plugins/rate-limiting/algorithms/rate-limiting
+ #items:
+ #- text: Overview
+ #url: /kong-plugins/rate-limiting/ commenting these lines out for 3.0
+ #url: /kong-plugins/rate-limiting/algorithms/rate-limiting
+ #- text: Algorithms
+ # items:
+ # - text: Configuring sliding-window
+ # url: /kong-plugins/rate-limiting/algorithms/rate-limiting
+ #- text: Configuring Fixed bucket
+ # url: /kong-plugins/rate-limiting/algorithms/fixed-bucket
+ - text: Request Transformer
items:
- - text: Overview
- url: /kong-plugins/rate-limiting/
- - text: Algorithms
- items:
- - text: Configuring sliding-window
- url: /kong-plugins/rate-limiting/algorithms/rate-limiting
- - text: Configuring Fixed bucket
- url: /kong-plugins/rate-limiting/algorithms/fixed-bucket
+ - text: Add a Body Value
+ url: /kong-plugins/request-transformer/add-body-value
- text: GraphQL
- url: /kong-plugins/graphql-quickstart
+ url: /kong-plugins/graphql
- text: gRPC
url: /kong-plugins/grpc
- title: Admin API
icon: /assets/images/icons/documentation/icn-admin-api-color.svg
items:
- - text: Introduction to the Kong Admin API
+ - text: Overview
url: /admin-api/
- text: Information Routes
url: /admin-api/#information-routes
@@ -500,84 +520,52 @@ items:
url: /admin-api/#health-routes
- text: Tags
url: /admin-api/#tags
- - text: Service Object
+ - text: Services
url: /admin-api/#service-object
- - text: Route Object
+ - text: Routes
url: /admin-api/#route-object
- - text: Consumer Object
+ - text: Consumers
url: /admin-api/#consumer-object
- - text: Plugin Object
+ - text: Plugins
url: /admin-api/#plugin-object
- - text: Certificate Object
+ - text: Certificates
url: /admin-api/#certificate-object
- - text: CA Certificate Object
+ - text: CA Certificates
url: /admin-api/#ca-certificate-object
- - text: SNI Object
+ - text: SNIs
url: /admin-api/#sni-object
- - text: Upstream Object
+ - text: Upstreams
url: /admin-api/#upstream-object
- - text: Target Object
+ - text: Targets
url: /admin-api/#target-object
- - text: Vaults Beta
- url: /admin-api/#vaults-beta-entity
+ - text: Vaults
+ url: /admin-api/#vaults-entity
- text: Licenses
url: /admin-api/licenses/reference
- items:
- - text: Licenses Reference
- url: /admin-api/licenses/reference
- - text: Licenses Examples
- url: /admin-api/licenses/examples
- text: Workspaces
url: /admin-api/workspaces/reference
- items:
- - text: Workspaces Reference
- url: /admin-api/workspaces/reference
- - text: Workspace Examples
- url: /admin-api/workspaces/examples
- text: RBAC
url: /admin-api/rbac/reference
- items:
- - text: RBAC Reference
- url: /admin-api/rbac/reference
- - text: RBAC Examples
- url: /admin-api/rbac/examples
- text: Admins
url: /admin-api/admins/reference
- items:
- - text: Admins API Reference
- url: /admin-api/admins/reference
- - text: Admins Examples
- url: /admin-api/admins/examples
- text: Developers
url: /admin-api/developers/reference
- text: Consumer Groups
url: /admin-api/consumer-groups/reference
- items:
- - text: Consumer Groups API Reference
- url: /admin-api/consumer-groups/reference
- - text: Consumer Groups Examples
- url: /admin-api/consumer-groups/examples
- text: Event Hooks
url: /admin-api/event-hooks/reference
- items:
- - text: Event Hooks Reference
- url: /admin-api/event-hooks/reference
- - text: Event Hooks Examples
- url: /admin-api/event-hooks/examples
- - text: Securing the Admin API
- url: /admin-api/secure-admin-api
+ - text: Keyring and Data Encryption
+ url: /admin-api/db-encryption
- title: Reference
icon: /assets/images/icons/documentation/icn-references-color.svg
items:
- - text: Configuration
+ - text: kong.conf
url: /reference/configuration
- - text: Kong Gateway Nginx Directives
+ - text: Injecting Nginx Directives
url: /reference/nginx-directives
- - text: CLI Reference
+ - text: CLI
url: /reference/cli
- - text: Rate Limiting Library
- url: /reference/rate-limit
- - text: Performance Testing Framework Reference
+ - text: Performance Testing Framework
url: /reference/performance-testing-framework
- text: Router Operators
url: /reference/router-operators
diff --git a/app/_plugins/filters/titleize_filter.rb b/app/_plugins/filters/titleize_filter.rb
index 93adbd621ccb..024d027682bc 100644
--- a/app/_plugins/filters/titleize_filter.rb
+++ b/app/_plugins/filters/titleize_filter.rb
@@ -5,6 +5,8 @@
ActiveSupport::Inflector.inflections do |inflect|
inflect.acronym 'API'
inflect.acronym 'mTLS'
+ inflect.acronym 'PDK'
+ inflect.acronym 'OIDC'
end
module Jekyll
diff --git a/app/_plugins/generators/alias_generator.rb b/app/_plugins/generators/alias_generator.rb
index c51765447b3f..f46b7543a103 100644
--- a/app/_plugins/generators/alias_generator.rb
+++ b/app/_plugins/generators/alias_generator.rb
@@ -31,7 +31,7 @@ module Jekyll
class AliasGenerator < Generator
priority :lowest
- def generate(site) # rubocop:disable Metrics/AbcSize
+ def generate(site) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
@redirects = []
# Generate redirect_to from frontmatter redirects
@@ -54,9 +54,9 @@ def generate(site) # rubocop:disable Metrics/AbcSize
end
def generate_moved_aliases(moved_pages)
- moved_pages.each do |k,v|
- k = k.sub("/VERSION/", "/latest/")
- v = v.sub("/VERSION/", "/latest/")
+ moved_pages.each do |k, v|
+ k = k.sub('/VERSION/', '/latest/')
+ v = v.sub('/VERSION/', '/latest/')
@redirects.push("#{k}\t#{v}")
end
end
diff --git a/app/_redirects b/app/_redirects
index d78279d600a4..a6e1c9e66f7d 100644
--- a/app/_redirects
+++ b/app/_redirects
@@ -700,3 +700,16 @@
/introduction /
/enterprise/ /gateway/
/gateway-oss/ /gateway/
+
+
+
+# 3.0
+
+/gateway/2.8.x/install-and-run/ /gateway/latest/install-and-run/os-support
+/gateway/2.8.x/install-and-run/centos/ /gateway/latest/install-and-run/os-support
+/gateway/2.8.x/get-started/quickstart/ /gateway/latest/get-started/
+/gateway/2.8.x/get-started/quickstart/configuring-a-service/ /gateway/latest/get-started/services-and-routes/
+/gateway/2.8.x/get-started/quickstart/configuring-a-grpc-service/ /gateway/latest/get-started/ratelimiting/
+/gateway/2.8.x/get-started/quickstart/enabling-plugins/ /gateway/latest/key-concepts/plugins/
+/gateway/2.8.x/get-started/quickstart/adding-consumers/ /gateway/latest/get-started/key-authentication
+/gateway/2.8.x/admin-api/rbac/examples/ /gateway/latest/admin-api/rbac/reference/
\ No newline at end of file
diff --git a/app/moved_urls.yml b/app/moved_urls.yml
index b789bd5e6be8..93c55615e0ad 100644
--- a/app/moved_urls.yml
+++ b/app/moved_urls.yml
@@ -1,5 +1,185 @@
---
/gateway-oss/VERSION/configuration/: "/gateway/VERSION/reference/configuration/"
-/gateway/VERSION/install-and-run/rhel/: "/gateway/VERSION/kong-production/install-options/linux/rhel/"
-/gateway/VERSION/get-started/get-kong-with-docker/: "/gateway/VERSION/get-started/get-kong"
/gateway/VERSION/get-started/configure-services-and-routes/: "/gateway/VERSION/get-started/services-and-routes/"
+
+
+/gateway/VERSION/install-and-run/kubernetes/: "/gateway/VERSION/install/kubernetes/kubernetes/"
+/gateway/VERSION/install-and-run/helm/: "/gateway/VERSION/install/kubernetes/helm/"
+/gateway/VERSION/install-and-run/helm/: "/gateway/VERSION/install/kubernetes/openshift/"
+/gateway/VERSION/install-and-run/docker/: "/gateway/VERSION/install/docker/"
+/gateway/VERSION/install-and-run/amazon-linux/: "/gateway/VERSION/install/linux/amazon-linux/"
+/gateway/VERSION/install-and-run/macos/: "/gateway/VERSION/install/macos/"
+/gateway/VERSION/install-and-run/debian/: "/gateway/VERSION/install/linux/debian"
+/gateway/VERSION/install-and-run/rhel/: "/gateway/VERSION/install/linux/debian/rhel"
+/gateway/VERSION/install-and-run/ubuntu/: "/gateway/VERSION/install/linux/ubuntu/"
+/gateway/VERSION/install-and-run/migrate-ce-to-ke/: "/gateway/VERSION/upgrade/migrate-ce-to-ke/"
+/gateway/VERSION/install-and-run/upgrade-enterprise/: "/gateway/VERSION/upgrade/enterprise/"
+/gateway/VERSION/install-and-run/upgrade-oss/: "/gateway/VERSION/upgrade/oss/"
+/gateway/VERSION/get-started/comprehensive/prepare/: "/gateway/VERSION/get-started/"
+/gateway/VERSION/get-started/comprehensive/expose-services/: "/gateway/VERSION/get-started/services-and-routes/"
+/gateway/VERSION/get-started/comprehensive/protect-services/: "/gateway/VERSION/get-started/ratelimiting/"
+/gateway/VERSION/get-started/comprehensive/improve-performance/: "/gateway/VERSION/get-started/proxy-caching/"
+/gateway/VERSION/get-started/comprehensive/secure-services/: "/gateway/VERSION/get-started/secure-services/"
+/gateway/VERSION/get-started/comprehensive/load-balancing/: "/gateway/VERSION/get-started/load-balancing/"
+/gateway/VERSION/get-started/comprehensive/manage-teams/: "/gateway/VERSION/get-started/manage-teams/"
+/gateway/VERSION/get-started/comprehensive/dev-portal/: "/gateway/VERSION/kong-enterprise/developer-portal/publish-spec/"
+/gateway/VERSION/plan-and-deploy/kong-user/: "/gateway/VERSION/production-deployment/running-kong/kong-user/"
+/gateway/VERSION/plan-and-deploy/sizing-guidelines/: "/gateway/VERSION/production-deployment/sizing-guidelines/"
+/gateway/VERSION/plan-and-deploy/hybrid-mode/: "/gateway/VERSION/production-deployment/deployment-topologies/hybrid-mode/"
+/gateway/VERSION/plan-and-deploy/hybrid-mode/hybrid-mode-setup/: "/gateway/VERSION/production-deployment/deployment-topologies/hybrid-mode/setup/"
+/gateway/VERSION/plan-and-deploy/kubernetes-deployment-options/: "/gateway/VERSION/install/kubernetes/deployment-options/"
+/gateway/VERSION/plan-and-deploy/systemd/: "/gateway/VERSION/production-deployment/running-kong/systemd/"
+/gateway/VERSION/plan-and-deploy/performance-testing-framework/: "/gateway/VERSION/how-kong-works/performance-testing/"
+/gateway/VERSION/plan-and-deploy/dns-considerations/: "/gateway/VERSION/production-deployment/networking/dns-considerations/"
+/gateway/VERSION/plan-and-deploy/default-ports/: "/gateway/VERSION/production-deployment/networking/default-ports/"
+/gateway/VERSION/plan-and-deploy/licenses/: "/gateway/VERSION/licenses/"
+/gateway/VERSION/plan-and-deploy/licenses/access-license/: "/gateway/VERSION/licenses/download/"
+/gateway/VERSION/plan-and-deploy/licenses/deploy-license/: "/gateway/VERSION/licenses/deploy/"
+/gateway/VERSION/plan-and-deploy/licenses/report/: "/gateway/VERSION/licenses/report/"
+/gateway/VERSION/plan-and-deploy/security/start-kong-securely/: "/gateway/VERSION/production-deployment/access-control/start-securely/"
+/gateway/VERSION/plan-and-deploy/security/db-encryption/: "/gateway/VERSION/kong-enterprise/db-encryption/"
+/gateway/VERSION/plan-and-deploy/security/kong-security-update-process/: "/gateway/VERSION/production-deployment/security-update-process/"
+/gateway/VERSION/plan-and-deploy/security/secrets-management/: "/gateway/VERSION/kong-enterprise/secrets-management/"
+/gateway/VERSION/plan-and-deploy/security/secrets-management/getting-started/: "/gateway/VERSION/kong-enterprise/secrets-management/getting-started/"
+/gateway/VERSION/plan-and-deploy/security/secrets-management/advanced-usage/: "/gateway/VERSION/kong-enterprise/secrets-management/advanced-usage/"
+/gateway/VERSION/plan-and-deploy/security/secrets-management/backends/: "/gateway/VERSION/kong-enterprise/secrets-management/backends/"
+/gateway/VERSION/plan-and-deploy/security/secrets-management/backends/env/: "/gateway/VERSION/kong-enterprise/secrets-management/backends/env/"
+/gateway/VERSION/plan-and-deploy/security/secrets-management/backends/aws-sm/: "/gateway/VERSION/kong-enterprise/secrets-management/backends/aws-sm/"
+/gateway/VERSION/plan-and-deploy/security/secrets-management/backends/gcp-sm/: "/gateway/VERSION/kong-enterprise/secrets-management/backends/gcp-sm/"
+/gateway/VERSION/plan-and-deploy/security/secrets-management/backends/hashicorp-vault/: "/gateway/VERSION/kong-enterprise/secrets-management/backends/hashicorp-vault/"
+/gateway/VERSION/plan-and-deploy/security/secrets-management/reference-format/: "/gateway/VERSION/kong-enterprise/secrets-management/reference-format/"
+/gateway/VERSION/configure/auth/: "/gateway/VERSION/kong-plugins/authentication/reference/"
+/gateway/VERSION/configure/auth/oidc-use-case/: "/gateway/VERSION/kong-plugins/authentication/oidc/"
+/gateway/VERSION/configure/auth/oidc-curity/: "/gateway/VERSION/kong-plugins/authentication/oidc/curity/"
+/gateway/VERSION/configure/auth/oidc-azuread/: "/gateway/VERSION/kong-plugins/authentication/oidc/azure-ad/"
+/gateway/VERSION/configure/auth/oidc-google/: "/gateway/VERSION/kong-plugins/authentication/oidc/google/"
+/gateway/VERSION/configure/auth/oidc-okta/: "/gateway/VERSION/kong-plugins/authentication/oidc/okta/"
+/gateway/VERSION/configure/auth/oidc-auth0/: "/gateway/VERSION/kong-plugins/authentication/oidc/auth0/"
+/gateway/VERSION/configure/auth/oidc-cognito/: "/gateway/VERSION/kong-plugins/authentication/oidc/cognito/"
+/gateway/VERSION/configure/auth/allowing-multiple-authentication-methods/: "/gateway/VERSION/kong-plugins/authentication/allowing-multiple-authentication-methods/"
+/gateway/VERSION/configure/auth/kong-manager/: "/gateway/VERSION/kong-manager/auth/"
+/gateway/VERSION/configure/auth/kong-manager/super-admin/: "/gateway/VERSION/kong-manager/auth/super-admin/"
+/gateway/VERSION/configure/auth/kong-manager/networking/: "/gateway/VERSION/kong-manager/networking/"
+/gateway/VERSION/configure/auth/kong-manager/email/: "/gateway/VERSION/kong-manager/configuring-to-send-email/"
+/gateway/VERSION/configure/auth/kong-manager/reset-password/: "/gateway/VERSION/kong-manager/auth/reset-password/"
+/gateway/VERSION/configure/auth/kong-manager/workspaces/: "/gateway/VERSION/kong-manager/workspaces/"
+/gateway/VERSION/configure/auth/kong-manager/basic/: "/gateway/VERSION/kong-manager/auth/basic/"
+/gateway/VERSION/configure/auth/kong-manager/ldap/: "/gateway/VERSION/kong-manager/auth/ldap/configure/"
+/gateway/VERSION/configure/auth/kong-manager/oidc-mapping/: "/gateway/VERSION/kong-manager/auth/oidc/mapping/"
+/gateway/VERSION/configure/auth/kong-manager/sessions/: "/gateway/VERSION/kong-manager/auth/sessions/"
+/gateway/VERSION/configure/auth/kong-manager/super-admin/: "/gateway/VERSION/kong-manager/auth/super-admin/"
+/gateway/VERSION/configure/auth/kong-manager/networking/: "/gateway/VERSION/kong-manager/networking/"
+/gateway/VERSION/configure/auth/rbac/: "/gateway/VERSION/kong-manager/auth/rbac/"
+/gateway/VERSION/configure/auth/rbac/add-role/: "/gateway/VERSION/kong-manager/auth/rbac/add-role/"
+/gateway/VERSION/configure/auth/rbac/add-user/: "/gateway/VERSION/kong-manager/auth/rbac/add-user/"
+/gateway/VERSION/configure/auth/rbac/add-admin/: "/gateway/VERSION/kong-manager/auth/rbac/add-admin/"
+/gateway/VERSION/configure/auth/service-directory-mapping/: "/gateway/VERSION/kong-manager/auth/ldap/service-directory-mapping/"
+/gateway/VERSION/configure/grpc/: "/gateway/VERSION/kong-plugins/grpc/"
+/gateway/VERSION/configure/graphql-quickstart/: "/gateway/VERSION/kong-plugins/graphql/"
+/gateway/VERSION/configure/logging/: "/gateway/VERSION/production-deployment/logging/"
+/gateway/VERSION/configure/network/: "/gateway/VERSION/production-deployment/networking/firewall/"
+/gateway/VERSION/developer-portal/: "/gateway/VERSION/kong-enterprise/developer-portal/"
+/gateway/VERSION/developer-portal/enable-dev-portal/: "/gateway/VERSION/kong-enterprise/developer-portal/enable/"
+/gateway/VERSION/developer-portal/structure-and-file-types/: "/gateway/VERSION/kong-enterprise/developer-portal/structure-and-file-types/"
+/gateway/VERSION/developer-portal/working-with-templates/: "/gateway/VERSION/kong-enterprise/developer-portal/working-with-templates/"
+/gateway/VERSION/developer-portal/using-the-editor/: "/gateway/VERSION/kong-enterprise/developer-portal/using-the-editor/"
+/gateway/VERSION/developer-portal/configuration/authentication/basic-auth/: "/gateway/VERSION/kong-enterprise/developer-portal/authentication/basic-auth/"
+/gateway/VERSION/developer-portal/configuration/authentication/key-auth/: "/gateway/VERSION/kong-enterprise/developer-portal/authentication/key-auth/"
+/gateway/VERSION/developer-portal/configuration/authentication/oidc/: "/gateway/VERSION/kong-enterprise/developer-portal/authentication/oidc/"
+/gateway/VERSION/developer-portal/configuration/authentication/sessions/: "/gateway/VERSION/kong-enterprise/developer-portal/authentication/sessions/"
+/gateway/VERSION/developer-portal/configuration/authentication/adding-registration-fields/: "/gateway/VERSION/kong-enterprise/developer-portal/authentication/adding-registration-fields/"
+/gateway/VERSION/developer-portal/configuration/smtp/: "/gateway/VERSION/kong-enterprise/developer-portal/smtp/"
+/gateway/VERSION/developer-portal/configuration/workspaces/: "/gateway/VERSION/kong-enterprise/developer-portal/workspaces/"
+/gateway/VERSION/developer-portal/administration/managing-developers/: "/gateway/VERSION/kong-enterprise/developer-portal/authentication/managing-developers/"
+/gateway/VERSION/developer-portal/administration/developer-permissions/: "/gateway/VERSION/kong-enterprise/developer-portal/authentication/developer-permissions/"
+/gateway/VERSION/developer-portal/administration/application-registration/auth-provider-strategy/: "/gateway/VERSION/kong-enterprise/developer-portal/applications/auth-provider-strategy/"
+/gateway/VERSION/developer-portal/administration/application-registration/enable-application-registration/: "/gateway/VERSION/kong-enterprise/developer-portal/applications/enable-application-registration/"
+/gateway/VERSION/developer-portal/administration/application-registration/enable-key-auth-plugin/: "/gateway/VERSION/kong-enterprise/developer-portal/applications/enable-key-auth-plugin/"
+/gateway/VERSION/developer-portal/administration/application-registration/3rd-party-oauth/: "/gateway/VERSION/kong-enterprise/developer-portal/authentication/3rd-party-oauth/"
+/gateway/VERSION/developer-portal/administration/application-registration/okta-config/: "/gateway/VERSION/kong-enterprise/developer-portal/authentication/okta-config/"
+/gateway/VERSION/developer-portal/administration/application-registration/azure-oidc-config/: "/gateway/VERSION/kong-enterprise/developer-portal/authentication/azure-oidc-config/"
+/gateway/VERSION/developer-portal/administration/application-registration/managing-applications/: "/gateway/VERSION/kong-enterprise/developer-portal/applications/managing-applications/"
+/gateway/VERSION/developer-portal/theme-customization/easy-theme-editing/: "/gateway/VERSION/kong-enterprise/developer-portal/customize/theme-editing/"
+/gateway/VERSION/developer-portal/theme-customization/migrating-templates/: "/gateway/VERSION/kong-enterprise/developer-portal/customize/migrating-templates/"
+/gateway/VERSION/developer-portal/theme-customization/markdown-extended/: "/gateway/VERSION/kong-enterprise/developer-portal/customize/markdown-extended/"
+/gateway/VERSION/developer-portal/theme-customization/emails/: "/gateway/VERSION/kong-enterprise/developer-portal/customize/emails/"
+/gateway/VERSION/developer-portal/theme-customization/adding-javascript-assets/: "/gateway/VERSION/kong-enterprise/developer-portal/customize/adding-javascript-assets/"
+/gateway/VERSION/developer-portal/theme-customization/single-page-app/: "/gateway/VERSION/kong-enterprise/developer-portal/customize/single-page-app/"
+/gateway/VERSION/developer-portal/theme-customization/alternate-openapi-renderer/: "/gateway/VERSION/kong-enterprise/developer-portal/customize/alternate-openapi-renderer/"
+/gateway/VERSION/developer-portal/helpers/cli/: "/gateway/VERSION/kong-enterprise/developer-portal/cli/"
+/gateway/VERSION/vitals/: "/gateway/VERSION/kong-enterprise/vitals/"
+/gateway/VERSION/vitals/vitals-metrics/: "/gateway/VERSION/kong-enterprise/vitals/metrics/"
+/gateway/VERSION/vitals/vitals-reports/: "/gateway/VERSION/kong-enterprise/vitals/reports/"
+/gateway/VERSION/vitals/vitals-influx-strategy/: "/gateway/VERSION/kong-enterprise/vitals/influx-strategy/"
+/gateway/VERSION/vitals/vitals-prometheus-strategy/: "/gateway/VERSION/kong-enterprise/vitals/prometheus-strategy/"
+/gateway/VERSION/vitals/vitals-estimates/: "/gateway/VERSION/kong-enterprise/vitals/estimates/"
+/gateway/VERSION/admin-api/licenses/examples/: "/gateway/VERSION/licenses/examples/"
+/gateway/VERSION/admin-api/workspaces/examples/: "/gateway/latest/kong-enterprise/workspaces/"
+/gateway/VERSION/admin-api/rbac/examples/: "/gateway/VERSION/admin-api/admins/examples"
+/gateway/VERSION/admin-api/admins/examples/: "/gateway/VERSION/production-deployment/access-control/register-admin-api/"
+/gateway/VERSION/admin-api/consumer-groups/examples/: "/gateway/latest/kong-enterprise/consumer-groups/"
+/gateway/VERSION/admin-api/event-hooks/examples/: "/gateway/latest/kong-enterprise/event-hooks/"
+/gateway/VERSION/admin-api/audit-log/: "/gateway/latest/kong-enterprise/audit-log/"
+/gateway/VERSION/admin-api/db-encryption/: "/gateway/latest/kong-enterprise/db-encryption/"
+/gateway/VERSION/admin-api/secure-admin-api/: "/gateway/latest/production-deployment/running-kong/secure-admin-api/"
+/gateway/VERSION/reference/db-less-and-declarative-config/: "/gateway/latest/production-deployment/deployment-topologies/db-less-and-declarative-config/"
+/gateway/VERSION/reference/configuration/: "/gateway/latest/reference/configuration/"
+/gateway/VERSION/reference/cli/: "/gateway/latest/reference/cli/"
+/gateway/VERSION/reference/loadbalancing/: "/gateway/latest/how-kong-works/loadbalancing/"
+/gateway/VERSION/reference/proxy/: "/gateway/latest/how-kong-works/proxy/"
+/gateway/VERSION/reference/rate-limiting/: "/gateway/latest/kong-plugins/rate-limiting/algorithms/rate-limiting/"
+/gateway/VERSION/reference/health-checks-circuit-breakers/: "/gateway/latest/how-kong-works/health-checks-circuit-breakers/"
+/gateway/VERSION/reference/clustering/: "/gateway/latest/production-deployment/clustering/"
+/gateway/VERSION/pdk/: "/gateway/latest/plugin-development/pdk/"
+/gateway/VERSION/pdk/kong.client/: "/gateway/latest/plugin-development/pdk/kong.client/"
+/gateway/VERSION/pdk/kong.client.tls/: "/gateway/latest/plugin-development/pdk/kong.client.tls/"
+/gateway/VERSION/pdk/kong.cluster/: "/gateway/latest/plugin-development/pdk/kong.cluster/"
+/gateway/VERSION/pdk/kong.ctx/: "/gateway/latest/plugin-development/pdk/kong.ctx/"
+/gateway/VERSION/pdk/kong.ip/: "/gateway/latest/plugin-development/pdk/kong.ip/"
+/gateway/VERSION/pdk/kong.log/: "/gateway/latest/plugin-development/pdk/kong.log/"
+/gateway/VERSION/pdk/kong.nginx/: "/gateway/latest/plugin-development/pdk/kong.nginx/"
+/gateway/VERSION/pdk/kong.node/: "/gateway/latest/plugin-development/pdk/kong.node/"
+/gateway/VERSION/pdk/kong.request/: "/gateway/latest/plugin-development/pdk/kong.request/"
+/gateway/VERSION/pdk/kong.response/: "/gateway/latest/plugin-development/pdk/kong.response/"
+/gateway/VERSION/pdk/kong.router/: "/gateway/latest/plugin-development/pdk/kong.router/"
+/gateway/VERSION/pdk/kong.service/: "/gateway/latest/plugin-development/pdk/kong.service/"
+/gateway/VERSION/pdk/kong.service.request/: "/gateway/latest/plugin-development/pdk/kong.service.request/"
+/gateway/VERSION/pdk/kong.service.response/: "/gateway/latest/plugin-development/pdk/kong.service.response/"
+/gateway/VERSION/pdk/kong.table/: "/gateway/latest/plugin-development/pdk/kong.table/"
+/gateway/VERSION/pdk/kong.vault/: "/gateway/latest/plugin-development/pdk/kong.vault/"
+/gateway/VERSION/plugin-development/: "/gateway/latest/plugin-development/"
+/gateway/VERSION/plugin-development/file-structure/: "/gateway/latest/plugin-development/file-structure/"
+/gateway/VERSION/plugin-development/custom-logic/: "/gateway/latest/plugin-development/custom-logic/"
+/gateway/VERSION/plugin-development/plugin-configuration/: "/gateway/latest/plugin-development/configuration/"
+/gateway/VERSION/plugin-development/access-the-datastore/: "/gateway/latest/plugin-development/access-the-datastore/"
+/gateway/VERSION/plugin-development/custom-entities/: "/gateway/latest/plugin-development/custom-entities/"
+/gateway/VERSION/plugin-development/entities-cache/: "/gateway/latest/plugin-development/entities-cache/"
+/gateway/VERSION/plugin-development/admin-api/: "/gateway/latest/plugin-development/admin-api/"
+/gateway/VERSION/plugin-development/tests/: "/gateway/latest/plugin-development/tests/"
+/gateway/VERSION/plugin-development/distribution/: "/gateway/latest/plugin-development/distribution/"
+/gateway/VERSION/reference/external-plugins/: "/gateway/latest/plugin-development/pluginserver/go/"
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# # EMpty Page
+# http://localhost:3000/gateway/latest/kong-plugins/rate-limiting/
+
diff --git a/src/gateway/admin-api/db-encryption.md b/src/gateway/admin-api/db-encryption.md
new file mode 100644
index 000000000000..bff20650be0d
--- /dev/null
+++ b/src/gateway/admin-api/db-encryption.md
@@ -0,0 +1,203 @@
+---
+title: Keyring and Data Encryption Reference
+badge: enterprise
+---
+
+## View Keyring
+**Endpoint**
+
+/keyring
+
+**Response**
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "active": "RfsDJ2Ol",
+ "ids": [
+ "RfsDJ2Ol",
+ "xSD219lH"
+ ]
+}
+
+```
+
+## View Active Key
+**Endpoint**
+
+/keyring/active
+
+**Response**
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "id": "RfsDJ2Ol"
+}
+
+```
+
+## Export Keyring
+
+*This endpoint is only available with the `cluster` keyring strategy.*
+
+*The endpoint requires that the `keyring_public_key` and `keyring_private_key` Kong configuration values are defined.*
+
+**Endpoint**
+
+/keyring/export
+
+**Response**
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "data": "..."
+}
+```
+
+## Import Exported Keyring
+
+*This endpoint is only available with the `cluster` keyring strategy.*
+
+*The endpoint requires that the `keyring_public_key` and `keyring_private_key` Kong configuration values are defined.*
+
+**Endpoint**
+
+/keyring/import
+
+**Request Body**
+
+| Attribute | Description |
+| --------- | ----------- |
+| `data` | Base64-encoded keyring export material. |
+
+
+**Response**
+
+```
+HTTP 201 Created
+```
+
+## Import Key
+
+*This endpoint is only available with the `cluster` keyring strategy.*
+
+*The endpoint requires that the `keyring_public_key` and `keyring_private_key` Kong configuration values are defined.*
+
+**Endpoint**
+
+/keyring/import/raw
+
+**Request Body**
+
+| Attribute | Description |
+| --------- | ----------- |
+| `id` | 8-byte key identifier. |
+| `data` | Base64-encoded keyring export material. |
+
+
+**Response**
+
+```
+HTTP 201 Created
+```
+
+## Recover Keyring from Database
+
+*This endpoint is only available with the `cluster` keyring strategy.*
+
+*The endpoint requires that the `keyring_recovery_public_key` Kong configuration value is defined.*
+
+**Endpoint**
+
+/keyring/recover
+
+**Request Body**
+
+| Attribute | Description |
+| --------- | ----------- |
+| `recovery_private_key` | The content of the private key. |
+
+**Response**
+
+```
+HTTP 200 OK
+```
+
+```json
+{
+ "message": "successfully recovered 1 keys",
+ "recovered": [
+ "RfsDJ2Ol"
+ ],
+ "not_recovered": [
+ "xSD219lH"
+ ]
+}
+```
+
+## Generate New Key
+
+*This endpoint is only available with the `cluster` keyring strategy.*
+
+**Endpoint**
+
+/keyring/generate
+
+**Response**
+
+```
+HTTP 201 Created
+```
+
+```json
+{
+ "id": "500pIquV",
+ "key": "3I23Ben5m7qKcCA/PK7rnsNeD3kI4IPtA6ki7YjAgKA="
+}
+```
+
+## Remove Key from Keyring
+
+*This endpoint is only available with the `cluster` keyring strategy.*
+
+**Endpoint**
+
+/keyring/remove
+
+**Request Body**
+
+| Attribute | Description |
+| --------- | ----------- |
+| `key` | 8-byte key identifier. |
+
+
+**Response**
+
+```
+HTTP 204 No Content
+```
+
+## Sync Keyring with Vault Endpoint
+
+*This endpoint is only available with the `vault` keyring strategy.*
+
+**Endpoint**
+
+/keyring/vault/sync
+
+**Response**
+
+```
+HTTP 204 No Content
+```
diff --git a/src/gateway/admin-api/index.md b/src/gateway/admin-api/index.md
index 0c488ab5ae6f..eebffd0cf64f 100644
--- a/src/gateway/admin-api/index.md
+++ b/src/gateway/admin-api/index.md
@@ -4186,7 +4186,7 @@ HTTP 200 OK
---
-## Vaults Beta Entity
+## Vaults Entity
Vault entities are used to configure different Vault connectors. Examples of
Vaults are Environment Variables, Hashicorp Vault and AWS Secrets Manager.
diff --git a/src/gateway/get-started/get-kong.md b/src/gateway/get-started/index.md
similarity index 100%
rename from src/gateway/get-started/get-kong.md
rename to src/gateway/get-started/index.md
diff --git a/src/gateway/get-started/ratelimiting.md b/src/gateway/get-started/ratelimiting.md
new file mode 100644
index 000000000000..98296c71315f
--- /dev/null
+++ b/src/gateway/get-started/ratelimiting.md
@@ -0,0 +1,187 @@
+---
+title: Configure Rate Limiting
+content-type: tutorial
+---
+
+
+## What is rate limiting?
+
+Rate limiting is used to control the rate of requests sent to an upstream service. It can be used to prevent DoS attacks, limit web scraping, and other forms of overuse. Without rate limiting, a user may make requests as often as they like, this leads to traffic spikes and it can impact other users of your upstream services. In {{site.base_gateway}} rate limiting allows you to set parameters that limit requests to your upstream service.
+
+
+## The rate limiting plugin
+
+{{site.base_gateway}} manages rate limiting through the use of Kong's [Rate Limiting plugin](/hub/kong-inc/rate-limiting). The rate limiting plugin has an open source and an enterprise version, with the enterprise version giving you access to features like [sliding window algorithm support](https://en.wikipedia.org/wiki/Sliding_window_protocol), and Redis support.
+
+
+The rate limiting plug-ins limit how often each user can call the API. This protects them from inadvertent or malicious overuse. Without rate limiting, each user may request as often as they like, which can lead to “spikes” of requests that starve other consumers. After rate limiting is enabled, they are limited to a fixed number of requests per second. Kong offers an open source and an Enterprise version of the rate limiting plug-in, with the Enterprise version providing support for the sliding window algorithm to prevent the API from being overloaded near window boundaries, and adds Redis support for greater performance. For this guide we will use the Enterprise version of plug-in. More details on the advanced rate limiting plug-in can be found here.
+
+
+Kong's [Rate Limiting plugin](/hub/kong-inc/rate-limiting) lets you restrict how many requests your upstream services receive from your API consumers, or how often each user can call the API.
+
+{:.note}
+> The [**Rate Limiting Advanced**](/hub/kong-inc/rate-limiting-advanced) plugin provides support for the sliding window algorithm to prevent the API from being overloaded near the window boundaries, and adds Redis support for greater performance.
+
+
+
+## Configure the Rate Limiting plugin
+
+
+To activate a plugin send a `POST` request to the [plugins](/gateway/latest/admin-api/#add-plugin) object of the Admin API:
+
+```sh
+curl -i -X POST http://localhost:8001/plugins \
+ --data name=rate-limiting \
+ --data config.minute=5 \
+ --data config.policy=local
+```
+
+This request configures the rate limiting plugin to enforce rate limiting on requests that exceed 5 per minute.
+
+### validate rate limiting
+
+After configuring rate limiting, you can verify that it was configured correctly and is working, by creating 6 requests within a 5 minute period.
+To validate rate limiting, send a request to the API six (6) times from the CLI to confirm the requests are rate limited.
+If you configured {{site.base_gateway}} with the [configure services and routes](/gateway/latest/get-started/configure-services-and-routes) guide use the example below, otherwise substitute the existing values for your own:
+
+{% navtabs %}
+{% navtab Admin API %}
+
+```sh
+curl -i -X GET http://localhost:8000/mock/request
+```
+
+{% endnavtab %}
+{% navtab Web browser %}
+
+Or you can follow these instructions from your web browser:
+
+1. Enter `localhost:8000/mock` and refresh your browser six times.
+ After the sixth request, you’ll receive an error message.
+2. Wait at least 30 seconds and try again.
+ The service will be accessible until the sixth access attempt within a 30-second window.
+
+{% endnavtab %}
+{% endnavtabs %}
+
+After the 6th request, you should receive a 429 "API rate limit exceeded" error:
+```
+{
+"message": "API rate limit exceeded"
+}
+```
+
+Every request triggers a counter that checks against the policy that was configured in the `POST` request.
+The value `config.policy = local` instructs {{site.base_gateway}} to store the policies and counters locally in memory.
+The available options for `config.policy` are:
+
+* `local` - Counters are stored locally in-memory on the node.
+* `cluster` - Counters are stored in the Kong data store and shared across the nodes.
+* `redis` - Counters are stored on a Redis server and shared across the nodes.
+
+
+### Rate limiting by domain
+
+
+The Rate Limiting plugin can be enabled and associated to three different scopes:
+
+* Service — restricts every consumer making requests to the service.
+
+* Route — restricts every consumer making requests to the specific route of the service.
+
+* Consumer — restricts only that specified consumer making requests to any routes of the service, using a `consumer_id`.
+
+
+### Service-level rate limiting
+
+You can rate limit specific services in order to restrict requests to an upstream application.
+
+```sh
+
+curl -X POST http://localhost:8001/services/example_service/plugins \
+--data "name=rate-limiting" \
+--data config.minute=5 \
+--data config.policy=local
+
+```
+
+
+### Route-level rate limiting
+
+You can limit traffic to a specific route:
+
+```sh
+
+curl -X POST http://localhost:8001/routes/mock/plugins \
+--data "name=rate-limiting" \
+--data "config.minute=2" \
+--data "config.hour=100"
+
+```
+
+If you did not follow the [configure services and routes](/gateway/latest/get-started/configure-services-and-routes) guide, replace the `mock` value with a `route_id`.
+
+
+### Consumer-level rate limiting
+
+Consumer-level rate limiting can be used when trying to apply rate limiting rules to specific consumer. Consumers are created using the [consumer object](/gateway/latest/admin-api/#consumer-object) in the Admin API. Because you haven't created a consumer yet, to try this type of rate limiting out you will have to first create a consumer:
+
+
+```sh
+
+curl -X POST http://localhost:8001/consumers/ \
+ --data username=example_consumer
+
+```
+
+And with the `example_consumer` variable, create another request to the `plugins` object, and pass `example_consumer` to the `consumer.id` parameter.
+```sh
+
+$ curl -X POST http://localhost:8001/plugins \
+--data "name=rate-limiting" \
+--data "consumer.id=example_consumer" \
+--data "config.second=5" \
+```
+
+
+## The Rate Limiting Advanced plugin
+
+Rate Limiting Advanced provides:
+
+* Additional configurations: `limit`, `window_size`, and `sync_rate`
+* Support for Redis Sentinel, Redis cluster, and Redis SSL
+* Increased performance: Rate Limiting Advanced has better throughput performance with better accuracy. Configure `sync_rate` to periodically sync with backend storage.
+* More limiting algorithms to choose from: These algorithms are more accurate and they enable configuration with more specificity. Learn more about our algorithms in How to Design a Scalable Rate Limiting Algorithm.
+* Consumer groups support: apply different rate limiting configurations to select groups of consumers.
+
+
+### Additional configuration
+
+The configuration process for the Rate Limiting Advanced plugin is similar to configuring the Rate Limiting plugin. To configure the Rate Limiting Advanced plugin create a `POST` request like this:
+
+```sh
+
+curl -i -X POST http://localhost:8001/plugins \
+--data name=rate-limiting-advanced \
+--data config.limit=5 \
+--data config.window_size=30 \
+--data config.sync_rate=-1
+
+```
+
+This request utilizes the `config.limit`, `config.window_size` and `config.sync_rate` form parameters.
+
+
+* config.limit: Number of requests allows per window.
+* config.window_size: Window size to track request for in seconds.
+* config.sync_rate: how often to sync counter data to the central data store. `-1` ignores sync behavior entirely and only stores counters in node memory, `>0 ` sync the counters in that many number of seconds.
+
+
+The word "window" here refers to a window of time, and the requests that can be made within that time frame. In the request you created, 5 requests can be made within a 30 second window of time. On the 6th request, the server will return a `429` response code. You can add multiple `window_size` and `config.limit` parameters to this request to specify, with granularity, the rate limiting rules.
+
+
+### Next steps
+
+The next tutorial in this series walks you through how and why to [configure proxy caching](/gateway/latest/get-started/configure-ratelimiting/).
+
+
diff --git a/src/gateway/understanding-kong/glossary.md b/src/gateway/glossary.md
similarity index 100%
rename from src/gateway/understanding-kong/glossary.md
rename to src/gateway/glossary.md
diff --git a/src/gateway/understanding-kong/health-checks-circuit-breakers.md b/src/gateway/how-kong-works/health-checks-circuit-breakers.md
similarity index 100%
rename from src/gateway/understanding-kong/health-checks-circuit-breakers.md
rename to src/gateway/how-kong-works/health-checks-circuit-breakers.md
diff --git a/src/gateway/understanding-kong/loadbalancing.md b/src/gateway/how-kong-works/loadbalancing.md
similarity index 100%
rename from src/gateway/understanding-kong/loadbalancing.md
rename to src/gateway/how-kong-works/loadbalancing.md
diff --git a/src/gateway/understanding-kong/kong-performance-testing.md b/src/gateway/how-kong-works/performance-testing.md
similarity index 100%
rename from src/gateway/understanding-kong/kong-performance-testing.md
rename to src/gateway/how-kong-works/performance-testing.md
diff --git a/src/gateway/understanding-kong/proxy.md b/src/gateway/how-kong-works/proxy.md
similarity index 100%
rename from src/gateway/understanding-kong/proxy.md
rename to src/gateway/how-kong-works/proxy.md
diff --git a/src/gateway/kong-production/install-options/docker/build-custom-images.md b/src/gateway/install/docker/build-custom-images.md
similarity index 100%
rename from src/gateway/kong-production/install-options/docker/build-custom-images.md
rename to src/gateway/install/docker/build-custom-images.md
diff --git a/src/gateway/kong-production/install-options/docker/index.md b/src/gateway/install/docker/index.md
similarity index 100%
rename from src/gateway/kong-production/install-options/docker/index.md
rename to src/gateway/install/docker/index.md
diff --git a/src/gateway/kong-production/install-options/helm-quickstart.md b/src/gateway/install/helm-quickstart.md
similarity index 100%
rename from src/gateway/kong-production/install-options/helm-quickstart.md
rename to src/gateway/install/helm-quickstart.md
diff --git a/src/gateway/kong-production/install-options/index.md b/src/gateway/install/index.md
similarity index 100%
rename from src/gateway/kong-production/install-options/index.md
rename to src/gateway/install/index.md
diff --git a/src/gateway/kong-production/kubernetes/kubernetes-deployment-options.md b/src/gateway/install/kubernetes/deployment-options.md
similarity index 100%
rename from src/gateway/kong-production/kubernetes/kubernetes-deployment-options.md
rename to src/gateway/install/kubernetes/deployment-options.md
diff --git a/src/gateway/install/kubernetes/helm-quickstart.md b/src/gateway/install/kubernetes/helm-quickstart.md
new file mode 100644
index 000000000000..22ca33377667
--- /dev/null
+++ b/src/gateway/install/kubernetes/helm-quickstart.md
@@ -0,0 +1,428 @@
+---
+title: Install with Kong Gateway using Helm
+toc: true
+content-type: how-to
+---
+
+
+This guide will show you how to install {{site.base_gateway}} on Kubernetes with Helm. Two options are provided for deploying a local development environment using [Docker Desktop Kubernetes](https://docs.docker.com/desktop/kubernetes/) and [Kind Kubernetes](https://kind.sigs.k8s.io/). You can also follow this guide using an existing cloud hosted Kubernetes cluster.
+
+
+{% navtabs %}
+{% navtab Docker Desktop Kubernetes %}
+## Docker Desktop
+
+Docker Desktop Kubernetes is a tool for running a local Kubernetes cluster using Docker. These instructions will guide you through deploying {{site.base_gateway}} to a local Docker Desktop Kubernetes cluster.
+
+## Dependencies
+
+- [`Helm 3`](https://helm.sh/)
+- [`kubectl`](https://kubernetes.io/docs/tasks/tools/) v1.19 or later
+- [Docker Desktop Kubernetes](https://docs.docker.com/desktop/kubernetes/)
+
+{:.note}
+> Kong services will be published to localhost at the domain name `https://kong.127-0-0-1.nip.io`. The [nip.io](https://nip.io) service is used to automatically resolve this domain to the localhost address.
+
+## Configure Kubectl
+
+Set your kubeconfig context and verify with the following command:
+
+ kubectl config use-context docker-desktop && kubectl cluster-info
+
+
+{% endnavtab %}
+{% navtab Kind Kubernetes %}
+
+## Kind Kubernetes
+
+Kind or "Kubernetes-in-Docker", is a tool for running local Kubernetes clusters in Docker containers. These instructions will guide you through deploying {{site.base_gateway}} to a local Kind Kubernetes cluster.
+
+
+## Dependencies
+
+- [`Helm 3`](https://helm.sh/)
+- [`kubectl`](https://kubernetes.io/docs/tasks/tools/) v1.19 or later
+- [KinD](https://kind.sigs.k8s.io/)
+
+{:.note}
+> Kong services will be published to localhost at the domain name `https://kong.127-0-0-1.nip.io`. The [nip.io](https://nip.io) service is used to automatically resolve this domain to the localhost address.
+
+## Create Kubernetes Cluster
+
+A Kind config file is required to build a local cluster listening locally on ports `80` and `443`. Starting from the `bash` command, and ending with the `EOF"` line, highlight and copy this text block, then paste it into your terminal.
+
+ bash -c "cat < /tmp/kind-config.yaml && kind create cluster --config /tmp/kind-config.yaml
+ apiVersion: kind.x-k8s.io/v1alpha4
+ kind: Cluster
+ name: kong
+ networking:
+ apiServerAddress: "0.0.0.0"
+ apiServerPort: 16443
+ nodes:
+ - role: control-plane
+ extraPortMappings:
+ - listenAddress: "0.0.0.0"
+ protocol: TCP
+ hostPort: 80
+ containerPort: 80
+ - listenAddress: "0.0.0.0"
+ protocol: TCP
+ hostPort: 443
+ containerPort: 443
+ EOF"
+
+Set your kubeconfig context and verify with the following commands.
+
+ kubectl config use-context kind-kong && kubectl cluster-info
+
+{% endnavtab %}
+{% navtab Kubernetes in the Cloud%}
+
+## Kubernetes in the cloud
+
+These instructions will guide you through deploying {{site.base_gateway}} to a cloud hosted Kubernetes cluster you have already built. Please ensure your local system and your Kubernetes cluster meet the dependency criteria listed below before continuing.
+
+{:.note}
+> Please note that it is recommended to first try the Docker Desktop or Kind Kubernetes local deploys before proceeding to build on a cloud hosted kubernetes cluster.
+
+## Dependencies
+
+- [`Helm 3`](https://helm.sh/)
+- [`kubectl`](https://kubernetes.io/docs/tasks/tools/) v1.19 or later
+- Domain Name
+- DNS configured with your DNS Provider
+- Public Cloud hosted Kubernetes cluster
+- [Cloud load balancer support](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/)
+
+## Configure Kubectl
+
+Verify your kubeconfig context is set correctly with the following command.
+
+ kubectl cluster-info
+
+## Prepare the Helm chart
+
+To inject your custom domain name into the Helm values file configure the {{site.base_gateway}} deployment with:
+
+1. `curl` the example values.yaml file.
+
+ curl -o ~/quickstart.yaml -L https://bit.ly/KongGatewayHelmValuesAIO
+
+2. Replace `example.com` with your preferred domain name and export as a variable.
+
+ export BASE_DOMAIN="example.com"
+
+3. Replace the `127-0-0-1.nip.io` base domain in the values file with your preferred domain name.
+
+ sed -i "s/127-0-0-1\.nip\.io/$BASE_DOMAIN/g" ~/quickstart.yaml
+
+{% endnavtab %}
+{% endnavtabs %}
+
+## Create {{site.base_gateway}} secrets
+
+Configuring {{site.base_gateway}} requires a namespace and configuration secrets. The secrets contain Kong's enterprise license, admin password, session configurations, and PostgreSQL connection details.
+
+1. Create the Kong namespace for {{site.base_gateway}}:
+
+ kubectl create namespace kong
+
+2. Create Kong config and credential variables:
+
+ kubectl create secret generic kong-config-secret -n kong \
+ --from-literal=portal_session_conf='{"storage":"kong","secret":"super_secret_salt_string","cookie_name":"portal_session","cookie_samesite":"off","cookie_secure":false}' \
+ --from-literal=admin_gui_session_conf='{"storage":"kong","secret":"super_secret_salt_string","cookie_name":"admin_session","cookie_samesite":"off","cookie_secure":false}' \
+ --from-literal=pg_host="enterprise-postgresql.kong.svc.cluster.local" \
+ --from-literal=kong_admin_password=kong \
+ --from-literal=password=kong
+
+4. Create a Kong Enterprise license secret:
+
+{% navtabs %}
+{% navtab Kong Enterprise Free Mode%}
+
+ kubectl create secret generic kong-enterprise-license --from-literal=license="'{}'" -n kong --dry-run=client -o yaml | kubectl apply -f -
+
+{% endnavtab %}
+{% navtab Kong Enterprise Licensed Mode%}
+
+ >This command must be run in the directory that contains your `license.json` file.
+
+ kubectl create secret generic kong-enterprise-license --from-file=license=license.json -n kong --dry-run=client -o yaml | kubectl apply -f -
+
+{% endnavtab %}
+{% endnavtabs %}
+
+{:.note}
+> Kong can run in two license modes, Enterprise Licensed, or Enterprise Free. If you would like to run all enterprise features, please contact your account manager to request a `license.json` file.
+
+## Install Cert Manager
+
+Cert Manager provides automation for generating SSL certificates. {{site.base_gateway}} uses Cert Manager to provide the required certificates.
+
+
+
+Install Cert Manager and create a basic [SelfSigned](https://cert-manager.io/docs/configuration/selfsigned/) certificate issuer:
+
+1. Add the Jetstack Cert Manager Helm repository:
+
+ helm repo add jetstack https://charts.jetstack.io ; helm repo update
+
+2. Install Cert Manager:
+
+ helm upgrade --install cert-manager jetstack/cert-manager \
+ --set installCRDs=true --namespace cert-manager --create-namespace
+
+3. Create a SelfSigned certificate issuer:
+
+ bash -c "cat < You will receive a "Your Connection is not Private" warning message due to using selfsigned certs. If you are using Chrome there may not be an "Accept risk and continue" option, to continue type `thisisunsafe` while the tab is in focus to continue.
+
+5. If running {{site.base_gateway}} in Licensed Mode, use the Super Admin username with the password set in the secret `kong-config-secret` created earlier: `kong_admin`:`kong`
+
+{% endnavtab %}
+{% navtab Kind Kubernetes %}
+
+Once all dependencies are installed and ready, deploy {{site.base_gateway}} to your cluster:
+
+1. Add the Kong Helm repo:
+
+ helm repo add kong https://charts.konghq.com ; helm repo update
+
+2. Install Kong:
+
+ helm install quickstart kong/kong --namespace kong --values https://bit.ly/KongGatewayHelmValuesAIO
+
+3. Wait for all pods to be in the `Running` state:
+
+ kubectl get po --namespace kong -w
+
+4. Once all the pods are running, open Kong Manager in your browser at its ingress host domain, for example: [https://kong.127-0-0-1.nip.io](https://kong.127-0-0-1.nip.io). Or open it with the following command:
+
+ open "https://$(kubectl get ingress --namespace kong quickstart-kong-manager -o jsonpath='{.spec.tls[0].hosts[0]}')"
+
+ {:.important}
+ > You will receive a "Your Connection is not Private" warning message due to using selfsigned certs. If you are using Chrome there may not be an "Accept risk and continue" option, to continue type `thisisunsafe` while the tab is in focus to continue.
+
+5. If running {{site.base_gateway}} in Licensed Mode, use the Super Admin username with the password set in the secret `kong-config-secret` created earlier: `kong_admin`:`kong`
+
+{% endnavtab %}
+{% navtab Kubernetes in the Cloud%}
+
+Once all dependencies are installed and ready, deploy {{site.base_gateway}} to your cluster:
+
+1. Add the Kong Helm repo:
+
+ helm repo add kong https://charts.konghq.com ; helm repo update
+
+2. Install Kong:
+
+ helm install quickstart kong/kong --namespace kong --values ~/quickstart.yaml
+
+3. Wait for all pods to be in the `Running` state:
+
+ kubectl get po --namespace kong -w
+
+4. Once all pods are running, find the cloud load balancer of your {{site.base_gateway}} data plane:
+
+ kubectl get svc --namespace kong quickstart-kong-proxy -w
+
+5. Using your DNS Provider, configure a DNS entry to point to the load balancer shown by the last step. A wildcard DNS record is recommended for development environments.
+
+6. Open Kong Manager with the kong subdomain on your domain. For example: `https://kong.example.com`, or open it with the following command:
+
+ open "https://$(kubectl get ingress --namespace kong quickstart-kong-manager -o jsonpath='{.spec.tls[0].hosts[0]}')"
+
+ {:.important}
+ > You will receive a "Your Connection is not Private" warning message due to using selfsigned certs. If you are using Chrome there may not be an "Accept risk and continue" option, to continue type `thisisunsafe` while the tab is in focus to continue.
+
+7. If running {{site.base_gateway}} in Licensed Mode, use the Super Admin username with the password set in the secret `kong-config-secret` created earlier: `kong_admin`:`kong`
+
+{% endnavtab %}
+{% endnavtabs %}
+
+## Use {{site.base_gateway}}
+
+{{site.base_gateway}} is now serving the Kong Manager WebGUI and the Kong Admin API.
+
+For local deployments, Kong Manager is locally accessible at `https://kong.127-0-0-1.nip.io`. The [nip.io](https://nip.io) service resolves this domain to localhost also known as `127.0.0.1`.
+
+You can configure Kong via the Admin API with [decK](https://docs.konghq.com/deck/latest/), [Insomnia](https://docs.insomnia.rest/insomnia/get-started), HTTPie, or cURL, at `https://kong.127-0-0-1.nip.io/api`:
+
+{% navtabs codeblock %}
+{% navtab cURL %}
+
+ curl --silent --insecure -X GET https://kong.127-0-0-1.nip.io/api -H 'kong-admin-token:kong'
+
+{% endnavtab %}
+{% navtab HTTPie %}
+
+ http --verify=no get https://kong.127-0-0-1.nip.io/api kong-admin-token:kong
+
+{% endnavtab %}
+{% endnavtabs %}
+
+## Teardown
+
+{% navtabs %}
+{% navtab Docker Desktop Kubernetes %}
+
+To remove {{site.base_gateway}} from your system, follow these instructions:
+
+1. Remove Kong
+
+ helm uninstall --namespace kong quickstart
+
+2. Delete Kong secrets
+
+ kubectl delete secrets -nkong kong-enterprise-license
+ kubectl delete secrets -nkong kong-config-secret
+
+3. Remove Kong database PVC
+
+ kubectl delete pvc -n kong data-quickstart-postgresql-0
+
+4. Remove Kong Helm chart repository
+
+ helm repo remove kong
+
+5. Remove cert-manager
+
+ helm uninstall --namespace cert-manager cert-manager
+
+6. Remove jetstack cert-manager Helm repository
+
+ helm repo remove jetstack
+
+{% endnavtab %}
+{% navtab Kind Kubernetes %}
+
+To remove {{site.base_gateway}} from your system, follow these instructions:
+
+1. Remove Kong
+
+ helm uninstall --namespace kong quickstart
+
+2. Delete Kong secrets
+
+ kubectl delete secrets -nkong kong-enterprise-license
+ kubectl delete secrets -nkong kong-config-secret
+
+3. Remove Kong database PVC
+
+ kubectl delete pvc -n kong data-quickstart-postgresql-0
+
+4. Remove Kong Helm chart repository
+
+ helm repo remove kong
+
+5. Remove cert-manager
+
+ helm uninstall --namespace cert-manager cert-manager
+
+6. Remove jetstack cert-manager Helm repository
+
+ helm repo remove jetstack
+
+7. Destroy the Kind cluster
+
+ kind delete cluster --name=kong
+ rm /tmp/kind-config.yaml
+
+{% endnavtab %}
+{% navtab Kubernetes in the Cloud%}
+
+To remove {{site.base_gateway}} from your system, follow these instructions:
+
+1. Remove Kong
+
+ helm uninstall --namespace kong quickstart
+
+2. Delete Kong secrets
+
+ kubectl delete secrets -nkong kong-enterprise-license
+ kubectl delete secrets -nkong kong-config-secret
+
+3. Remove Kong database PVC
+
+ kubectl delete pvc -n kong data-quickstart-postgresql-0
+
+4. Remove Kong Helm chart repository
+
+ helm repo remove kong
+
+5. Remove cert-manager
+
+ helm uninstall --namespace cert-manager cert-manager
+
+6. Remove jetstack cert-manager Helm Repository
+
+ helm repo remove jetstack
+
+{% endnavtab %}
+{% endnavtabs %}
+
+## Next Steps
+
+See the [Kong Ingress Controller docs](/kubernetes-ingress-controller/) for how-to guides, reference guides, and more.
diff --git a/src/gateway/kong-production/install-options/helm.md b/src/gateway/install/kubernetes/helm.md
similarity index 100%
rename from src/gateway/kong-production/install-options/helm.md
rename to src/gateway/install/kubernetes/helm.md
diff --git a/src/gateway/kong-production/install-options/kubernetes.md b/src/gateway/install/kubernetes/kubernetes.md
similarity index 100%
rename from src/gateway/kong-production/install-options/kubernetes.md
rename to src/gateway/install/kubernetes/kubernetes.md
diff --git a/src/gateway/kong-production/install-options/openshift.md b/src/gateway/install/kubernetes/openshift.md
similarity index 100%
rename from src/gateway/kong-production/install-options/openshift.md
rename to src/gateway/install/kubernetes/openshift.md
diff --git a/src/gateway/kong-production/install-options/linux/amazon-linux.md b/src/gateway/install/linux/amazon-linux.md
similarity index 100%
rename from src/gateway/kong-production/install-options/linux/amazon-linux.md
rename to src/gateway/install/linux/amazon-linux.md
diff --git a/src/gateway/kong-production/install-options/linux/centos.md b/src/gateway/install/linux/centos.md
similarity index 100%
rename from src/gateway/kong-production/install-options/linux/centos.md
rename to src/gateway/install/linux/centos.md
diff --git a/src/gateway/kong-production/install-options/linux/debian.md b/src/gateway/install/linux/debian.md
similarity index 100%
rename from src/gateway/kong-production/install-options/linux/debian.md
rename to src/gateway/install/linux/debian.md
diff --git a/src/gateway/kong-production/install-options/linux/os-support.md b/src/gateway/install/linux/os-support.md
similarity index 100%
rename from src/gateway/kong-production/install-options/linux/os-support.md
rename to src/gateway/install/linux/os-support.md
diff --git a/src/gateway/kong-production/install-options/linux/rhel.md b/src/gateway/install/linux/rhel.md
similarity index 100%
rename from src/gateway/kong-production/install-options/linux/rhel.md
rename to src/gateway/install/linux/rhel.md
diff --git a/src/gateway/kong-production/install-options/linux/ubuntu.md b/src/gateway/install/linux/ubuntu.md
similarity index 100%
rename from src/gateway/kong-production/install-options/linux/ubuntu.md
rename to src/gateway/install/linux/ubuntu.md
diff --git a/src/gateway/kong-production/install-options/macos.md b/src/gateway/install/macos.md
similarity index 100%
rename from src/gateway/kong-production/install-options/macos.md
rename to src/gateway/install/macos.md
diff --git a/src/gateway/understanding-kong/manange-kong-with-deck.md b/src/gateway/key-concepts/manage-kong-with-deck.md
similarity index 100%
rename from src/gateway/understanding-kong/manange-kong-with-deck.md
rename to src/gateway/key-concepts/manage-kong-with-deck.md
diff --git a/src/gateway/understanding-kong/key-concepts/plugins.md b/src/gateway/key-concepts/plugins.md
similarity index 100%
rename from src/gateway/understanding-kong/key-concepts/plugins.md
rename to src/gateway/key-concepts/plugins.md
diff --git a/src/gateway/understanding-kong/how-to/router-atc.md b/src/gateway/key-concepts/routes/expressions.md
similarity index 100%
rename from src/gateway/understanding-kong/how-to/router-atc.md
rename to src/gateway/key-concepts/routes/expressions.md
diff --git a/src/gateway/understanding-kong/key-concepts/routes.md b/src/gateway/key-concepts/routes/index.md
similarity index 100%
rename from src/gateway/understanding-kong/key-concepts/routes.md
rename to src/gateway/key-concepts/routes/index.md
diff --git a/src/gateway/understanding-kong/key-concepts/services.md b/src/gateway/key-concepts/services.md
similarity index 100%
rename from src/gateway/understanding-kong/key-concepts/services.md
rename to src/gateway/key-concepts/services.md
diff --git a/src/gateway/understanding-kong/key-concepts/upstreams.md b/src/gateway/key-concepts/upstreams.md
similarity index 100%
rename from src/gateway/understanding-kong/key-concepts/upstreams.md
rename to src/gateway/key-concepts/upstreams.md
diff --git a/src/gateway/admin-api/consumer-groups/examples.md b/src/gateway/kong-enterprise/consumer-groups/index.md
similarity index 100%
rename from src/gateway/admin-api/consumer-groups/examples.md
rename to src/gateway/kong-enterprise/consumer-groups/index.md
diff --git a/src/gateway/kong-enterprise/db-encryption.md b/src/gateway/kong-enterprise/db-encryption.md
index b940b7700db4..4b52497f964b 100644
--- a/src/gateway/kong-enterprise/db-encryption.md
+++ b/src/gateway/kong-enterprise/db-encryption.md
@@ -1,142 +1,231 @@
---
-title: Keyring & Data Encryption
+title: Keyring and Data Encryption
badge: enterprise
---
-## View Keyring
-**Endpoint**
+{{site.base_gateway}} provides a mechanism to store sensitive data fields, such as consumer secrets, in an encrypted format within the database. This provides for encryption-at-rest security controls in a Kong cluster.
-/keyring
+This functionality provides transparent, symmetric encryption of sensitive data fields at rest. _Transparency_ refers to the fact that, when enabled, encryption/decryption of data is done on-the-fly by Kong immediately before writing/immediately after reading from the database. Responses generated by the Admin API containing sensitive fields continue to show data as plaintext, and runtime elements of Kong (such as plugins) that require access to sensitive fields do so transparently, without requiring additional configuration.
-**Response**
+## Getting Started
-```
-HTTP 200 OK
-```
+This document provides a brief introduction to leveraging {{site.base_gateway}} symmetric database encryption to store sensitive configuration data in a Kong cluster. This document covers necessary Kong configuration settings and key management lifecycle procedures when using database encryption in `cluster` mode. This mode offers the simplest method to getting started, as it requires no external dependencies.
-```json
-{
- "active": "RfsDJ2Ol",
- "ids": [
- "RfsDJ2Ol",
- "xSD219lH"
- ]
-}
+### Generate a Management RSA Key Pair
+
+Before enabling database encryption, we strongly recommend you generate an RSA key pair for use in exporting and recovering keyring material. If keyring material is lost, it is impossible to recover any sensitive data fields written to the database with a key on that keyring.
+
+Generating an RSA key pair is straightforward via the `openssl` CLI:
+```bash
+$ openssl genrsa -out key.pem 2048
+$ openssl rsa -in key.pem -pubout -out cert.pem
```
-## View Active Key
-**Endpoint**
+This key pair will be provided to Kong in order to facilitate recovering, exporting, and re-importing the keyring. The public `cert.pem` and private `key.pem` should be stored securely in accordance with your existing secrets management policies. Details on secure storage of RSA key pairs are outside the scope of this documentation.
-/keyring/active
+### Configure Kong for database encryption
-**Response**
+Enabling data encryption in Kong requires modifying the Kong configuration. Set the following values in `kong.conf`:
```
-HTTP 200 OK
+keyring_enabled = on
+keyring_strategy = cluster
+keyring_recovery_public_key = /path/to/generated/cert.pem
```
-```json
-{
- "id": "RfsDJ2Ol"
-}
+Or via environmental variables:
+```
+export KONG_KEYRING_ENABLED=on
+export KONG_KEYRING_STRATEGY=cluster
+export KONG_KEYRING_RECOVERY_PUBLIC_KEY=/path/to/generated/cert.pem
```
-## Export Keyring
+All nodes in the Kong cluster should share the same `keyring_enabled` and `keyring_strategy` configuration values.
+The generated private key `key.pem` is not required to configure Kong, or to start Kong. Please refer to the [disaster recovery](#disaster-recovery) section for more information on how to use private keys in keyring management.
-*This endpoint is only available with the `cluster` keyring strategy.*
+### Start Kong
-*The endpoint requires that the `keyring_public_key` and `keyring_private_key` Kong configuration values are defined.*
+Once all Kong nodes in the cluster have been configured, start each node:
-**Endpoint**
+```bash
+$ kong start
+```
-/keyring/export
+When encryption is enabled on a Kong node, it checks the status of the cluster keyring on boot. If it detects that no keys are present in the keyring, it will generate a key automatically. This process allows encryption/decryption operations to begin immediately.
-**Response**
+For all other nodes, the generated key will be automatically distributed within a few seconds.
-```
-HTTP 200 OK
-```
+Note that encryption keys are held _only_ in memory, and do not persist past a restart of the Kong process (e.g., running `kong restart`). Because of this limitation, you must [recover](#recover-the-keyring) or [import](#import-the-keyring) the keyring following initialization. Otherwise, if all Kong nodes in a cluster restart simultaneously, any sensitive fields written with the keyring become unrecoverable. Key material still persists after a soft reload of Kong (i.e., `kong reload`).
-```json
+### Verify the Cluster Keyring
+
+With the keyring enabled and Kong started, verify the contents of the keyring:
+
+
+```bash
+$ curl -s localhost:8001/keyring | jq
{
- "data": "..."
+ "ids": [
+ "LaW1urRQ"
+ ],
+ "active": "LaW1urRQ"
}
```
-## Import Exported Keyring
+Note that in this example, the value `LaW1urRQ` is the _ID_ of the key, not the key material itself.
-*This endpoint is only available with the `cluster` keyring strategy.*
-*The endpoint requires that the `keyring_public_key` and `keyring_private_key` Kong configuration values are defined.*
+### Exercise the Encryption Routines
-**Endpoint**
+Create a Consumer with a basic-auth credential. At this point, the `password` field of the basic-auth credential will be symmetrically encrypted before it is written to the database (in addition to being hashed by the basic-auth plugin, which is done by the plugin regardless of whether keyring encryption is enabled):
-/keyring/import
+```bash
+$ curl -s localhost:8001/consumers -d username=bob | jq
+{
+ "custom_id": null,
+ "created_at": 1576518610,
+ "id": "6375b5fd-9c95-4822-b2dd-80ffbccb7ec9",
+ "tags": null,
+ "username": "bob",
+ "type": 0
+}
+```
-**Request Body**
+```bash
+$ curl -s localhost:8001/consumers/bob/basic-auth -d username=bob -d password=supersecretpassword | jq
+{
+ "created_at": 1576518704,
+ "consumer": {
+ "id": "6375b5fd-9c95-4822-b2dd-80ffbccb7ec9"
+ },
+ "id": "fc46ce48-c1d6-4078-9f51-5a777350a8a2",
+ "password": "da61c0083b6d19ef3db2490d0da96a71572da0fa",
+ "username": "bob"
+}
+```
-| Attribute | Description |
-| --------- | ----------- |
-| `data` | Base64-encoded keyring export material. |
+Note that the returned `password` field in the API response is not the encrypted value; database encryption does not modify responses generated by the Admin API. This allows existing workflows to continue in the same form, while providing encryption at rest security under the hood. We can verify this by examining the value stored in the database:
+```
+kong=# select id,password from basicauth_credentials;
+ id | password
+--------------------------------------+---------------------------------------------------------------------------------------------------------------------------
+ fc46ce48-c1d6-4078-9f51-5a777350a8a2 | $ke$1$-LaW1urRQ-0f5b1ee8ddeefca1a1d75125-53f158a5f619133a2113692a7057e2b91fa947321de4480d452dd42c36bc9ef8aa6499cd429db6d7
+(1 row)
+```
-**Response**
+We can also verify that reading back the credential after it has been created behaves as expected:
+```bash
+$ curl -s localhost:8001/consumers/bob/basic-auth/fc46ce48-c1d6-4078-9f51-5a777350a8a2 | jq
+{
+ "created_at": 1576518704,
+ "consumer": {
+ "id": "6375b5fd-9c95-4822-b2dd-80ffbccb7ec9"
+ },
+ "id": "fc46ce48-c1d6-4078-9f51-5a777350a8a2",
+ "password": "da61c0083b6d19ef3db2490d0da96a71572da0fa",
+ "username": "bob"
+}
```
-HTTP 201 Created
+
+### Rotating Key Material
+
+As noted above, Kong supports rotating keys by allowing for multiple keys to exist on the keyring at the same time. This allows for data fields written by one key to be read back, while a fresher encryption key is used for write operations. Rotating keys is a matter of importing or generating a new key into the keyring, and marking it as active. Arbitrary key material can be imported via the `/keyring/import` material, or Kong can generate a new key via `/keyring/generate` endpoint:
+
+```bash
+$ curl -XPOST -s localhost:8001/keyring/generate
+{
+ "key": "t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44=",
+ "id": "8zgITLQh"
+}
```
-## Import Key
+Note that as a convenience the raw key material is returned from this endpoint call.
-*This endpoint is only available with the `cluster` keyring strategy.*
+Once a new key is present in the keyring, activate the key's ID:
-*The endpoint requires that the `keyring_public_key` and `keyring_private_key` Kong configuration values are defined.*
+```bash
+$ curl -s localhost:8001/keyring/activate -d key=8zgITLQh
+```
-**Endpoint**
+Kong can write new sensitive data fields with the current `active` key, and read previously written fields in the database with the prior key, provided that key is in the keyring. Kong automatically selects the appropriate key to use when decrypting fields from the database.
-/keyring/import/raw
+At this point, it is encouraged to take another backup of the keyring via the `/keyring/export` Admin API endpoint.
-**Request Body**
+### Rotating Encrypted Data Fields
-| Attribute | Description |
-| --------- | ----------- |
-| `id` | 8-byte key identifier. |
-| `data` | Base64-encoded keyring export material. |
+Once the keyring has updated, existing encrypted fields can rotate to use the new active key. To accomplish this rotation, issue a PATCH request to the entity in question:
+```bash
+$ # curl -XPATCH -s localhost:8001/consumers/bob/basic-auth/fc46ce48-c1d6-4078-9f51-5a777350a8a2 -d password=adifferentsecretpassword | jq
+{
+ "created_at": 1576518704,
+ "consumer": {
+ "id": "6375b5fd-9c95-4822-b2dd-80ffbccb7ec9"
+ },
+ "id": "fc46ce48-c1d6-4078-9f51-5a777350a8a2",
+ "password": "cc7274e94e41f3e00c238ff8712d1a83693f2a89",
+ "username": "bob"
+}
+```
-**Response**
+Again, note that the encryption behavior is transparent to the Admin API response. Under the hood, Kong reads the entity's `password` field with a read-only encryption key. As part of the PATCH process, Kong writes the `password` field back to the database with the new `active` key. To verify this process, examine the raw contents of the database:
```
-HTTP 201 Created
+kong=# select id,password from basicauth_credentials;
+ id | password
+--------------------------------------+---------------------------------------------------------------------------------------------------------------------------
+ fc46ce48-c1d6-4078-9f51-5a777350a8a2 | $ke$1$-8zgITLQh-b8d28531252241e6b95907e4-0768a9a4baaa2c777d9406d4e3098d813be55ae82c4c849182b06b9c5954704c6290c9e677bcd693
+(1 row)
```
-## Recovery Keyring from Database
+Note that the key identifier within the password data blob has been updated. This rotation mechanism allows organizations to meet specific compliance needs around key management rotation and retention policies.
-*This endpoint is only available with the `cluster` keyring strategy.*
+Currently, encrypted fields must undergo a direct write operation in order to rotate the encrypted field. Future releases of Kong may contain helper API operations to automate this process.
-*The endpoint requires that the `keyring_recovery_public_key` Kong configuration value is defined.*
+### Exploring Missing Keyring Material Behavior
-**Endpoint**
+As a test, stop all Kong nodes in the cluster, and restart one Kong node again, but do not import the keyring material. The behavior of attempting to read an entity with an encrypted field now changes:
-/keyring/recover
+```bash
+$ time curl -s localhost:8001/consumers/bob/basic-auth/fc46ce48-c1d6-4078-9f51-5a777350a8a2
+{"message":"An unexpected error occurred"}
+real 0m24.811s
+user 0m0.017s
+sys 0m0.006s
+```
+
+When the Kong node restarts, it sends a broadcast request for the keyring, but as no other nodes are present in the cluster (or no other nodes had the keyring available), Kong is unable to decrypt the `password` field on the credential. Because Kong has an eventually-consistent clustering model, it makes several attempts to request the keyring and allows for delays in hearing responses from another cluster node; thus, the request takes several seconds to complete before finally failing.
-**Request Body**
+## Disaster Recovery
-| Attribute | Description |
-| --------- | ----------- |
-| `recovery_private_key` | The content of the private key. |
+`cluster` strategy supports two disaster recovery strategies.
-**Response**
+### Automatic backup and manual recovery
+To use automatic backups for keyring materials, configure `keyring_recovery_public_key`:
```
-HTTP 200 OK
+keyring_recovery_public_key = /path/to/generated/cert.pem
```
-```json
+Or via environmental variables:
+
+```
+export KONG_KEYRING_RECOVERY_PUBLIC_KEY=/path/to/generated/cert.pem
+```
+
+#### Recover the Keyring
+
+The keyring material is then encrypted with the public RSA key defined with the `keyring_recovery_public_key`
+Kong configuration value in the database. The corresponding private key can be used to decrypt the keyring material in the database:
+
+```bash
+$ curl -X POST localhost:8001/keyring/recover -F recovery_private_key=@/path/to/generated/key.pem
{
- "message": "successfully recovered 1 keys",
+ "message": "successfully recovered 1 keys",
"recovered": [
"RfsDJ2Ol"
],
@@ -146,58 +235,141 @@ HTTP 200 OK
}
```
-## Generate New Key
+The response contains a list of keys that were successfully recovered and that could not be recovered. The Kong error log will contain the detailed reason why the keys could not be recovered.
-*This endpoint is only available with the `cluster` keyring strategy.*
+### Manual export and manual import
-**Endpoint**
+**Use of this method is deprecated in Kong 3.0 and will be removed in a future release.**
-/keyring/generate
+```
+keyring_public_key = /path/to/generated/cert.pem
+keyring_private_key = /path/to/generated/key.pem
+```
-**Response**
+Or via environmental variables:
```
-HTTP 201 Created
+export KONG_KEYRING_PUBLIC_KEY=/path/to/generated/cert.pem
+export KONG_KEYRING_PRIVATE_KEY=/path/to/generated/key.pem
```
-```json
-{
- "id": "500pIquV",
- "key": "3I23Ben5m7qKcCA/PK7rnsNeD3kI4IPtA6ki7YjAgKA="
-}
+Not every node needs to be provided the management RSA key pair, as that key pair is only used for backup and recovery processes. It does not need to be present for regular database read/write operations.
+
+The user that the Kong worker process is running under must have read access to the public and private keys in order to be able to import and export keyrings. This user is defined with the `nginx_user` Kong configuration option. We recommend restricting access to these files, for example:
+
+```bash
+$ chown : /path/to/generated/cert.pem /path/to/generated/key.pem
+$ chmod 400 /path/to/generated/cert.pem /path/to/generated/key.pem
```
-## Remove Key from Keyring
+When testing, you can set `keyring_blob_path` in kong.conf or `KONG_KEYRING_BLOB_PATH`
+using environmental variables to specify a path to dump known keys. The dumped keys are
+encrypted with the public RSA key defined in the `keyring_public_key` Kong configuration
+value, and are automatically loaded when Kong starts.
-*This endpoint is only available with the `cluster` keyring strategy.*
+#### Export the Keyring
-**Endpoint**
+Export the keyring. The exported material can be re-imported to the cluster in the event of an outage or to restore a previously-deleted key:
-/keyring/remove
+```bash
+$ curl -XPOST -s localhost:8001/keyring/export | jq
+{
+ "data": "eyJrIjoiV1JZeTdubDlYeFZpR3VVQWtWTXBcL0JiVW1jMWZrWHluc0dKd3N4M1c0MlIxWE5XM05lZ05sdFdIVmJ1d0ZnaVZSTnFSdmM1WERscGY3b0NIZ1ZDQ3JvTFJ4czFnRURhOXpJT0tVV0prM2lhd0VLMHpKTXdwRDd5ZjV2VFYzQTY0Y2UxcVl1emJoSTI4VUZ1ZExRZWljVjd2T3BYblVvU3dOY3IzblhJQWhyWlcxc1grWXE3aHM1RzhLRXY2OWlRamJBTXAwbHZmTWNFWWxTOW9NUjdnSm5xZWlST0J1Q09iMm5tSXg0Qk1uaTJGalZzQzBtd2R2dmJyYWxYa3VLYXhpRWZvQm9EODk3MEtVcDYzY05lWGdJclpjang4YmJDV1lDRHlEVmExdGt5c0g1TjBJM0hTNDRQK1dyT2JkcElCUk5vSVZVNis1QWdcLzdZM290RUdzN1E9PSIsImQiOiIxWEZJOXZKQ05CTW5uVTB5c0hQenVjSG5nc2c5UURxQmcxZ3g1VVYxNWNlOEVTTlZXTmthYm8zdlUzS2VRTURcL0RUYXdzZCtJWHB5SllBTkRtanZNcytqU2lrVTFiRkpyMEVcLzBSRlg2emJrT0oybTR2bXlxdVE9PSIsIm4iOiJUUmRLK01Qajh6MkdHTmtyIn0="
+}
+
+```
-**Request Body**
+The response generated is an opaque blob containing the keyring. This blob is encrypted with
+a randomly-generated symmetric key, which is encrypted with the public
+RSA key defined via the `keyring_public_key` Kong configuration value.
-| Attribute | Description |
-| --------- | ----------- |
-| `key` | 8-byte key identifier. |
+The exported keyring should be stored in a safe location for disaster recovery
+purposes. It is not designed to be modified or decrypted before being used during
+a disaster recovery process.
+#### Import the Keyring
-**Response**
+Restart Kong and re-import the previously exported keyring:
+```bash
+$ kong restart
```
-HTTP 204 No Content
+
+```bash
+$ curl localhost:8001/keyring/import -d data=
```
-## Sync Keyring with Vault Endpoint
+This operation requires that the `keyring_private_key` point to the private RSA
+key associated with the public key used during the initial keyring export. Once
+this is complete, Admin API operations that require the keyring for encryption/
+decryption can be verified:
-*This endpoint is only available with the `vault` keyring strategy.*
+```bash
+$ curl -s localhost:8001/consumers/bob/basic-auth/fc46ce48-c1d6-4078-9f51-5a777350a8a2 | jq
+{
+ "created_at": 1576518704,
+ "consumer": {
+ "id": "6375b5fd-9c95-4822-b2dd-80ffbccb7ec9"
+ },
+ "id": "fc46ce48-c1d6-4078-9f51-5a777350a8a2",
+ "password": "da61c0083b6d19ef3db2490d0da96a71572da0fa",
+ "username": "bob"
+}
+```
-**Endpoint**
-/keyring/vault/sync
+## Implementation Details
-**Response**
+### Encryption/Decryption
+{{site.base_gateway}} uses 256-bit AES encryption in GCM mode. Cryptographic nonce values for each encryption routine execution are derived from the kernel CSPRNG (`/dev/urandom`). The AES routines used by Kong are provided by the OpenSSL library bundled with the {{site.base_gateway}} package.
+
+### Key Generation and Lifecycle
+
+{{site.base_gateway}}'s keyring handling mechanisms allow for more than one key to be present on any given Kong node at a time. Each key may be used to read encrypted fields from the database, but one and only one key at any given time is used to write encrypted fields back to the data store. This process allows for a key rotation mechanism wherein new keyring material is introduced, and older keys may be present for a time to allow rotating previously-encrypted fields.
+
+Through the kernel CSPRNG, Kong derives keyring material generated through the `/keyring/generate` Admin API endpoint. Kong stores keyring material in a shared memory zone that all Kong worker processes access. To prevent key material from being written to disk as part of memory paging operations, we recommend that swap be disabled on systems running Kong
+
+When operating in `cluster` mode, keyring material propagates automatically among all nodes in the Kong cluster. Because Kong nodes do not have a notion of direct peer-to-peer communication, the underlying datastore serves as a communication channel to transmit messages. When a Kong node starts, it generates an ephemeral RSA key pair. The node's public keys propagate to all other active nodes in the cluster. When an active node sees a message request for keyring material, it wraps the in-memory keyring material in the presented public key, and transmits the payload back over the central messaging channel provided by the underlying data store. This process allows each node in the cluster to broadcast keyring material to new nodes, without sending key material in plaintext over the wire. This model requires that at least one node be running at all times within the cluster; a failure of all nodes requires manually re-importing the keyring to one node during an outage recovery.
+
+### Encrypted Fields
+
+The keyring module encrypts the following fields at rest:
+
+* `key` fields of `certificate` objects (corresponding to the private key of a TLS certificate).
+* Certain configuration parameters in plugins and plugin-related authentication
+objects. For information on which plugin fields are encrypted, see
+[each individual plugin's documentation](/hub/).
+
+## Vault Integration
+
+Kong's keyring mechanism can integrate directly with [HashiCorp Vault](https://www.vaultproject.io/) for keyring storage and versioning. In this model, Kong nodes read keyring material directly from a Vault KV secrets engine, rather than generating and disseminating keyring material around the cluster.
+
+To configure Kong to use Vault for keyring storage, set the `keyring_strategy` configuration value to `vault`. Leveraging Vault also requires defining a host, mount point, and token for Vault access. See the Kong configuration reference for more details.
+
+### Key Format
+
+Kong leverages version 2 of the [Vault KV secrets engine](https://www.vaultproject.io/docs/secrets/kv/kv-v2.html). This process allows for the same versioning and key rotation mechanisms that the `cluster` keyring strategy provides. Each version of a KV secrets entry must contain both an `id` field, and a `key` field, e.g.:
+
+```json
+{
+ "key": "t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44=",
+ "id": "8zgITLQh"
+}
```
-HTTP 204 No Content
-```
+
+To provide consistent consumption of all Vault KV secrets, the underlying symmetric key is derived as the SHA256 of the `key` component of the secret value. Take note of this derivation when extending or re-using symmetric encryption keys from other systems. This derivation also implies that the `key` field can contain any arbitrary data, as Kong hashes the contents before importing the material into the keyring.
+
+To provide a new key, add a new version to the Vault secrets engine at the configured path. The `current_version` of the Vault secret denotes the active key in the keyring. See the [KV v2 documentation](https://www.vaultproject.io/docs/secrets/kv/kv-v2.html) for more detail.
+
+### Vault Permissions
+
+In order to communicate with Vault, Kong must be provided a Vault token for access. The token must be associated with a policy that allows the `read` and `list` actions on the path where keyring secrets are stored. Kong does not write keyring material to the Vault cluster.
+
+### Syncing the Keyring
+
+Kong reads the keyring material from Vault when the Kong process starts. Any changes to the Vault KV store are not reflected on the Kong node until Kong syncs with Vault via the `/keyring/vault/sync` Admin API endpoint. This allows Kong to receive a Vault token with a low TTL, as the list and read operation only occur once.
+
+### Keyring on hybrid mode
+
+Because Keyring encrypts the data in the database, it means it doesn't encrypt data on Kong data plane nodes that run without a database and get data from the control plane. However, one can turn on `declarative_config_encryption_mode` within the Kong configuration, or use secrets management to securely store sensitive data on the data plane nodes.
diff --git a/src/gateway/kong-enterprise/developer-portal/customize/easy-theme-editing.md b/src/gateway/kong-enterprise/developer-portal/customize/theme-editing.md
similarity index 100%
rename from src/gateway/kong-enterprise/developer-portal/customize/easy-theme-editing.md
rename to src/gateway/kong-enterprise/developer-portal/customize/theme-editing.md
diff --git a/src/gateway/kong-enterprise/developer-portal/enable-dev-portal.md b/src/gateway/kong-enterprise/developer-portal/enable.md
similarity index 100%
rename from src/gateway/kong-enterprise/developer-portal/enable-dev-portal.md
rename to src/gateway/kong-enterprise/developer-portal/enable.md
diff --git a/src/gateway/admin-api/event-hooks/examples.md b/src/gateway/kong-enterprise/event-hooks/index.md
similarity index 100%
rename from src/gateway/admin-api/event-hooks/examples.md
rename to src/gateway/kong-enterprise/event-hooks/index.md
diff --git a/src/gateway/understanding-kong/how-to/aws-secrets-manager.md b/src/gateway/kong-enterprise/secrets-management/how-to/aws-secrets-manager.md
similarity index 100%
rename from src/gateway/understanding-kong/how-to/aws-secrets-manager.md
rename to src/gateway/kong-enterprise/secrets-management/how-to/aws-secrets-manager.md
diff --git a/src/gateway/kong-enterprise/vitals/vitals-estimates.md b/src/gateway/kong-enterprise/vitals/estimates.md
similarity index 100%
rename from src/gateway/kong-enterprise/vitals/vitals-estimates.md
rename to src/gateway/kong-enterprise/vitals/estimates.md
diff --git a/src/gateway/kong-enterprise/vitals/vitals-influx-strategy.md b/src/gateway/kong-enterprise/vitals/influx-strategy.md
similarity index 100%
rename from src/gateway/kong-enterprise/vitals/vitals-influx-strategy.md
rename to src/gateway/kong-enterprise/vitals/influx-strategy.md
diff --git a/src/gateway/kong-enterprise/vitals/vitals-metrics.md b/src/gateway/kong-enterprise/vitals/metrics.md
similarity index 100%
rename from src/gateway/kong-enterprise/vitals/vitals-metrics.md
rename to src/gateway/kong-enterprise/vitals/metrics.md
diff --git a/src/gateway/kong-enterprise/vitals/vitals-prometheus-strategy.md b/src/gateway/kong-enterprise/vitals/prometheus-strategy.md
similarity index 100%
rename from src/gateway/kong-enterprise/vitals/vitals-prometheus-strategy.md
rename to src/gateway/kong-enterprise/vitals/prometheus-strategy.md
diff --git a/src/gateway/kong-enterprise/vitals/vitals-reports.md b/src/gateway/kong-enterprise/vitals/reports.md
similarity index 100%
rename from src/gateway/kong-enterprise/vitals/vitals-reports.md
rename to src/gateway/kong-enterprise/vitals/reports.md
diff --git a/src/gateway/admin-api/workspaces/examples.md b/src/gateway/kong-enterprise/workspaces/index.md
similarity index 96%
rename from src/gateway/admin-api/workspaces/examples.md
rename to src/gateway/kong-enterprise/workspaces/index.md
index 98632756cc69..b7f0c6782e48 100644
--- a/src/gateway/admin-api/workspaces/examples.md
+++ b/src/gateway/kong-enterprise/workspaces/index.md
@@ -3,11 +3,6 @@ title: Workspace Examples
badge: enterprise
---
-This chapter aims to provide a step-by-step tutorial on how to set up
-workspaces, entities, and see it in action.
-
-## Important Note: Conflicting Services or Routes in workspaces
-
Workspaces provide a way to segment Kong entities—entities in a workspace
are isolated from those in other workspaces. That said, entities
such as Services and Routes have "routing rules", which are pieces of info
diff --git a/src/gateway/kong-manager/auth/overview.md b/src/gateway/kong-manager/auth/index.md
similarity index 100%
rename from src/gateway/kong-manager/auth/overview.md
rename to src/gateway/kong-manager/auth/index.md
diff --git a/src/gateway/kong-manager/overview.md b/src/gateway/kong-manager/index.md
similarity index 100%
rename from src/gateway/kong-manager/overview.md
rename to src/gateway/kong-manager/index.md
diff --git a/src/gateway/kong-plugins/authentication/oidc/oidc-auth0.md b/src/gateway/kong-plugins/authentication/oidc/auth0.md
similarity index 100%
rename from src/gateway/kong-plugins/authentication/oidc/oidc-auth0.md
rename to src/gateway/kong-plugins/authentication/oidc/auth0.md
diff --git a/src/gateway/kong-plugins/authentication/oidc/oidc-azuread.md b/src/gateway/kong-plugins/authentication/oidc/azure-ad.md
similarity index 100%
rename from src/gateway/kong-plugins/authentication/oidc/oidc-azuread.md
rename to src/gateway/kong-plugins/authentication/oidc/azure-ad.md
diff --git a/src/gateway/kong-plugins/authentication/oidc/oidc-cognito.md b/src/gateway/kong-plugins/authentication/oidc/cognito.md
similarity index 100%
rename from src/gateway/kong-plugins/authentication/oidc/oidc-cognito.md
rename to src/gateway/kong-plugins/authentication/oidc/cognito.md
diff --git a/src/gateway/kong-plugins/authentication/oidc/oidc-curity.md b/src/gateway/kong-plugins/authentication/oidc/curity.md
similarity index 100%
rename from src/gateway/kong-plugins/authentication/oidc/oidc-curity.md
rename to src/gateway/kong-plugins/authentication/oidc/curity.md
diff --git a/src/gateway/kong-plugins/authentication/oidc/oidc-google.md b/src/gateway/kong-plugins/authentication/oidc/google.md
similarity index 100%
rename from src/gateway/kong-plugins/authentication/oidc/oidc-google.md
rename to src/gateway/kong-plugins/authentication/oidc/google.md
diff --git a/src/gateway/kong-plugins/authentication/oidc/oidc-use-case.md b/src/gateway/kong-plugins/authentication/oidc/index.md
similarity index 100%
rename from src/gateway/kong-plugins/authentication/oidc/oidc-use-case.md
rename to src/gateway/kong-plugins/authentication/oidc/index.md
diff --git a/src/gateway/kong-plugins/authentication/oidc/oidc-okta.md b/src/gateway/kong-plugins/authentication/oidc/okta.md
similarity index 100%
rename from src/gateway/kong-plugins/authentication/oidc/oidc-okta.md
rename to src/gateway/kong-plugins/authentication/oidc/okta.md
diff --git a/src/gateway/kong-plugins/authentication/auth-reference.md b/src/gateway/kong-plugins/authentication/reference.md
similarity index 100%
rename from src/gateway/kong-plugins/authentication/auth-reference.md
rename to src/gateway/kong-plugins/authentication/reference.md
diff --git a/src/gateway/kong-plugins/graphql-quickstart.md b/src/gateway/kong-plugins/graphql.md
similarity index 100%
rename from src/gateway/kong-plugins/graphql-quickstart.md
rename to src/gateway/kong-plugins/graphql.md
diff --git a/src/gateway/understanding-kong/how-to/request-transformations.md b/src/gateway/kong-plugins/request-transformer/add-body-value.md
similarity index 100%
rename from src/gateway/understanding-kong/how-to/request-transformations.md
rename to src/gateway/kong-plugins/request-transformer/add-body-value.md
diff --git a/src/gateway/kong-production/licenses/deploy-license.md b/src/gateway/licenses/deploy.md
similarity index 100%
rename from src/gateway/kong-production/licenses/deploy-license.md
rename to src/gateway/licenses/deploy.md
diff --git a/src/gateway/kong-production/licenses/access-license.md b/src/gateway/licenses/download.md
similarity index 95%
rename from src/gateway/kong-production/licenses/access-license.md
rename to src/gateway/licenses/download.md
index a386b9980be4..720a5f734493 100644
--- a/src/gateway/kong-production/licenses/access-license.md
+++ b/src/gateway/licenses/download.md
@@ -1,5 +1,5 @@
---
-title: Access Your Kong Gateway License
+title: Download Your Kong Gateway License
badge: enterprise
---
diff --git a/src/gateway/admin-api/licenses/examples.md b/src/gateway/licenses/examples.md
similarity index 100%
rename from src/gateway/admin-api/licenses/examples.md
rename to src/gateway/licenses/examples.md
diff --git a/src/gateway/kong-production/licenses/index.md b/src/gateway/licenses/index.md
similarity index 100%
rename from src/gateway/kong-production/licenses/index.md
rename to src/gateway/licenses/index.md
diff --git a/src/gateway/kong-production/licenses/report.md b/src/gateway/licenses/report.md
similarity index 100%
rename from src/gateway/kong-production/licenses/report.md
rename to src/gateway/licenses/report.md
diff --git a/src/gateway/plan-and-deploy/security/db-encryption.md b/src/gateway/plan-and-deploy/security/db-encryption.md
deleted file mode 100644
index 4b52497f964b..000000000000
--- a/src/gateway/plan-and-deploy/security/db-encryption.md
+++ /dev/null
@@ -1,375 +0,0 @@
----
-title: Keyring and Data Encryption
-badge: enterprise
----
-
-{{site.base_gateway}} provides a mechanism to store sensitive data fields, such as consumer secrets, in an encrypted format within the database. This provides for encryption-at-rest security controls in a Kong cluster.
-
-This functionality provides transparent, symmetric encryption of sensitive data fields at rest. _Transparency_ refers to the fact that, when enabled, encryption/decryption of data is done on-the-fly by Kong immediately before writing/immediately after reading from the database. Responses generated by the Admin API containing sensitive fields continue to show data as plaintext, and runtime elements of Kong (such as plugins) that require access to sensitive fields do so transparently, without requiring additional configuration.
-
-## Getting Started
-
-This document provides a brief introduction to leveraging {{site.base_gateway}} symmetric database encryption to store sensitive configuration data in a Kong cluster. This document covers necessary Kong configuration settings and key management lifecycle procedures when using database encryption in `cluster` mode. This mode offers the simplest method to getting started, as it requires no external dependencies.
-
-### Generate a Management RSA Key Pair
-
-Before enabling database encryption, we strongly recommend you generate an RSA key pair for use in exporting and recovering keyring material. If keyring material is lost, it is impossible to recover any sensitive data fields written to the database with a key on that keyring.
-
-Generating an RSA key pair is straightforward via the `openssl` CLI:
-
-```bash
-$ openssl genrsa -out key.pem 2048
-$ openssl rsa -in key.pem -pubout -out cert.pem
-```
-
-This key pair will be provided to Kong in order to facilitate recovering, exporting, and re-importing the keyring. The public `cert.pem` and private `key.pem` should be stored securely in accordance with your existing secrets management policies. Details on secure storage of RSA key pairs are outside the scope of this documentation.
-
-### Configure Kong for database encryption
-
-Enabling data encryption in Kong requires modifying the Kong configuration. Set the following values in `kong.conf`:
-
-```
-keyring_enabled = on
-keyring_strategy = cluster
-keyring_recovery_public_key = /path/to/generated/cert.pem
-```
-
-Or via environmental variables:
-
-```
-export KONG_KEYRING_ENABLED=on
-export KONG_KEYRING_STRATEGY=cluster
-export KONG_KEYRING_RECOVERY_PUBLIC_KEY=/path/to/generated/cert.pem
-```
-
-All nodes in the Kong cluster should share the same `keyring_enabled` and `keyring_strategy` configuration values.
-The generated private key `key.pem` is not required to configure Kong, or to start Kong. Please refer to the [disaster recovery](#disaster-recovery) section for more information on how to use private keys in keyring management.
-
-### Start Kong
-
-Once all Kong nodes in the cluster have been configured, start each node:
-
-```bash
-$ kong start
-```
-
-When encryption is enabled on a Kong node, it checks the status of the cluster keyring on boot. If it detects that no keys are present in the keyring, it will generate a key automatically. This process allows encryption/decryption operations to begin immediately.
-
-For all other nodes, the generated key will be automatically distributed within a few seconds.
-
-Note that encryption keys are held _only_ in memory, and do not persist past a restart of the Kong process (e.g., running `kong restart`). Because of this limitation, you must [recover](#recover-the-keyring) or [import](#import-the-keyring) the keyring following initialization. Otherwise, if all Kong nodes in a cluster restart simultaneously, any sensitive fields written with the keyring become unrecoverable. Key material still persists after a soft reload of Kong (i.e., `kong reload`).
-
-### Verify the Cluster Keyring
-
-With the keyring enabled and Kong started, verify the contents of the keyring:
-
-
-```bash
-$ curl -s localhost:8001/keyring | jq
-{
- "ids": [
- "LaW1urRQ"
- ],
- "active": "LaW1urRQ"
-}
-```
-
-Note that in this example, the value `LaW1urRQ` is the _ID_ of the key, not the key material itself.
-
-
-### Exercise the Encryption Routines
-
-Create a Consumer with a basic-auth credential. At this point, the `password` field of the basic-auth credential will be symmetrically encrypted before it is written to the database (in addition to being hashed by the basic-auth plugin, which is done by the plugin regardless of whether keyring encryption is enabled):
-
-```bash
-$ curl -s localhost:8001/consumers -d username=bob | jq
-{
- "custom_id": null,
- "created_at": 1576518610,
- "id": "6375b5fd-9c95-4822-b2dd-80ffbccb7ec9",
- "tags": null,
- "username": "bob",
- "type": 0
-}
-```
-
-```bash
-$ curl -s localhost:8001/consumers/bob/basic-auth -d username=bob -d password=supersecretpassword | jq
-{
- "created_at": 1576518704,
- "consumer": {
- "id": "6375b5fd-9c95-4822-b2dd-80ffbccb7ec9"
- },
- "id": "fc46ce48-c1d6-4078-9f51-5a777350a8a2",
- "password": "da61c0083b6d19ef3db2490d0da96a71572da0fa",
- "username": "bob"
-}
-```
-
-Note that the returned `password` field in the API response is not the encrypted value; database encryption does not modify responses generated by the Admin API. This allows existing workflows to continue in the same form, while providing encryption at rest security under the hood. We can verify this by examining the value stored in the database:
-
-```
-kong=# select id,password from basicauth_credentials;
- id | password
---------------------------------------+---------------------------------------------------------------------------------------------------------------------------
- fc46ce48-c1d6-4078-9f51-5a777350a8a2 | $ke$1$-LaW1urRQ-0f5b1ee8ddeefca1a1d75125-53f158a5f619133a2113692a7057e2b91fa947321de4480d452dd42c36bc9ef8aa6499cd429db6d7
-(1 row)
-```
-
-We can also verify that reading back the credential after it has been created behaves as expected:
-
-```bash
-$ curl -s localhost:8001/consumers/bob/basic-auth/fc46ce48-c1d6-4078-9f51-5a777350a8a2 | jq
-{
- "created_at": 1576518704,
- "consumer": {
- "id": "6375b5fd-9c95-4822-b2dd-80ffbccb7ec9"
- },
- "id": "fc46ce48-c1d6-4078-9f51-5a777350a8a2",
- "password": "da61c0083b6d19ef3db2490d0da96a71572da0fa",
- "username": "bob"
-}
-```
-
-### Rotating Key Material
-
-As noted above, Kong supports rotating keys by allowing for multiple keys to exist on the keyring at the same time. This allows for data fields written by one key to be read back, while a fresher encryption key is used for write operations. Rotating keys is a matter of importing or generating a new key into the keyring, and marking it as active. Arbitrary key material can be imported via the `/keyring/import` material, or Kong can generate a new key via `/keyring/generate` endpoint:
-
-```bash
-$ curl -XPOST -s localhost:8001/keyring/generate
-{
- "key": "t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44=",
- "id": "8zgITLQh"
-}
-```
-
-Note that as a convenience the raw key material is returned from this endpoint call.
-
-Once a new key is present in the keyring, activate the key's ID:
-
-```bash
-$ curl -s localhost:8001/keyring/activate -d key=8zgITLQh
-```
-
-Kong can write new sensitive data fields with the current `active` key, and read previously written fields in the database with the prior key, provided that key is in the keyring. Kong automatically selects the appropriate key to use when decrypting fields from the database.
-
-At this point, it is encouraged to take another backup of the keyring via the `/keyring/export` Admin API endpoint.
-
-### Rotating Encrypted Data Fields
-
-Once the keyring has updated, existing encrypted fields can rotate to use the new active key. To accomplish this rotation, issue a PATCH request to the entity in question:
-
-```bash
-$ # curl -XPATCH -s localhost:8001/consumers/bob/basic-auth/fc46ce48-c1d6-4078-9f51-5a777350a8a2 -d password=adifferentsecretpassword | jq
-{
- "created_at": 1576518704,
- "consumer": {
- "id": "6375b5fd-9c95-4822-b2dd-80ffbccb7ec9"
- },
- "id": "fc46ce48-c1d6-4078-9f51-5a777350a8a2",
- "password": "cc7274e94e41f3e00c238ff8712d1a83693f2a89",
- "username": "bob"
-}
-```
-
-Again, note that the encryption behavior is transparent to the Admin API response. Under the hood, Kong reads the entity's `password` field with a read-only encryption key. As part of the PATCH process, Kong writes the `password` field back to the database with the new `active` key. To verify this process, examine the raw contents of the database:
-
-```
-kong=# select id,password from basicauth_credentials;
- id | password
---------------------------------------+---------------------------------------------------------------------------------------------------------------------------
- fc46ce48-c1d6-4078-9f51-5a777350a8a2 | $ke$1$-8zgITLQh-b8d28531252241e6b95907e4-0768a9a4baaa2c777d9406d4e3098d813be55ae82c4c849182b06b9c5954704c6290c9e677bcd693
-(1 row)
-```
-
-Note that the key identifier within the password data blob has been updated. This rotation mechanism allows organizations to meet specific compliance needs around key management rotation and retention policies.
-
-Currently, encrypted fields must undergo a direct write operation in order to rotate the encrypted field. Future releases of Kong may contain helper API operations to automate this process.
-
-### Exploring Missing Keyring Material Behavior
-
-As a test, stop all Kong nodes in the cluster, and restart one Kong node again, but do not import the keyring material. The behavior of attempting to read an entity with an encrypted field now changes:
-
-```bash
-$ time curl -s localhost:8001/consumers/bob/basic-auth/fc46ce48-c1d6-4078-9f51-5a777350a8a2
-{"message":"An unexpected error occurred"}
-real 0m24.811s
-user 0m0.017s
-sys 0m0.006s
-```
-
-When the Kong node restarts, it sends a broadcast request for the keyring, but as no other nodes are present in the cluster (or no other nodes had the keyring available), Kong is unable to decrypt the `password` field on the credential. Because Kong has an eventually-consistent clustering model, it makes several attempts to request the keyring and allows for delays in hearing responses from another cluster node; thus, the request takes several seconds to complete before finally failing.
-
-## Disaster Recovery
-
-`cluster` strategy supports two disaster recovery strategies.
-
-### Automatic backup and manual recovery
-To use automatic backups for keyring materials, configure `keyring_recovery_public_key`:
-
-```
-keyring_recovery_public_key = /path/to/generated/cert.pem
-```
-
-Or via environmental variables:
-
-```
-export KONG_KEYRING_RECOVERY_PUBLIC_KEY=/path/to/generated/cert.pem
-```
-
-#### Recover the Keyring
-
-The keyring material is then encrypted with the public RSA key defined with the `keyring_recovery_public_key`
-Kong configuration value in the database. The corresponding private key can be used to decrypt the keyring material in the database:
-
-```bash
-$ curl -X POST localhost:8001/keyring/recover -F recovery_private_key=@/path/to/generated/key.pem
-{
- "message": "successfully recovered 1 keys",
- "recovered": [
- "RfsDJ2Ol"
- ],
- "not_recovered": [
- "xSD219lH"
- ]
-}
-```
-
-The response contains a list of keys that were successfully recovered and that could not be recovered. The Kong error log will contain the detailed reason why the keys could not be recovered.
-
-### Manual export and manual import
-
-**Use of this method is deprecated in Kong 3.0 and will be removed in a future release.**
-
-```
-keyring_public_key = /path/to/generated/cert.pem
-keyring_private_key = /path/to/generated/key.pem
-```
-
-Or via environmental variables:
-
-```
-export KONG_KEYRING_PUBLIC_KEY=/path/to/generated/cert.pem
-export KONG_KEYRING_PRIVATE_KEY=/path/to/generated/key.pem
-```
-
-Not every node needs to be provided the management RSA key pair, as that key pair is only used for backup and recovery processes. It does not need to be present for regular database read/write operations.
-
-The user that the Kong worker process is running under must have read access to the public and private keys in order to be able to import and export keyrings. This user is defined with the `nginx_user` Kong configuration option. We recommend restricting access to these files, for example:
-
-```bash
-$ chown : /path/to/generated/cert.pem /path/to/generated/key.pem
-$ chmod 400 /path/to/generated/cert.pem /path/to/generated/key.pem
-```
-
-When testing, you can set `keyring_blob_path` in kong.conf or `KONG_KEYRING_BLOB_PATH`
-using environmental variables to specify a path to dump known keys. The dumped keys are
-encrypted with the public RSA key defined in the `keyring_public_key` Kong configuration
-value, and are automatically loaded when Kong starts.
-
-#### Export the Keyring
-
-Export the keyring. The exported material can be re-imported to the cluster in the event of an outage or to restore a previously-deleted key:
-
-```bash
-$ curl -XPOST -s localhost:8001/keyring/export | jq
-{
- "data": "eyJrIjoiV1JZeTdubDlYeFZpR3VVQWtWTXBcL0JiVW1jMWZrWHluc0dKd3N4M1c0MlIxWE5XM05lZ05sdFdIVmJ1d0ZnaVZSTnFSdmM1WERscGY3b0NIZ1ZDQ3JvTFJ4czFnRURhOXpJT0tVV0prM2lhd0VLMHpKTXdwRDd5ZjV2VFYzQTY0Y2UxcVl1emJoSTI4VUZ1ZExRZWljVjd2T3BYblVvU3dOY3IzblhJQWhyWlcxc1grWXE3aHM1RzhLRXY2OWlRamJBTXAwbHZmTWNFWWxTOW9NUjdnSm5xZWlST0J1Q09iMm5tSXg0Qk1uaTJGalZzQzBtd2R2dmJyYWxYa3VLYXhpRWZvQm9EODk3MEtVcDYzY05lWGdJclpjang4YmJDV1lDRHlEVmExdGt5c0g1TjBJM0hTNDRQK1dyT2JkcElCUk5vSVZVNis1QWdcLzdZM290RUdzN1E9PSIsImQiOiIxWEZJOXZKQ05CTW5uVTB5c0hQenVjSG5nc2c5UURxQmcxZ3g1VVYxNWNlOEVTTlZXTmthYm8zdlUzS2VRTURcL0RUYXdzZCtJWHB5SllBTkRtanZNcytqU2lrVTFiRkpyMEVcLzBSRlg2emJrT0oybTR2bXlxdVE9PSIsIm4iOiJUUmRLK01Qajh6MkdHTmtyIn0="
-}
-
-```
-
-The response generated is an opaque blob containing the keyring. This blob is encrypted with
-a randomly-generated symmetric key, which is encrypted with the public
-RSA key defined via the `keyring_public_key` Kong configuration value.
-
-The exported keyring should be stored in a safe location for disaster recovery
-purposes. It is not designed to be modified or decrypted before being used during
-a disaster recovery process.
-
-#### Import the Keyring
-
-Restart Kong and re-import the previously exported keyring:
-
-```bash
-$ kong restart
-```
-
-```bash
-$ curl localhost:8001/keyring/import -d data=
-```
-
-This operation requires that the `keyring_private_key` point to the private RSA
-key associated with the public key used during the initial keyring export. Once
-this is complete, Admin API operations that require the keyring for encryption/
-decryption can be verified:
-
-```bash
-$ curl -s localhost:8001/consumers/bob/basic-auth/fc46ce48-c1d6-4078-9f51-5a777350a8a2 | jq
-{
- "created_at": 1576518704,
- "consumer": {
- "id": "6375b5fd-9c95-4822-b2dd-80ffbccb7ec9"
- },
- "id": "fc46ce48-c1d6-4078-9f51-5a777350a8a2",
- "password": "da61c0083b6d19ef3db2490d0da96a71572da0fa",
- "username": "bob"
-}
-```
-
-
-## Implementation Details
-
-### Encryption/Decryption
-
-{{site.base_gateway}} uses 256-bit AES encryption in GCM mode. Cryptographic nonce values for each encryption routine execution are derived from the kernel CSPRNG (`/dev/urandom`). The AES routines used by Kong are provided by the OpenSSL library bundled with the {{site.base_gateway}} package.
-
-### Key Generation and Lifecycle
-
-{{site.base_gateway}}'s keyring handling mechanisms allow for more than one key to be present on any given Kong node at a time. Each key may be used to read encrypted fields from the database, but one and only one key at any given time is used to write encrypted fields back to the data store. This process allows for a key rotation mechanism wherein new keyring material is introduced, and older keys may be present for a time to allow rotating previously-encrypted fields.
-
-Through the kernel CSPRNG, Kong derives keyring material generated through the `/keyring/generate` Admin API endpoint. Kong stores keyring material in a shared memory zone that all Kong worker processes access. To prevent key material from being written to disk as part of memory paging operations, we recommend that swap be disabled on systems running Kong
-
-When operating in `cluster` mode, keyring material propagates automatically among all nodes in the Kong cluster. Because Kong nodes do not have a notion of direct peer-to-peer communication, the underlying datastore serves as a communication channel to transmit messages. When a Kong node starts, it generates an ephemeral RSA key pair. The node's public keys propagate to all other active nodes in the cluster. When an active node sees a message request for keyring material, it wraps the in-memory keyring material in the presented public key, and transmits the payload back over the central messaging channel provided by the underlying data store. This process allows each node in the cluster to broadcast keyring material to new nodes, without sending key material in plaintext over the wire. This model requires that at least one node be running at all times within the cluster; a failure of all nodes requires manually re-importing the keyring to one node during an outage recovery.
-
-### Encrypted Fields
-
-The keyring module encrypts the following fields at rest:
-
-* `key` fields of `certificate` objects (corresponding to the private key of a TLS certificate).
-* Certain configuration parameters in plugins and plugin-related authentication
-objects. For information on which plugin fields are encrypted, see
-[each individual plugin's documentation](/hub/).
-
-## Vault Integration
-
-Kong's keyring mechanism can integrate directly with [HashiCorp Vault](https://www.vaultproject.io/) for keyring storage and versioning. In this model, Kong nodes read keyring material directly from a Vault KV secrets engine, rather than generating and disseminating keyring material around the cluster.
-
-To configure Kong to use Vault for keyring storage, set the `keyring_strategy` configuration value to `vault`. Leveraging Vault also requires defining a host, mount point, and token for Vault access. See the Kong configuration reference for more details.
-
-### Key Format
-
-Kong leverages version 2 of the [Vault KV secrets engine](https://www.vaultproject.io/docs/secrets/kv/kv-v2.html). This process allows for the same versioning and key rotation mechanisms that the `cluster` keyring strategy provides. Each version of a KV secrets entry must contain both an `id` field, and a `key` field, e.g.:
-
-```json
-{
- "key": "t6NWgbj3g9cbNVC3/D6oZ2Md1Br5gWtRrqb1T2FZy44=",
- "id": "8zgITLQh"
-}
-```
-
-To provide consistent consumption of all Vault KV secrets, the underlying symmetric key is derived as the SHA256 of the `key` component of the secret value. Take note of this derivation when extending or re-using symmetric encryption keys from other systems. This derivation also implies that the `key` field can contain any arbitrary data, as Kong hashes the contents before importing the material into the keyring.
-
-To provide a new key, add a new version to the Vault secrets engine at the configured path. The `current_version` of the Vault secret denotes the active key in the keyring. See the [KV v2 documentation](https://www.vaultproject.io/docs/secrets/kv/kv-v2.html) for more detail.
-
-### Vault Permissions
-
-In order to communicate with Vault, Kong must be provided a Vault token for access. The token must be associated with a policy that allows the `read` and `list` actions on the path where keyring secrets are stored. Kong does not write keyring material to the Vault cluster.
-
-### Syncing the Keyring
-
-Kong reads the keyring material from Vault when the Kong process starts. Any changes to the Vault KV store are not reflected on the Kong node until Kong syncs with Vault via the `/keyring/vault/sync` Admin API endpoint. This allows Kong to receive a Vault token with a low TTL, as the list and read operation only occur once.
-
-### Keyring on hybrid mode
-
-Because Keyring encrypts the data in the database, it means it doesn't encrypt data on Kong data plane nodes that run without a database and get data from the control plane. However, one can turn on `declarative_config_encryption_mode` within the Kong configuration, or use secrets management to securely store sensitive data on the data plane nodes.
diff --git a/src/gateway/plugin-development/plugin-configuration.md b/src/gateway/plugin-development/configuration.md
similarity index 100%
rename from src/gateway/plugin-development/plugin-configuration.md
rename to src/gateway/plugin-development/configuration.md
diff --git a/src/gateway/plugin-development/other/external-plugins.md b/src/gateway/plugin-development/pluginserver/external-plugins.md
similarity index 100%
rename from src/gateway/plugin-development/other/external-plugins.md
rename to src/gateway/plugin-development/pluginserver/external-plugins.md
diff --git a/src/gateway/plugin-development/other/go.md b/src/gateway/plugin-development/pluginserver/go.md
similarity index 100%
rename from src/gateway/plugin-development/other/go.md
rename to src/gateway/plugin-development/pluginserver/go.md
diff --git a/src/gateway/plugin-development/other/javascript.md b/src/gateway/plugin-development/pluginserver/javascript.md
similarity index 100%
rename from src/gateway/plugin-development/other/javascript.md
rename to src/gateway/plugin-development/pluginserver/javascript.md
diff --git a/src/gateway/plugin-development/other/plugins-kubernetes.md b/src/gateway/plugin-development/pluginserver/plugins-kubernetes.md
similarity index 100%
rename from src/gateway/plugin-development/other/plugins-kubernetes.md
rename to src/gateway/plugin-development/pluginserver/plugins-kubernetes.md
diff --git a/src/gateway/plugin-development/other/python.md b/src/gateway/plugin-development/pluginserver/python.md
similarity index 100%
rename from src/gateway/plugin-development/other/python.md
rename to src/gateway/plugin-development/pluginserver/python.md
diff --git a/src/gateway/admin-api/rbac/examples.md b/src/gateway/production-deployment/access-control/enable-rbac.md
similarity index 98%
rename from src/gateway/admin-api/rbac/examples.md
rename to src/gateway/production-deployment/access-control/enable-rbac.md
index 4b4c14225d21..d214a9cbbd28 100644
--- a/src/gateway/admin-api/rbac/examples.md
+++ b/src/gateway/production-deployment/access-control/enable-rbac.md
@@ -7,9 +7,7 @@ This chapter aims to provide a step-by-step tutorial on how to set up
RBAC and see it in action, with an end-to-end use case. The chosen
use case demonstrates how **RBAC with workspaces** can be coupled
to achieve a flexible organization of teams and users in complex
-hierarchies. Make sure to read the [RBAC Overview][rbac-overview] page
-and to glance over the [RBAC Admin API][rbac-admin] chapter, keeping it
-open as a reference.
+hierarchies.
## Use Case
@@ -18,7 +16,7 @@ cluster to be shared with 3 teams: teamA, teamB, and teamC. While the Kong
cluster are shared among these teams, they want to be able to segment
their entities in such a way that management of entities in one team doesn't
disrupt operation in some other team. As shown in the
-[Workspaces Examples Page][workspaces-examples], such a use case is possible
+[Workspaces Page][workspaces-examples], such a use case is possible
with workspaces. On top of workspaces, though, each team wants to enforce
access control over their Workspace, which is possible with RBAC. **To sum up,
Workspaces and RBAC are complementary: Workspaces provide segmentation of
@@ -1040,7 +1038,5 @@ he created.
---
-[rbac-overview]: /gateway/{{page.kong_version}}/configure/auth/rbac
-[rbac-admin]: /gateway/{{page.kong_version}}/admin-api/rbac/reference
-[workspaces-examples]: /gateway/{{page.kong_version}}/admin-api/workspaces/examples
+[workspaces-examples]: /gateway/{{page.kong_version}}/kong-enterprise/workspaces
[getting-started-guide]: /gateway/{{page.kong_version}}/get-started/comprehensive
diff --git a/src/gateway/admin-api/admins/examples.md b/src/gateway/production-deployment/access-control/register-admin-api.md
similarity index 100%
rename from src/gateway/admin-api/admins/examples.md
rename to src/gateway/production-deployment/access-control/register-admin-api.md
diff --git a/src/gateway/kong-production/running-kong/start-kong-securely.md b/src/gateway/production-deployment/access-control/start-securely.md
similarity index 100%
rename from src/gateway/kong-production/running-kong/start-kong-securely.md
rename to src/gateway/production-deployment/access-control/start-securely.md
diff --git a/src/gateway/kong-production/blue-green.md b/src/gateway/production-deployment/blue-green.md
similarity index 100%
rename from src/gateway/kong-production/blue-green.md
rename to src/gateway/production-deployment/blue-green.md
diff --git a/src/gateway/kong-production/canary.md b/src/gateway/production-deployment/canary.md
similarity index 100%
rename from src/gateway/kong-production/canary.md
rename to src/gateway/production-deployment/canary.md
diff --git a/src/gateway/production-deployment/clustering.md b/src/gateway/production-deployment/clustering.md
new file mode 100644
index 000000000000..2ffa8455a833
--- /dev/null
+++ b/src/gateway/production-deployment/clustering.md
@@ -0,0 +1,293 @@
+---
+title: Clustering Reference
+---
+
+A Kong cluster allows you to scale the system horizontally by adding more
+machines to handle more incoming requests. They will all share the same
+configuration since they point to the same database. Kong nodes pointing to the
+**same datastore** will be part of the same Kong cluster.
+
+You need a load balancer in front of your Kong cluster to distribute traffic
+across your available nodes.
+
+## What a Kong cluster does and doesn't do
+
+**Having a Kong cluster does not mean that your clients traffic will be
+load-balanced across your Kong nodes out of the box.** You still need a
+load-balancer in front of your Kong nodes to distribute your traffic. Instead,
+a Kong cluster means that those nodes will share the same configuration.
+
+For performance reasons, Kong avoids database connections when proxying
+requests, and caches the contents of your database in memory. The cached
+entities include Services, Routes, Consumers, Plugins, Credentials, and so on. Since those
+values are in memory, any change made via the Admin API of one of the nodes
+needs to be propagated to the other nodes.
+
+This document describes how those cached entities are being invalidated and how
+to configure your Kong nodes for your use case, which lies somewhere between
+performance and consistency.
+
+## Single node Kong clusters
+
+
+{% include_cached /md/enterprise/cassandra-deprecation.md %}
+
+
+A single Kong node connected to a database (Cassandra or PostgreSQL) creates a
+Kong cluster of one node. Any changes applied via the Admin API of this node
+will instantly take effect. Example:
+
+Consider a single Kong node `A`. If we delete a previously registered Service:
+
+```bash
+$ curl -X DELETE http://127.0.0.1:8001/services/test-service
+```
+
+Then any subsequent request to `A` would instantly return `404 Not Found`, as
+the node purged it from its local cache:
+
+```bash
+$ curl -i http://127.0.0.1:8000/test-service
+```
+
+## Multiple nodes Kong clusters
+
+In a cluster of multiple Kong nodes, other nodes connected to the same database
+would not instantly be notified that the Service was deleted by node `A`. While
+the Service is **not** in the database anymore (it was deleted by node `A`), it is
+**still** in node `B`'s memory.
+
+All nodes perform a periodic background job to synchronize with changes that
+may have been triggered by other nodes. The frequency of this job can be
+configured via:
+
+* [db_update_frequency][db_update_frequency] (default: 5 seconds)
+
+Every `db_update_frequency` seconds, all running Kong nodes will poll the
+database for any update, and will purge the relevant entities from their cache
+if necessary.
+
+If we delete a Service from node `A`, this change will not be effective in node
+`B` until node `B`s next database poll, which will occur up to
+`db_update_frequency` seconds later (though it could happen sooner).
+
+This makes Kong clusters **eventually consistent**.
+
+### Use read-only replicas when deploying Kong clusters with Postgres
+
+When using Postgres as the backend storage, you can optionally enable
+Kong to serve read queries from a separate database instance.
+
+Enabling the read-only connection support in Kong
+greatly reduces the load on the main database instance since read-only
+queries are no longer sent to it.
+
+To learn more about how to configure this feature, refer to the
+[Datastore section](/gateway/{{page.kong_version}}/reference/configuration/#datastore-section)
+of the Configuration reference.
+
+## What is being cached?
+
+All of the core entities such as Services, Routes, Plugins, Consumers, Credentials are
+cached in memory by Kong and depend on their invalidation via the polling
+mechanism to be updated.
+
+Additionally, Kong also caches **database misses**. This means that if you
+configure a Service with no plugin, Kong will cache this information. Example:
+
+On node `A`, we add a Service and a Route:
+
+```bash
+# node A
+$ curl -X POST http://127.0.0.1:8001/services \
+ --data "name=example-service" \
+ --data "url=http://example.com"
+
+$ curl -X POST http://127.0.0.1:8001/services/example-service/routes \
+ --data "paths[]=/example"
+```
+
+(Note that we used `/services/example-service/routes` as a shortcut: we
+could have used the `/routes` endpoint instead, but then we would need to
+pass `service_id` as an argument, with the UUID of the new Service.)
+
+A request to the Proxy port of both node `A` and `B` will cache this Service, and
+the fact that no plugin is configured on it:
+
+```bash
+# node A
+$ curl http://127.0.0.1:8000/example
+HTTP 200 OK
+...
+```
+
+```bash
+# node B
+$ curl http://127.0.0.2:8000/example
+HTTP 200 OK
+...
+```
+
+Now, say we add a plugin to this Service via node `A`'s Admin API:
+
+```bash
+# node A
+$ curl -X POST http://127.0.0.1:8001/services/example-service/plugins \
+ --data "name=example-plugin"
+```
+
+Because this request was issued via node `A`'s Admin API, node `A` will locally
+invalidate its cache and on subsequent requests, it will detect that this API
+has a plugin configured.
+
+However, node `B` hasn't run a database poll yet, and still caches that this
+API has no plugin to run. It will be so until node `B` runs its database
+polling job.
+
+**Conclusion**: All CRUD operations trigger cache invalidations. Creation
+(`POST`, `PUT`) will invalidate cached database misses, and update/deletion
+(`PATCH`, `DELETE`) will invalidate cached database hits.
+
+## How to configure database caching?
+
+You can configure three properties in the Kong configuration file, the most
+important one being `db_update_frequency`, which determine where your Kong
+nodes stand on the performance versus consistency trade-off.
+
+Kong comes with default values tuned for consistency so that you can
+experiment with its clustering capabilities while avoiding surprises. As you
+prepare a production setup, you should consider tuning those values to ensure
+that your performance constraints are respected.
+
+### 1. [db_update_frequency][db_update_frequency] (default: 5s)
+
+This value determines the frequency at which your Kong nodes will be polling
+the database for invalidation events. A lower value means that the polling
+job will execute more frequently, but that your Kong nodes will keep up
+with changes you apply. A higher value means that your Kong nodes will
+spend less time running the polling jobs, and will focus on proxying your
+traffic.
+
+**Note**: Changes propagate through the cluster in up to `db_update_frequency`
+seconds.
+
+### 2. [db_update_propagation][db_update_propagation] (default: 0s)
+
+If your database itself is eventually consistent (that is, Cassandra), you **must**
+configure this value. It is to ensure that the change has time to propagate
+across your database nodes. When set, Kong nodes receiving invalidation events
+from their polling jobs will delay the purging of their cache for
+`db_update_propagation` seconds.
+
+If a Kong node connected to an eventually consistent database was not delaying
+the event handling, it could purge its cache, only to cache the non-updated
+value again (because the change hasn't propagated through the database yet)!
+
+You should set this value to an estimate of the amount of time your database
+cluster takes to propagate changes.
+
+**Note**: When this value is set, changes propagate through the cluster in
+up to `db_update_frequency + db_update_propagation` seconds.
+
+### 3. [db_cache_ttl][db_cache_ttl] (default: 0s)
+
+The time (in seconds) for which Kong will cache database entities (both hits
+and misses). This Time-To-Live value acts as a safeguard in case a Kong node
+misses an invalidation event, to avoid it from running on stale data for too
+long. When the TTL is reached, the value will be purged from its cache, and the
+next database result will be cached again.
+
+By default, no data is invalidated based on this TTL (the default value is `0`).
+This is usually fine: Kong nodes rely on invalidation events, which are handled
+at the db store level (Cassandra/PostgreSQL). If you are concerned that a Kong
+node might miss invalidation event for any reason, you should set a TTL. Otherwise
+the node might run with a stale value in its cache for an undefined amount of time
+until the cache is manually purged, or the node is restarted.
+
+### 4. When using Cassandra
+
+If you use Cassandra as your Kong database, you **must** set
+[db_update_propagation][db_update_propagation] to a non-zero value. Since
+Cassandra is eventually consistent by nature, this will ensure that Kong nodes
+do not prematurely invalidate their cache, only to fetch and catch a
+not up-to-date entity again. Kong will present you a warning in logs if you did
+not configure this value when using Cassandra.
+
+Additionally, you might want to configure `cassandra_consistency` to a value
+like `QUORUM` or `LOCAL_QUORUM`, to ensure that values being cached by your
+Kong nodes are up-to-date values from your database.
+
+Setting the `cassandra_refresh_frequency` option to `0` is not advised, as a Kong
+restart will be required to discover any changes to the Cassandra cluster topology.
+
+## Interacting with the cache via the Admin API
+
+If for some reason, you want to investigate the cached values, or manually
+invalidate a value cached by Kong (a cached hit or miss), you can do so via the
+Admin API `/cache` endpoint.
+
+### Inspect a cached value
+
+**Endpoint**
+
+/cache/{cache_key}
+
+**Response**
+
+If a value with that key is cached:
+
+```
+HTTP 200 OK
+...
+{
+ ...
+}
+```
+
+Else:
+
+```
+HTTP 404 Not Found
+```
+
+**Note**: Retrieving the `cache_key` for each entity being cached by Kong is
+currently an undocumented process. Future versions of the Admin API will make
+this process easier.
+
+### Purge a cached value
+
+**Endpoint**
+
+/cache/{cache_key}
+
+**Response**
+
+```
+HTTP 204 No Content
+...
+```
+
+**Note**: Retrieving the `cache_key` for each entity being cached by Kong is
+currently an undocumented process. Future versions of the Admin API will make
+this process easier.
+
+### Purge a node's cache
+
+**Endpoint**
+
+/cache
+
+**Response**
+
+```
+HTTP 204 No Content
+```
+
+**Note**: Be wary of using this endpoint on a node running in production with warm cache.
+If the node is receiving a lot of traffic, purging its cache at the same time
+will trigger many requests to your database, and could cause a
+[dog-pile effect](https://en.wikipedia.org/wiki/Cache_stampede).
+
+[db_update_frequency]: /gateway/{{page.kong_version}}/reference/configuration/#db_update_frequency
+[db_update_propagation]: /gateway/{{page.kong_version}}/reference/configuration/#db_update_propagation
+[db_cache_ttl]: /gateway/{{page.kong_version}}/reference/configuration/#db_cache_ttl
diff --git a/src/gateway/kong-production/deployment-topologies/db-less-and-declarative-config.md b/src/gateway/production-deployment/deployment-topologies/db-less-and-declarative-config.md
similarity index 100%
rename from src/gateway/kong-production/deployment-topologies/db-less-and-declarative-config.md
rename to src/gateway/production-deployment/deployment-topologies/db-less-and-declarative-config.md
diff --git a/src/gateway/kong-production/deployment-topologies/hybrid-mode/index.md b/src/gateway/production-deployment/deployment-topologies/hybrid-mode/index.md
similarity index 100%
rename from src/gateway/kong-production/deployment-topologies/hybrid-mode/index.md
rename to src/gateway/production-deployment/deployment-topologies/hybrid-mode/index.md
diff --git a/src/gateway/production-deployment/deployment-topologies/hybrid-mode/setup.md b/src/gateway/production-deployment/deployment-topologies/hybrid-mode/setup.md
new file mode 100644
index 000000000000..75386d9de580
--- /dev/null
+++ b/src/gateway/production-deployment/deployment-topologies/hybrid-mode/setup.md
@@ -0,0 +1,677 @@
+---
+title: Deploy Kong Gateway in Hybrid Mode
+---
+
+## Prerequisites
+
+To get started with a hybrid mode deployment, first install an instance of
+{{site.base_gateway}} with TLS to be your control plane (CP) node. See the
+[installation documentation](/gateway/{{page.kong_version}}/install-and-run/)
+for details.
+
+We will bring up any subsequent data plane (DP) instances in this topic.
+
+{:.note}
+> **Note:** For a hybrid mode deployment on Kubernetes, see [hybrid mode](https://github.com/Kong/charts/blob/main/charts/kong/README.md#hybrid-mode)
+in the `kong/charts` repository.
+
+## Generate a certificate/key pair
+
+In hybrid mode, a mutual TLS handshake (mTLS) is used for authentication so the
+actual private key is never transferred on the network, and communication
+between CP and DP nodes is secure.
+
+Before using hybrid mode, you need a certificate/key pair.
+{{site.base_gateway}} provides two modes for handling certificate/key pairs:
+
+* **Shared mode:** (Default) Use the Kong CLI to generate a certificate/key
+pair, then distribute copies across nodes. The certificate/key pair is shared
+by both CP and DP nodes.
+* **PKI mode:** Provide certificates signed by a central certificate authority
+(CA). Kong validates both sides by checking if they are from the same CA. This
+eliminates the risks associated with transporting private keys.
+
+{:.warning}
+> **Warning:** If you have a TLS-aware proxy between the DP and CP nodes, you
+must use PKI mode and set `cluster_server_name` to the CP hostname in
+`kong.conf`. Do not use shared mode, as it uses a non-standard value for TLS server name
+indication, and this will confuse TLS-aware proxies that rely on SNI to route
+traffic.
+
+For a breakdown of the properties used by these modes, see the
+[configuration reference](#configuration-reference).
+
+{% navtabs %}
+{% navtab Shared mode %}
+{:.warning}
+ > **Warning:** Protect the Private Key. Ensure the private key file can only be accessed by
+ Kong nodes belonging to the cluster. If the key is compromised, you must
+ regenerate and replace certificates and keys on all CP and DP nodes.
+
+1. On an existing {{site.base_gateway}} instance, create a certificate/key pair:
+ ```bash
+ kong hybrid gen_cert
+ ```
+ This will generate `cluster.crt` and `cluster.key` files and save them to
+ the current directory. By default, the certificate/key pair is valid for three
+ years, but can be adjusted with the `--days` option. See `kong hybrid --help`
+ for more usage information.
+
+2. Copy the `cluster.crt` and `cluster.key` files to the same directory
+on all Kong CP and DP nodes; e.g., `/cluster/cluster`.
+ Set appropriate permissions on the key file so it can only be read by Kong.
+
+{% endnavtab %}
+{% navtab PKI mode %}
+
+With PKI mode, the Hybrid cluster can use certificates signed by a central
+certificate authority (CA).
+
+In this mode, the control plane and data plane don't need to use the same
+`cluster_cert` and `cluster_cert_key`. Instead, Kong validates both sides by
+checking if they are from the same CA.
+
+Prepare your CA certificates on the hosts where Kong will be running.
+
+{% navtabs %}
+{% navtab CA Certificate Example %}
+Typically, a CA certificate will look like this:
+
+```
+Certificate:
+ Data:
+ Version: 3 (0x2)
+ Serial Number:
+ 5d:29:73:bf:c3:da:5f:60:69:da:73:ed:0e:2e:97:6f:7f:4c:db:4b
+ Signature Algorithm: ecdsa-with-SHA256
+ Issuer: O = Kong Inc., CN = Hybrid Root CA
+ Validity
+ Not Before: Jul 7 12:36:10 2020 GMT
+ Not After : Jul 7 12:36:40 2023 GMT
+ Subject: O = Kong Inc., CN = Hybrid Root CA
+ Subject Public Key Info:
+ Public Key Algorithm: id-ecPublicKey
+ Public-Key: (256 bit)
+ pub:
+ 04:df:49:9f:39:e6:2c:52:9f:46:7a:df:ae:7b:9b:
+ 87:1e:76:bb:2e:1d:9c:61:77:07:e5:8a:ba:34:53:
+ 3a:27:4c:1e:76:23:b4:a2:08:80:b4:1f:18:7a:0b:
+ 79:de:ea:8c:23:94:e6:2f:57:cf:27:b4:0a:52:59:
+ 90:2c:2b:86:03
+ ASN1 OID: prime256v1
+ NIST CURVE: P-256
+ X509v3 extensions:
+ X509v3 Key Usage: critical
+ Certificate Sign, CRL Sign
+ X509v3 Basic Constraints: critical
+ CA:TRUE
+ X509v3 Subject Key Identifier:
+ 8A:0F:07:61:1A:0F:F4:B4:5D:B7:F3:B7:28:D1:C5:4B:81:A2:B9:25
+ X509v3 Authority Key Identifier:
+ keyid:8A:0F:07:61:1A:0F:F4:B4:5D:B7:F3:B7:28:D1:C5:4B:81:A2:B9:25
+
+ Signature Algorithm: ecdsa-with-SHA256
+ 30:45:02:20:68:3c:d1:f3:63:a2:aa:b4:59:c9:52:af:33:b7:
+ 3f:ca:3a:2b:1c:9d:87:0c:c0:47:ff:a2:c4:af:3e:b0:36:29:
+ 02:21:00:86:ce:d0:fc:ba:92:e9:59:16:1c:c3:b2:11:11:ed:
+ 01:5d:16:49:d0:f9:0c:1d:35:0d:40:ba:19:98:31:76:57
+```
+{% endnavtab %}
+
+{% navtab CA Certificate on CP %}
+Here is an example of a CA certificate on a control plane:
+
+```
+Certificate:
+ Data:
+ Version: 3 (0x2)
+ Serial Number:
+ 18:cc:a3:6b:aa:77:0a:69:c6:d5:ff:12:be:be:c0:ac:5c:ff:f1:1e
+ Signature Algorithm: ecdsa-with-SHA256
+ Issuer: CN = Hybrid Intermediate CA
+ Validity
+ Not Before: Jul 31 00:59:29 2020 GMT
+ Not After : Oct 29 00:59:59 2020 GMT
+ Subject: CN = control-plane.kong.yourcorp.tld
+ Subject Public Key Info:
+ Public Key Algorithm: id-ecPublicKey
+ Public-Key: (256 bit)
+ pub:
+ 04:f8:3a:a9:d2:e2:79:19:19:f3:1c:58:a0:23:60:
+ 78:04:1f:7e:e2:bb:60:d2:29:50:ad:7c:9b:8e:22:
+ 1c:54:c2:ce:68:b8:6c:8a:f6:92:9d:0c:ce:08:d3:
+ aa:0c:20:67:41:32:18:63:c9:dd:50:31:60:d6:8b:
+ 8d:f9:7b:b5:37
+ ASN1 OID: prime256v1
+ NIST CURVE: P-256
+ X509v3 extensions:
+ X509v3 Key Usage: critical
+ Digital Signature, Key Encipherment, Key Agreement
+ X509v3 Extended Key Usage:
+ TLS Web Server Authentication
+ X509v3 Subject Key Identifier:
+ 70:C7:F0:3B:CD:EB:8D:1B:FF:6A:7C:E0:A4:F0:C6:4C:4A:19:B8:7F
+ X509v3 Authority Key Identifier:
+ keyid:16:0D:CF:92:3B:31:B0:61:E5:AB:EE:91:42:B9:60:56:0A:88:92:82
+
+ X509v3 Subject Alternative Name:
+ DNS:control-plane.kong.yourcorp.tld, DNS:alternate-control-plane.kong.yourcorp.tld
+ X509v3 CRL Distribution Points:
+
+ Full Name:
+ URI:https://crl-service.yourcorp.tld/v1/pki/crl
+
+ Signature Algorithm: ecdsa-with-SHA256
+ 30:44:02:20:5d:dd:ec:a8:4f:e7:5b:7d:2f:3f:ec:b5:40:d7:
+ de:5e:96:e1:db:b7:73:d6:84:2e:be:89:93:77:f1:05:07:f3:
+ 02:20:16:56:d9:90:06:cf:98:07:87:33:dc:ef:f4:cc:6b:d1:
+ 19:8f:64:ee:82:a6:e8:e6:de:57:a7:24:82:72:82:49
+```
+{% endnavtab %}
+
+{% navtab CA Certificate on DP %}
+Here is an example of a CA certificate on a data plane:
+
+```
+Certificate:
+ Data:
+ Version: 3 (0x2)
+ Serial Number:
+ 4d:8b:eb:89:a2:ed:b5:29:80:94:31:e4:94:86:ce:4f:98:5a:ad:a0
+ Signature Algorithm: ecdsa-with-SHA256
+ Issuer: CN = Hybrid Intermediate CA
+ Validity
+ Not Before: Jul 31 00:57:01 2020 GMT
+ Not After : Oct 29 00:57:31 2020 GMT
+ Subject: CN = kong-dp-ce39edecp.service
+ Subject Public Key Info:
+ Public Key Algorithm: id-ecPublicKey
+ Public-Key: (256 bit)
+ pub:
+ 04:19:51:80:4c:6d:8c:a8:05:63:42:71:a2:9a:23:
+ 34:34:92:c6:2a:d3:e5:15:6e:36:44:85:64:0a:4c:
+ 12:16:82:3f:b7:4c:e1:a1:5a:49:5d:4c:5e:af:3c:
+ c1:37:e7:91:e2:b5:52:41:a0:51:ac:13:7b:cc:69:
+ 93:82:9b:2f:e2
+ ASN1 OID: prime256v1
+ NIST CURVE: P-256
+ X509v3 extensions:
+ X509v3 Key Usage: critical
+ Digital Signature, Key Encipherment, Key Agreement
+ X509v3 Extended Key Usage:
+ TLS Web Client Authentication
+ X509v3 Subject Key Identifier:
+ 25:82:8C:93:85:35:C3:D6:34:CF:CB:7B:D6:14:97:46:84:B9:2B:87
+ X509v3 Authority Key Identifier:
+ keyid:16:0D:CF:92:3B:31:B0:61:E5:AB:EE:91:42:B9:60:56:0A:88:92:82
+ X509v3 CRL Distribution Points:
+
+ Full Name:
+ URI:https://crl-service.yourcorp.tld/v1/pki/crl
+
+ Signature Algorithm: ecdsa-with-SHA256
+ 30:44:02:20:65:2f:5e:30:f7:a4:28:14:88:53:58:c5:85:24:
+ 35:50:25:c9:fe:db:2f:72:9f:ad:7d:a0:67:67:36:32:2b:d2:
+ 02:20:2a:27:7d:eb:75:a6:ee:65:8b:f1:66:a4:99:32:56:7c:
+ ad:ca:3a:d5:50:8f:cf:aa:6d:c2:1c:af:a4:ca:75:e8
+```
+{% endnavtab %}
+{% endnavtabs %}
+
+> **Note:** Certificates on CP and DP must contain the `TLS Web Server Authentication` and
+`TLS Web Client Authentication` as X509v3 Extended Key Usage extension, respectively.
+
+Kong doesn't validate the CommonName (CN) in the DP certificate; it can take an arbitrary value.
+
+{% endnavtab %}
+{% endnavtabs %}
+
+## Set up the control plane
+Next, give the control plane node the `control_plane` role, and set
+certificate/key parameters to point at the location of your certificates and
+keys.
+
+{% navtabs %}
+{% navtab Using Docker %}
+
+1. In your Docker container, set the following environment variables:
+
+ For `shared` certificate mode, use:
+ ```bash
+ KONG_ROLE=control_plane
+ KONG_CLUSTER_CERT=//cluster.crt
+ KONG_CLUSTER_CERT_KEY=//cluster.key
+ ```
+
+ For `pki` certificate mode, use:
+ ```bash
+ KONG_ROLE=control_plane
+ KONG_CLUSTER_MTLS=pki
+ KONG_CLUSTER_CA_CERT=//ca-cert.pem
+ KONG_CLUSTER_CERT=//control-plane.crt
+ KONG_CLUSTER_CERT_KEY=//control-plane.key
+ ```
+ By setting the role of the node to `control_plane`, this node will listen on
+ port `0.0.0.0:8005` by default for data plane connections, and on port
+ `0.0.0.0:8006` for telemetry data. These ports on the
+ control plane will need to be accessible by all data planes it controls through
+ any firewalls you may have in place.
+
+ For PKI mode, `KONG_CLUSTER_CA_CERT` specifies the root CA certificate for
+ `KONG_CLUSTER_CERT` and `KONG_CLUSTER_CERT_KEY`. This certificate must be
+ the root CA certificate and not any of an intermediate CA. Kong allows a
+ maximum of three levels of intermediate CAs to be used between the root CA
+ and the cluster certificate.
+
+ If you need to change the ports that the control plane listens on, set:
+ ```bash
+ KONG_CLUSTER_LISTEN=0.0.0.0:
+ KONG_CLUSTER_TELEMETRY_LISTEN=0.0.0.0:
+ ```
+
+2. Next, start Kong, or reload Kong if it's already running:
+ ```bash
+ kong start
+ ```
+ ```bash
+ kong reload
+ ```
+
+{% endnavtab %}
+{% navtab Using kong.conf %}
+1. In `kong.conf`, set the following configuration parameters:
+
+ For `shared` certificate mode, use:
+ ```bash
+ role = control_plane
+ cluster_cert = //cluster.crt
+ cluster_cert_key = //cluster.key
+ ```
+
+ For `pki` certificate mode, use:
+ ```bash
+ role = control_plane
+ cluster_mtls = pki
+ cluster_ca_cert = //ca-cert.pem
+ cluster_cert = //control-plane.crt
+ cluster_cert_key = //control-plane.key
+ ```
+
+ By setting the role of the node to `control_plane`, this node will listen on
+ port `0.0.0.0:8005` by default for data plane connections, and on port
+ `0.0.0.0:8006` for telemetry data. These ports on the
+ control plane will need to be accessible by all data planes it controls through
+ any firewalls you may have in place.
+
+ For PKI mode, `cluster_ca_cert` specifies the root CA certificate for
+ `cluster_cert` and `cluster_cert_key`. This certificate must be the root CA
+ certificate and not any of an intermediate CA. Kong allows a maximum of three
+ levels of intermediate CAs to be used between the root CA and the cluster
+ certificate.
+
+ If you need to change the ports that the control plane listens on, set:
+ ```bash
+ cluster_listen=0.0.0.0:
+ cluster_telemetry_listen=0.0.0.0:
+ ```
+
+2. Restart Kong for the settings to take effect:
+ ```bash
+ kong restart
+ ```
+{% endnavtab %}
+{% endnavtabs %}
+
+Note that the control plane still needs a database to
+store the central configurations, although the database never needs to
+be accessed by data plane nodes. You may run multiple control plane nodes to
+provide load balancing and redundancy, as long as they all point to the same
+backend database.
+
+{:.note}
+> **Note:** Control plane nodes cannot be used for proxying.
+
+### (Optional) Revocation checks of data plane certificates
+
+When Kong is running hybrid mode with PKI mode, the control plane can be configured to
+optionally check for revocation status of the connecting data plane certificate.
+
+The supported method is through Online Certificate Status Protocol (OCSP) responders.
+Issued data plane certificates must contain the Certificate Authority Information Access extension
+that references the URI of OCSP responder that can be reached from the control plane.
+
+To enable OCSP checks, set the `cluster_ocsp` config on the control plane to one of the following values:
+
+* `on`: OCSP revocation check is enabled and the data plane must pass the revocation check
+to establish connection with the control plane. This implies that certificates without the
+OCSP extension or unreachable OCSP responder also prevents a connection from being established.
+* `off`: OCSP revocation check is disabled (default).
+* `optional`: OCSP revocation check will be attempted, however, if the OCSP responder URI is not
+found inside the data plane-provided certificate or communication with the OCSP responder failed,
+then data plane is still allowed through.
+
+Note that OCSP checks are only performed on the control plane against certificates provided by incoming data plane
+nodes. The `cluster_ocsp` config has no effect on data plane nodes.
+`cluster_oscp` affects all hybrid mode connections established from a data plane to its control plane.
+
+## Install and start data planes
+Now that the control plane is running, you can attach data plane nodes to it to
+start serving traffic.
+
+In this step, you will give all data plane nodes the `data_plane` role,
+point them to the control plane, set certificate/key parameters to point at
+the location of your certificates and keys, and ensure the database
+is disabled.
+
+In addition, the certificate from `cluster_cert` (in `shared` mode) or `cluster_ca_cert`
+(in `pki` mode) is automatically added to the trusted chain in
+[`lua_ssl_trusted_certificate`](/gateway/{{page.kong_version}}/reference/configuration/#lua_ssl_trusted_certificate).
+
+{:.important}
+> **Important:** Data plane nodes receive updates from the control plane via a format
+similar to declarative config, therefore `database` has to be set to
+`off` for Kong to start up properly.
+
+See the [DP node start sequence](#dp-node-start-sequence) for more information
+on how data plane nodes process configuration.
+
+
+{% navtabs %}
+{% navtab Using Docker %}
+1. Using the [Docker installation documentation](/gateway/{{page.kong_version}}/install-and-run/docker),
+follow the instructions to:
+ 1. [Download {{site.base_gateway}}](/gateway/{{page.kong_version}}/install-and-run/docker).
+ 2. [Create a Docker network](/gateway/{{page.kong_version}}/install-and-run/docker/#install-gateway-in-db-less-mode).
+
+ {:.warning}
+ > **Warning:** Do not start or create a database on this node.
+
+
+1. Bring up your data plane container with the following settings:
+
+ For `shared` certificate mode, use:
+
+{% capture shared-mode-cp %}
+{% navtabs codeblock %}
+{% navtab Kong Gateway %}
+```bash
+docker run -d --name kong-dp --network=kong-net \
+-e "KONG_ROLE=data_plane" \
+-e "KONG_DATABASE=off" \
+-e "KONG_PROXY_LISTEN=0.0.0.0:8000" \
+-e "KONG_CLUSTER_CONTROL_PLANE=control-plane..com:8005" \
+-e "KONG_CLUSTER_TELEMETRY_ENDPOINT=control-plane..com:8006" \
+-e "KONG_CLUSTER_CERT=//cluster.crt" \
+-e "KONG_CLUSTER_CERT_KEY=//cluster.key" \
+--mount type=bind,source="$(pwd)"/cluster,target=,readonly \
+-p 8000:8000 \
+kong/kong-gateway:{{page.kong_versions[page.version-index].ee-version}}-alpine
+```
+{% endnavtab %}
+{% navtab Kong Gateway (OSS) %}
+```bash
+docker run -d --name kong-dp --network=kong-net \
+-e "KONG_ROLE=data_plane" \
+-e "KONG_DATABASE=off" \
+-e "KONG_PROXY_LISTEN=0.0.0.0:8000" \
+-e "KONG_CLUSTER_CONTROL_PLANE=control-plane..com:8005" \
+-e "KONG_CLUSTER_TELEMETRY_ENDPOINT=control-plane..com:8006" \
+-e "KONG_CLUSTER_CERT=//cluster.crt" \
+-e "KONG_CLUSTER_CERT_KEY=//cluster.key" \
+--mount type=bind,source="$(pwd)"/cluster,target=,readonly \
+-p 8000:8000 \
+kong:{{page.kong_versions[page.version-index].ce-version}}-alpine
+```
+{% endnavtab %}
+{% endnavtabs %}
+{% endcapture %}
+{{ shared-mode-cp | indent | replace: " ", "" }}
+
+ For `pki` certificate mode, use:
+
+{% capture pki-mode-cp %}
+{% navtabs codeblock %}
+{% navtab Kong Gateway %}
+```bash
+docker run -d --name kong-dp --network=kong-net \
+-e "KONG_ROLE=data_plane" \
+-e "KONG_DATABASE=off" \
+-e "KONG_PROXY_LISTEN=0.0.0.0:8000" \
+-e "KONG_CLUSTER_CONTROL_PLANE=control-plane..com:8005" \
+-e "KONG_CLUSTER_TELEMETRY_ENDPOINT=control-plane..com:8006" \
+-e "KONG_CLUSTER_MTLS=pki" \
+-e "KONG_CLUSTER_SERVER_NAME=control-plane.kong.yourcorp.tld" \
+-e "KONG_CLUSTER_CERT=data-plane.crt" \
+-e "KONG_CLUSTER_CERT_KEY=//data-plane.crt" \
+-e "KONG_CLUSTER_CA_CERT=//ca-cert.pem" \
+--mount type=bind,source="$(pwd)"/cluster,target=,readonly \
+-p 8000:8000 \
+kong/kong-gateway:{{page.kong_versions[page.version-index].ee-version}}-alpine
+```
+{% endnavtab %}
+{% navtab Kong Gateway (OSS) %}
+```bash
+docker run -d --name kong-dp --network=kong-net \
+-e "KONG_ROLE=data_plane" \
+-e "KONG_DATABASE=off" \
+-e "KONG_PROXY_LISTEN=0.0.0.0:8000" \
+-e "KONG_CLUSTER_CONTROL_PLANE=control-plane..com:8005" \
+-e "KONG_CLUSTER_TELEMETRY_ENDPOINT=control-plane..com:8006" \
+-e "KONG_CLUSTER_MTLS=pki" \
+-e "KONG_CLUSTER_SERVER_NAME=control-plane.kong.yourcorp.tld" \
+-e "KONG_CLUSTER_CERT=data-plane.crt" \
+-e "KONG_CLUSTER_CERT_KEY=//data-plane.crt" \
+-e "KONG_CLUSTER_CA_CERT=//ca-cert.pem" \
+--mount type=bind,source="$(pwd)"/cluster,target=,readonly \
+-p 8000:8000 \
+kong:{{page.kong_versions[page.version-index].ce-version}}-alpine
+```
+{% endnavtab %}
+{% endnavtabs %}
+{% endcapture %}
+{{ pki-mode-cp | indent | replace: " ", "" }}
+
+ Where:
+
+ `--name` and `--network`
+ : The tag of the {{site.base_gateway}} image that you're using, and the Docker network it communicates on.
+
+ `KONG_CLUSTER_CONTROL_PLANE`
+ : Sets the address and port of the control plane (port `8005` by defaut).
+
+ `KONG_DATABASE`
+ : Specifies whether this node connects directly to a database.
+
+ `` and `target=`
+ : Are the same path, pointing to the location of the `cluster.key` and
+ `cluster.crt` files.
+
+ `KONG_CLUSTER_SERVER_NAME`
+ : Specifies the SNI (Server Name Indication
+ extension) to use for data plane connections to the control plane through
+ TLS. When not set, data plane will use `kong_clustering` as the SNI.
+
+ : You can also optionally use `KONG_CLUSTER_TELEMETRY_SERVER_NAME`
+ to set a custom SNI for telemetry data. If not set, it defaults to
+ `KONG_CLUSTER_SERVER_NAME`.
+
+ `KONG_CLUSTER_TELEMETRY_ENDPOINT`
+ : Optional setting, needed for telemetry gathering. Not available in open-source deployments.
+
+ You can also choose to encrypt or disable the data plane configuration
+ cache with some additional settings:
+
+1. If needed, bring up any subsequent data planes using the same settings.
+
+{% endnavtab %}
+{% navtab Using kong.conf %}
+
+1. Find the documentation for [your platform](/gateway/{{page.kong_version}}/install-and-run),
+and follow the instructions in Steps 1 and 2 **only** to download
+{{site.base_gateway}} and install Kong.
+
+ {:.note}
+ > **Note:** for Docker, see the **Docker** tab above. For Kubernetes, see the
+ [hybrid mode documentation](https://github.com/Kong/charts/blob/main/charts/kong/README.md#hybrid-mode)
+ in the `kong/charts` repository.
+
+ {:.warning}
+ > Do not start or create a database on this node.
+
+
+2. In `kong.conf`, set the following configuration parameters:
+
+ For `shared` certificate mode, use:
+ ```bash
+ role = data_plane
+ database = off
+ proxy_listen = 0.0.0.0:8000
+ cluster_control_plane = control-plane..com:8005
+ cluster_telemetry_endpoint = control-plane..com:8006
+ cluster_cert = //cluster.crt
+ cluster_cert_key = //cluster.key
+ ```
+
+ For `pki` certificate mode, use:
+ ```bash
+ role = data_plane
+ database = off
+ proxy_listen = 0.0.0.0:8000
+ cluster_control_plane = control-plane..com:8005
+ cluster_telemetry_endpoint = control-plane..com:8006
+ cluster_mtls = pki
+ cluster_server_name = control-plane.kong.yourcorp.tld
+ cluster_cert = //data-plane.crt
+ cluster_cert_key = //data-plane.crt
+ cluster_ca_cert = //ca-cert.pem
+ ```
+
+ Where:
+
+ `cluster_control_plane`
+ : Sets the address and port of the control plane (port `8005` by defaut).
+
+ `database`
+ : Specifies whether this node connects directly to a database.
+
+ ``
+ : Specifies the location of the `cluster.key` and `cluster.crt` files.
+
+ `cluster_server_name`
+ : Specifies the SNI (Server Name Indication extension)
+ to use for data plane connections to the control plane through TLS. When
+ not set, data plane will use `kong_clustering` as the SNI.
+
+ : You can also optionally use `cluster_telemetry_server_name`
+ to set a custom SNI for telemetry data. If not set, it defaults to
+ `cluster_server_name`.
+
+ `cluster_telemetry_endpoint`
+ : Optional setting, needed for telemetry gathering. Not available in open-source deployments.
+
+ You can also choose to encrypt or disable the data plane configuration
+ cache with some additional settings:
+
+3. Restart Kong for the settings to take effect:
+ ```bash
+ kong restart
+ ```
+{% endnavtab %}
+{% endnavtabs %}
+
+## Verify that nodes are connected
+
+Use the control plane’s Cluster Status API to monitor your data planes. It
+provides:
+* The name of the node
+* The last time the node synced with the control plane
+* The version of the config currently running on each data plane
+
+To check whether the CP and DP nodes you just brought up are connected, run the
+following on a control plane:
+{% navtabs %}
+{% navtab Using cURL %}
+```bash
+curl -i -X GET http://:8001/clustering/data-planes
+```
+{% endnavtab %}
+{% navtab Using HTTPie %}
+```bash
+http :8001/clustering/data-planes
+```
+{% endnavtab %}
+{% endnavtabs %}
+The output shows all of the connected data plane instances in the cluster:
+
+```json
+{
+ "data": [
+ {
+ "config_hash": "a9a166c59873245db8f1a747ba9a80a7",
+ "hostname": "data-plane-2",
+ "id": "ed58ac85-dba6-4946-999d-e8b5071607d4",
+ "ip": "192.168.10.3",
+ "last_seen": 1580623199,
+ "status": "connected"
+ },
+ {
+ "config_hash": "a9a166c59873245db8f1a747ba9a80a7",
+ "hostname": "data-plane-1",
+ "id": "ed58ac85-dba6-4946-999d-e8b5071607d4",
+ "ip": "192.168.10.4",
+ "last_seen": 1580623200,
+ "status": "connected"
+ }
+ ],
+ "next": null
+}
+```
+
+## References
+
+### DP node start sequence
+
+When set as a DP node, {{site.base_gateway}} processes configuration in the
+following order:
+
+1. **Config cache**: If the file `config.json.gz` exists in the `kong_prefix`
+path (`/usr/local/kong` by default), the DP node loads it as configuration.
+2. **`declarative_config` exists**: If there is no config cache and the
+`declarative_config` parameter is set, the DP node loads the specified file.
+3. **Empty config**: If there is no config cache or declarative
+configuration file available, the node starts with empty configuration. In this
+state, it returns 404 to all requests.
+4. **Contact CP Node**: In all cases, the DP node contacts the CP node to retrieve
+the latest configuration. If successful, it gets stored in the local config
+cache (`config.json.gz`).
+
+### Configuration reference
+
+Use the following configuration properties to configure {{site.base_gateway}}
+in hybrid mode.
+
+Parameter | Description | CP or DP {:width=10%:}
+--------- | ----------- | ----------------------
+[`role`](/gateway/{{page.kong_version}}/reference/configuration/#role)
*Required* | Determines whether the {{site.base_gateway}} instance is a control plane or a data plane. Valid values are `control_plane` or `data_plane`. | Both
+[`cluster_listen`](/gateway/{{page.kong_version}}/reference/configuration/#cluster_listen)
*Optional*
**Default:** `0.0.0.0:8005`| List of addresses and ports on which the control plane will listen for incoming data plane connections. This port is always protected with Mutual TLS (mTLS) encryption. Ignored on data plane nodes. | CP
+[`proxy_listen`](/gateway/{{page.kong_version}}/reference/configuration/#proxy_listen)
*Required* | Comma-separated list of addresses and ports on which the proxy server should listen for HTTP/HTTPS traffic. Ignored on control plane nodes. | DP
+[`cluster_telemetry_listen`](/gateway/{{page.kong_version}}/reference/configuration/#cluster_telemetry_listen)
*Optional*
**Default:** `0.0.0.0:8006`| List of addresses and ports on which the control plane will listen for data plane telemetry data. This port is always protected with Mutual TLS (mTLS) encryption. Ignored on data plane nodes. | CP
+[`cluster_telemetry_endpoint`](/gateway/{{page.kong_version}}/reference/configuration/#cluster_telemetry_endpoint)
*Required for Enterprise deployments* | The port that the data plane uses to send telemetry data to the control plane. Ignored on control plane nodes. | DP
+[`cluster_control_plane`](/gateway/{{page.kong_version}}/reference/configuration/#cluster_control_plane)
*Required* | Address and port that the data plane nodes use to connect to the control plane. Must point to the port configured using the [`cluster_listen`](/gateway/{{page.kong_version}}/reference/configuration/#cluster_listen) property on the control plane node. Ignored on control plane nodes. | DP
+[`cluster_mtls`](/gateway/{{page.kong_version}}/reference/configuration/#cluster_mtls)
*Optional*
**Default:** `shared` | One of `shared` or `pki`. Indicates whether hybrid mode will use a shared certificate/key pair for CP/DP mTLS or if PKI mode will be used. See below sections for differences in mTLS modes. | Both
+
+The following properties are used differently between `shared` and `pki` modes:
+
+Parameter | Description | Shared Mode {:width=12%:} | PKI Mode {:width=30%:}
+--------- | ----------- | ------------------------- | ----------------------
+[`cluster_cert`](/gateway/{{page.kong_version}}/reference/configuration/#cluster_cert) and [`cluster_cert_key`](/gateway/{{page.kong_version}}/reference/configuration/#cluster_cert_key)
*Required* | Certificate/key pair used for mTLS between CP/DP nodes. | Same between CP/DP nodes. | Unique certificate for each node, generated from the CA specified by `cluster_ca_cert`.
+[`cluster_ca_cert`](/gateway/{{page.kong_version}}/reference/configuration/#cluster_ca_cert)
*Required in PKI mode* | The trusted CA certificate file in PEM format used to verify the `cluster_cert`. | *Ignored* | CA certificate used to verify `cluster_cert`, same between CP/DP nodes. *Required*
+[`cluster_server_name`](/gateway/{{page.kong_version}}/reference/configuration/#cluster_server_name)
*Required in PKI mode* | The SNI presented by the DP node mTLS handshake. | *Ignored* | In PKI mode, the DP nodes will also verify that the Common Name (CN) or Subject Alternative Name (SAN) inside the certificate presented by CP matches the `cluster_server_name` value.
+[`cluster_telemetry_server_name`](/gateway/{{page.kong_version}}/reference/configuration/#cluster_telemetry_server_name) | The telemetry SNI presented by the DP node mTLS handshake. If not specified, falls back on SNI set in `cluster_server_name`. | *Ignored* | In PKI mode, the DP nodes will also verify that the Common Name (CN) or Subject Alternative Name (SAN) inside the certificate presented by CP matches the `cluster_telemetry_server_name` value.
+
+## Next steps
+
+Now, you can start managing the cluster using the control plane. Once
+all instances are set up, use the Admin API on the control plane as usual, and
+these changes will be synced and updated on the data plane nodes automatically
+within seconds.
diff --git a/src/gateway/production-deployment/deployment-topologies/index.md b/src/gateway/production-deployment/deployment-topologies/index.md
new file mode 100644
index 000000000000..07db17e67efd
--- /dev/null
+++ b/src/gateway/production-deployment/deployment-topologies/index.md
@@ -0,0 +1,6 @@
+---
+title: Overview
+
+---
+
+## PLACEHOLDER Overview
diff --git a/src/gateway/production-deployment/deployment-topologies/traditional.md b/src/gateway/production-deployment/deployment-topologies/traditional.md
new file mode 100644
index 000000000000..4163a58c765e
--- /dev/null
+++ b/src/gateway/production-deployment/deployment-topologies/traditional.md
@@ -0,0 +1,6 @@
+---
+title: traditional
+
+---
+
+## PLACEHOLDER traditional
diff --git a/src/gateway/kong-production/environment-variables.md b/src/gateway/production-deployment/environment-variables.md
similarity index 100%
rename from src/gateway/kong-production/environment-variables.md
rename to src/gateway/production-deployment/environment-variables.md
diff --git a/src/gateway/kong-production/kong-conf.md b/src/gateway/production-deployment/kong-conf.md
similarity index 100%
rename from src/gateway/kong-production/kong-conf.md
rename to src/gateway/production-deployment/kong-conf.md
diff --git a/src/gateway/kong-production/kong-openresty.md b/src/gateway/production-deployment/kong-openresty.md
similarity index 100%
rename from src/gateway/kong-production/kong-openresty.md
rename to src/gateway/production-deployment/kong-openresty.md
diff --git a/src/gateway/kong-production/logging.md b/src/gateway/production-deployment/logging.md
similarity index 100%
rename from src/gateway/kong-production/logging.md
rename to src/gateway/production-deployment/logging.md
diff --git a/src/gateway/kong-production/monitoring/datadog.md b/src/gateway/production-deployment/monitoring/datadog.md
similarity index 100%
rename from src/gateway/kong-production/monitoring/datadog.md
rename to src/gateway/production-deployment/monitoring/datadog.md
diff --git a/src/gateway/kong-production/monitoring/index.md b/src/gateway/production-deployment/monitoring/index.md
similarity index 100%
rename from src/gateway/kong-production/monitoring/index.md
rename to src/gateway/production-deployment/monitoring/index.md
diff --git a/src/gateway/production-deployment/monitoring/prometheus.md b/src/gateway/production-deployment/monitoring/prometheus.md
new file mode 100644
index 000000000000..d79babe49922
--- /dev/null
+++ b/src/gateway/production-deployment/monitoring/prometheus.md
@@ -0,0 +1,6 @@
+---
+title: Prometheus How to monitor
+
+---
+
+## PLACEHOLDER Monitoring with Prometheus
\ No newline at end of file
diff --git a/src/gateway/kong-production/monitoring/statsd.md b/src/gateway/production-deployment/monitoring/statsd.md
similarity index 100%
rename from src/gateway/kong-production/monitoring/statsd.md
rename to src/gateway/production-deployment/monitoring/statsd.md
diff --git a/src/gateway/kong-production/networking/default-ports.md b/src/gateway/production-deployment/networking/default-ports.md
similarity index 100%
rename from src/gateway/kong-production/networking/default-ports.md
rename to src/gateway/production-deployment/networking/default-ports.md
diff --git a/src/gateway/kong-production/networking/dns-considerations.md b/src/gateway/production-deployment/networking/dns-considerations.md
similarity index 100%
rename from src/gateway/kong-production/networking/dns-considerations.md
rename to src/gateway/production-deployment/networking/dns-considerations.md
diff --git a/src/gateway/kong-production/networking/network.md b/src/gateway/production-deployment/networking/firewall.md
similarity index 99%
rename from src/gateway/kong-production/networking/network.md
rename to src/gateway/production-deployment/networking/firewall.md
index 303331d80693..438f257cd5af 100644
--- a/src/gateway/kong-production/networking/network.md
+++ b/src/gateway/production-deployment/networking/firewall.md
@@ -1,5 +1,6 @@
---
title: Network and Firewall
+content_type: reference
---
In this section you will find a summary about the recommended network and firewall settings for Kong.
diff --git a/src/gateway/kong-production/running-kong/kong-user.md b/src/gateway/production-deployment/running-kong/kong-user.md
similarity index 100%
rename from src/gateway/kong-production/running-kong/kong-user.md
rename to src/gateway/production-deployment/running-kong/kong-user.md
diff --git a/src/gateway/admin-api/secure-admin-api.md b/src/gateway/production-deployment/running-kong/secure-admin-api.md
similarity index 100%
rename from src/gateway/admin-api/secure-admin-api.md
rename to src/gateway/production-deployment/running-kong/secure-admin-api.md
diff --git a/src/gateway/kong-production/running-kong/systemd.md b/src/gateway/production-deployment/running-kong/systemd.md
similarity index 100%
rename from src/gateway/kong-production/running-kong/systemd.md
rename to src/gateway/production-deployment/running-kong/systemd.md
diff --git a/src/gateway/kong-production/kong-security-update-process.md b/src/gateway/production-deployment/security-update-process.md
similarity index 100%
rename from src/gateway/kong-production/kong-security-update-process.md
rename to src/gateway/production-deployment/security-update-process.md
diff --git a/src/gateway/kong-production/sizing-guidelines.md b/src/gateway/production-deployment/sizing-guidelines.md
similarity index 100%
rename from src/gateway/kong-production/sizing-guidelines.md
rename to src/gateway/production-deployment/sizing-guidelines.md
diff --git a/src/gateway/kong-production/tracing/api.md b/src/gateway/production-deployment/tracing/api.md
similarity index 100%
rename from src/gateway/kong-production/tracing/api.md
rename to src/gateway/production-deployment/tracing/api.md
diff --git a/src/gateway/kong-production/tracing/index.md b/src/gateway/production-deployment/tracing/index.md
similarity index 100%
rename from src/gateway/kong-production/tracing/index.md
rename to src/gateway/production-deployment/tracing/index.md
diff --git a/src/gateway/kong-production/tracing/write-custom-trace-exporter.md b/src/gateway/production-deployment/tracing/write-custom-trace-exporter.md
similarity index 100%
rename from src/gateway/kong-production/tracing/write-custom-trace-exporter.md
rename to src/gateway/production-deployment/tracing/write-custom-trace-exporter.md
diff --git a/src/gateway/kong-production/website-api-serving.md b/src/gateway/production-deployment/website-api-serving.md
similarity index 100%
rename from src/gateway/kong-production/website-api-serving.md
rename to src/gateway/production-deployment/website-api-serving.md
diff --git a/src/gateway/reference/rate-limit.md b/src/gateway/reference/rate-limit.md
deleted file mode 100644
index ae5d9c7c2836..000000000000
--- a/src/gateway/reference/rate-limit.md
+++ /dev/null
@@ -1,142 +0,0 @@
----
-title: Rate Limiting Library
-badge: enterprise
----
-
-## Overview
-
-
-{% include_cached /md/enterprise/cassandra-deprecation.md %}
-
-
-This library is designed to provide an efficient, scalable, eventually-consistent sliding window rate limiting library. It relies on atomic operations in shared ngx memory zones to track window counters within a given node, periodically syncing this data to a central data store.
-
-A sliding window rate limiting implementation tracks the number of hits assigned to a specific key (such as an IP address, Consumer, Credential, etc) within a given time window, taking into account previous hit rates to smooth out a calculated rate, while still providing a familiar windowing interface that modern developers are used to (e.g., n hits per second/minute/hour). This is similar to a fixed window implementation, in which request rates reset at the beginning of the window, but without the "reset bump" from which fixed window implementations suffer, while providing a more intuitive interface beyond what leaky bucket or token bucket implementations can offer. Note that we use the term "hit" instead of "request" when referring to incrementing values for rate limit keys, because this library provides an abstract rate limiting interface; a sliding window implementation may have uses outside of HTTP request rate limiting, thus, we describe this library in a more abstract sense.
-
-A sliding window takes into account a weighted value of the previous window when calculating the current rate for a given key. A window is defined as a period of time, starting at a given "floor" timestamp, where the floor is calculated based on the size of the window. For window sizes of 60 seconds, the floor always falls at the 0th second (e.g., at the beginning of any given minute). Likewise, windows with a size of 30 seconds will begin at the 0th and 30th seconds of each minute.
-
-Consider a rate limit of 10 hits per minute. In this configuration, this library will calculate the hit rate of a given key based on the number of hits for the current window (starting at the beginning of the current minute), and a weighted percentage of all hits of the previous window (e.g., the previous minute). This weight is calculated based on the current timestamp with respect to the window size in question; the farther away the current time is from the start of the previous window, the lower the weight percentage. This value is best expressed through an example:
-
-```
-current window rate: 10
-previous window rate: 40
-window size: 60
-window position: 30 (seconds past the start of the current window)
-weight = .5 (60 second window size - 30 seconds past the window start)
-
-rate = 'current rate' + 'previous weight' * 'weight'
- = 10 + 40 * ('window size' - 'window position') / 'window size'
- = 10 + 40 * (60 - 30) / 60
- = 10 + 40 * .5
- = 30
-```
-Strictly speaking, the formula used to define the weighting percentage is as follows:
-
-`weight = (window_size - (time() % window_size)) / window_size`
-
-Where `time()` is the value of the current Unix timestamp.
-
-Each node in the Kong cluster relies on its own in-memory data store as the source of truth for rate limiting counters. Periodically, each node pushes a counter increment for each key it saw to the cluster, which is expected to atomically apply this diff to the appropriate key. The node then retrieves this key's value from the data store, along with other relevant keys for this data sync cycle. In this manner, each node shares the relevant portions of data with the cluster, while relying on a very high-performance method of tracking data during each request. This cycle of converge -> diverge -> reconverge among nodes in the cluster provides our eventually-consistent model.
-
-The periodic rate at which nodes converge is configurable; shorter sync intervals will result in less divergence of data points when traffic is spread across multiple nodes in the cluster (e.g., when sitting behind a round robin balancer), whereas longer sync intervals put less r/w pressure on the datastore, and less overhead on each node to calculate diffs and fetch new synced values. The desirable value here depends on use case; when using cluster syncing to refresh nodes periodically (e.g., to inform new cluster nodes of counter data), a value of 10-30 seconds may be desirable, to minimize data store traffic. Contrarily, environments demanding stronger consistency between nodes (such as orchestrated deployments involving a high churn rate among cluster membership, or cases where strict rate limiting policies must be applied to node sitting behind a non-hashing load balancer) should use a lower sync period, on the order of milliseconds. The minimum possible value is 0.001 (1 millisecond), though practically this value is limited by network performance between Kong nodes and the configured data store.
-
-In addition to periodic data sync behavior, this library can implement rate limiting counter in a synchronous pattern by defining its `sync_rate` as `0`. In such a case, the given counter will be applied directly to the datastore. This behavior is desirable in cases where stronger consistency among the cluster is desired; such a configuration comes with the cost of needing to communicate with the datastore (or Redis) on every request, which can induce noticeable latency into the request ("noticeable" being a relative term of typically a few milliseconds, depending on the performance of the storage mechanism in question; for comparison, Kong typically processes requests on the order of tens of microseconds).
-
-This library can also forgo syncing counter data entirely, and only apply incremental counters to its local memory zone, by defining a `sync_rate` value of less than `0`. This behavior is useful when cluster-wide syncing of data is unnecessary, such as environments using only a single Kong node, or where Kong nodes live behind a hashing load balancer and are treated as isolated instances.
-
-Module configuration data, such as sync rate, shared dictionary name, storage policy, etc, is kept in a per-worker public configuration table. Multiple configurations can be defined as stored as arbitrary `namespaces` (more on this below).
-
-## Developer Notes
-### Public Functions
-The following public functions are provided by this library:
-
-`ratelimiting.new`
-
-_syntax: ok = ratelimiting.new(opts)_
-
-Define configurations for a new namespace. The following options are accepted:
-
-- dict: Name of the shared dictionary to use
-- sync_rate: Rate, in seconds, to sync data diffs to the storage server.
-- strategy: Storage strategy to use. currently cassandra, postgres, and redis are supported. Strategies must provide several public—functions defined below.
-- strategy_opts: A table of options used by the storage strategy. Currently only applicable for the 'redis' strategy.
-- namespace: String defining these config values. A namespace may only be defined once; if a namespace has already been defined on this worker, an error is thrown. If no namespace is defined, the literal string "default" will be used.
-- window_sizes: A list of window sizes used by this configuration.
-
-`ratelimiting.increment`
-
-_syntax: rate = ratelimiting.increment(key, window_size, value, namespace?)_
-
-Increment a given key for window_size by value. If namespace is undefined, the "default" namespace is used. value can be any number Lua type (but ensure that the storage strategy in use for this namespace can support decimal values if a non-integer value is provided). This function returns the sliding rate for this key/window_size after the increment of value has been applied.
-
-`ratelimit.sliding_window`
-
-_syntax: rate = ratelimit.sliding_window(key, window_size, cur_diff?, namespace?)_
-
-Return the current sliding rate for this key/window_size. An optional cur_diff value can be provided that overrides the current stored diff for this key. If `namespace` is undefined, the "default" namespace is used.
-
-`ratelimiting.sync`
-
-_syntax: ratelimiting.sync(premature, namespace?)_
-
-Sync all currently stored key diffs in this worker with the storage server, and retrieve the newly synced value. If namespace is undefined, the "default" `namespace` is used. Before the diffs are pushed, another sync call for the given namespace is scheduled at `sync_rate` seconds in the future. Given this, this function should typically be called during the `init_worker` phase to initialize the recurring timer. This function is intended to be called in an `ngx.timer` context; hence, the first variable represents the injected `premature` param.
-
-`ratelimiting.fetch`
-
-_syntax: ratelimiting.fetch(premature, namespace, time, timeout?)_
-
-Retrieve all relevant counters for the given namespace at the given time. This
-function establishes a shm mutex such that only one worker will fetch and
-populate the shm per execution. If timeout is defined, the mutex will expire
-based on the given timeout value; otherwise, the mutex is unlocked immediately
-following the dictionary update. This function can be called in an `ngx.timer`
-context; hence, the first variable represents the injected `premature` param.
-
-### Strategy Functions
-
-Storage strategies must provide the following interfaces:
-
-#### strategy_class.new
-_syntax: strategy = strategy_class.new(dao_factory, opts)_
-
-Implement a new strategy object. `opts` is expected to be a table type, and can be used to pass opaque/arbitrary options to the strategy class.
-
-#### strategy:push_diffs
-_syntax: strategy:push_diffs(diffs)_
-
-Push a table of key diffs to the storage server. diffs is a table provided in the following format:
-
-```
-[1] = {
- key = "1.2.3.4",
- windows = {
- {
- window = 12345610,
- size = 60,
- diff = 5,
- namespace = foo,
- },
- {
- window = 12345670,
- size = 60,
- diff = 5,
- namespace = foo,
- },
- }
- },
- ...
- ["1.2.3.4"] = 1,
- ...
- ```
-
-#### strategy:get_counters
-
-_syntax: rows = strategy:get_counters(namespace, window_sizes, time?)_
-
-Return an iterator for each key stored in the datastore/redis for a given `namepsace` and list of window sizes. 'time' is an optional unix second- precision timestamp; if not provided, this value will be set via `ngx.time()`. It is encouraged to pass this via a previous defined timestamp, depending on the context (e.g., if previous calls in the same thread took a nontrivial amount of time to run).
-
-#### strategy:get_window
-
-_syntax: window = strategy:get_window(key, namespace, window_start, window_size)_
-
-Retrieve a single key from the data store based on the values provided.
diff --git a/src/gateway/availability-stages.md b/src/gateway/stability.md
similarity index 100%
rename from src/gateway/availability-stages.md
rename to src/gateway/stability.md
diff --git a/src/gateway/understanding-kong/how-to/kong-gateway.md b/src/gateway/understanding-kong/how-to/kong-gateway.md
deleted file mode 100644
index f5f7f0772c2b..000000000000
--- a/src/gateway/understanding-kong/how-to/kong-gateway.md
+++ /dev/null
@@ -1,100 +0,0 @@
----
-title: Run Kong Gateway in minutes
-description: A how-to guide for quickly starting a Kong Gateway
----
-
-In order to explore the capabilities of [{{site.base_gateway}}](/gateway/latest/),
-you'll need one to experiment with. This guide helps you quickly deploy Kong
-using [Docker](https://docs.docker.com/get-started/overview/). This guide's purpose is not to provide a production-like deployment or an explanation of deployment steps but rather to quickly get you a running {{site.base_gateway}} instance and an example [service](/gateway/latest/admin-api/#service-object) as quickly as possible.
-
-### Prerequisites
-
-This guide assumes each of the following tools are installed locally.
-* [Docker](https://docs.docker.com/get-docker/) is used to run Kong and the supporting database locally.
-* [curl](https://curl.se/) is used to send requests to the gateway. Most systems come with `curl` pre-installed.
-
-### Steps
-
-In order to get started, you'll download and execute a shell script that automatically installs Kong, its supporting database, and an example service.
-Then you'll interact with the gateway using `curl` to ensure it has been started properly.
-
-Run the following command to start {{site.base_gateway}} using Docker:
-
-```sh
-curl -Ls get.konghq.com/quickstart | sh -s -- -m
-```
-
-{:.note}
-> **Note:** The script creates a log file in the current directory named `kong-quickstart.log`
-
-Docker will download and run {{site.base_gateway}} and the supporting database. Additionally,
-the script bootstraps the database and installs a [mock service](https://mockbin.org/).
-
-Once Kong is available, you will see:
-
-```text
-✔ Kong is ready!
-```
-
-The script outputs connectivity details for your new gateway, which should look similar to the following:
-
-```text
-Kong Data Plane endpoint = localhost:55248
-Kong Admin API endpoint = localhost:55247
-```
-
-Docker assigns available network ports on the host machine to {{site.base_gateway}} services and forwards
-network traffic to {{site.base_gateway}}. You can see all the ports that {{site.base_gateway}} is listening on and the related host ports
-using this Docker command:
-
-```sh
-docker port kong-quickstart-gateway
-```
-
-The script will create a file with connection values you can source into your environment
-that you can use throughout the rest of the guide. Load the values into your current environment:
-
-```sh
-source kong.env
-```
-
-After you have sourced the `kong.env` environment variable file,
-test the [Kong Admin API](/gateway/latest/admin-api/) with the following:
-
-```sh
-curl $KONG_ADMIN_API
-```
-
-You will see a large JSON response from the Admin API containing information about the running gateway,
-including network, configuration, and plugins details.
-
-Test that {{site.base_gateway}} is proxying data by making a mock request to the gateway's data plane endpoint:
-
-```sh
-curl $KONG_PROXY/mock/requests
-```
-
-If everything is working correctly, you will see a JSON response from the mock service with various
-information about the request made, including headers, timestamps, and IP addresses.
-
-### Cleanup
-
-Once you are done working with {{site.base_gateway}}, you can use the shell script to stop and
-remove the gateway and database containers with the following command:
-
-```sh
-curl -Ls get.konghq.com/quickstart | sh -s -- -d
-```
-
-### What's next?
-
-You now have a {{site.base_gateway}} instance running locally. Kong offers a tremendous amount of capabilities
-to help you manage, configure and route requests to your APIs.
-
-* To follow a more detailed step-by-step guide to starting Kong, see the
-[Kong Getting Started guide](/gateway/latest/get-started/).
-* The [Admin API documentation](/gateway/latest/admin-api/)
-provides more details on managing a {{site.base_gateway}}.
-* Learn about modifying incoming JSON requests with no code by using the
-[request-transformer plugin](/gateway/latest/understanding-kong/how-to/request-transformations).
-
diff --git a/src/gateway/kong-production/upgrade-enterprise.md b/src/gateway/upgrade/enterprise.md
similarity index 100%
rename from src/gateway/kong-production/upgrade-enterprise.md
rename to src/gateway/upgrade/enterprise.md
diff --git a/src/gateway/kong-production/migrate-ce-to-ke.md b/src/gateway/upgrade/migrate-ce-to-ke.md
similarity index 100%
rename from src/gateway/kong-production/migrate-ce-to-ke.md
rename to src/gateway/upgrade/migrate-ce-to-ke.md
diff --git a/src/gateway/kong-production/upgrade-oss.md b/src/gateway/upgrade/oss.md
similarity index 100%
rename from src/gateway/kong-production/upgrade-oss.md
rename to src/gateway/upgrade/oss.md