From 664f7ba7716e566042f8630532b7b2b6c96a733b Mon Sep 17 00:00:00 2001 From: Michael Heap Date: Thu, 9 Jan 2025 12:49:00 +0000 Subject: [PATCH] Add page on KIC vs Hybrid mode for Kubernetes (#7480) --- app/_data/docs_nav_gateway_3.1.x.yml | 2 + app/_data/docs_nav_gateway_3.10.x.yml | 2 + app/_data/docs_nav_gateway_3.2.x.yml | 2 + app/_data/docs_nav_gateway_3.3.x.yml | 2 + app/_data/docs_nav_gateway_3.4.x.yml | 2 + app/_data/docs_nav_gateway_3.5.x.yml | 2 + app/_data/docs_nav_gateway_3.6.x.yml | 2 + app/_data/docs_nav_gateway_3.7.x.yml | 2 + app/_data/docs_nav_gateway_3.8.x.yml | 2 + app/_data/docs_nav_gateway_3.9.x.yml | 2 + .../deployment-topologies/kubernetes.md | 52 +++++++++++++++++++ 11 files changed, 72 insertions(+) create mode 100644 app/_src/gateway/production/deployment-topologies/kubernetes.md diff --git a/app/_data/docs_nav_gateway_3.1.x.yml b/app/_data/docs_nav_gateway_3.1.x.yml index 779317b09ce8..f4df7b4155aa 100644 --- a/app/_data/docs_nav_gateway_3.1.x.yml +++ b/app/_data/docs_nav_gateway_3.1.x.yml @@ -81,6 +81,8 @@ items: items: - text: Overview url: /production/deployment-topologies/ + - text: Kubernetes Topologies + url: /production/deployment-topologies/kubernetes/ - text: Hybrid Mode items: - text: Overview diff --git a/app/_data/docs_nav_gateway_3.10.x.yml b/app/_data/docs_nav_gateway_3.10.x.yml index a601949b5433..752af48aa503 100644 --- a/app/_data/docs_nav_gateway_3.10.x.yml +++ b/app/_data/docs_nav_gateway_3.10.x.yml @@ -143,6 +143,8 @@ items: items: - text: Overview url: /production/deployment-topologies/ + - text: Kubernetes Topologies + url: /production/deployment-topologies/kubernetes/ - text: Hybrid Mode items: - text: Overview diff --git a/app/_data/docs_nav_gateway_3.2.x.yml b/app/_data/docs_nav_gateway_3.2.x.yml index 3344a20ed815..af0f4911b4a5 100644 --- a/app/_data/docs_nav_gateway_3.2.x.yml +++ b/app/_data/docs_nav_gateway_3.2.x.yml @@ -83,6 +83,8 @@ items: items: - text: Overview url: /production/deployment-topologies/ + - text: Kubernetes Topologies + url: /production/deployment-topologies/kubernetes/ - text: Hybrid Mode items: - text: Overview diff --git a/app/_data/docs_nav_gateway_3.3.x.yml b/app/_data/docs_nav_gateway_3.3.x.yml index da3c9681f986..84ab5b0b7f86 100644 --- a/app/_data/docs_nav_gateway_3.3.x.yml +++ b/app/_data/docs_nav_gateway_3.3.x.yml @@ -87,6 +87,8 @@ items: items: - text: Overview url: /production/deployment-topologies/ + - text: Kubernetes Topologies + url: /production/deployment-topologies/kubernetes/ - text: Hybrid Mode items: - text: Overview diff --git a/app/_data/docs_nav_gateway_3.4.x.yml b/app/_data/docs_nav_gateway_3.4.x.yml index ff4b411f8e3d..c4b71f3a49c8 100644 --- a/app/_data/docs_nav_gateway_3.4.x.yml +++ b/app/_data/docs_nav_gateway_3.4.x.yml @@ -138,6 +138,8 @@ items: items: - text: Overview url: /production/deployment-topologies/ + - text: Kubernetes Topologies + url: /production/deployment-topologies/kubernetes/ - text: Hybrid Mode items: - text: Overview diff --git a/app/_data/docs_nav_gateway_3.5.x.yml b/app/_data/docs_nav_gateway_3.5.x.yml index f04a26b9c510..79ab821c70b9 100644 --- a/app/_data/docs_nav_gateway_3.5.x.yml +++ b/app/_data/docs_nav_gateway_3.5.x.yml @@ -137,6 +137,8 @@ items: items: - text: Overview url: /production/deployment-topologies/ + - text: Kubernetes Topologies + url: /production/deployment-topologies/kubernetes/ - text: Hybrid Mode items: - text: Overview diff --git a/app/_data/docs_nav_gateway_3.6.x.yml b/app/_data/docs_nav_gateway_3.6.x.yml index ac864c29547a..127a245f375b 100644 --- a/app/_data/docs_nav_gateway_3.6.x.yml +++ b/app/_data/docs_nav_gateway_3.6.x.yml @@ -139,6 +139,8 @@ items: items: - text: Overview url: /production/deployment-topologies/ + - text: Kubernetes Topologies + url: /production/deployment-topologies/kubernetes/ - text: Hybrid Mode items: - text: Overview diff --git a/app/_data/docs_nav_gateway_3.7.x.yml b/app/_data/docs_nav_gateway_3.7.x.yml index 645571da71cb..4a74714ddbde 100644 --- a/app/_data/docs_nav_gateway_3.7.x.yml +++ b/app/_data/docs_nav_gateway_3.7.x.yml @@ -141,6 +141,8 @@ items: items: - text: Overview url: /production/deployment-topologies/ + - text: Kubernetes Topologies + url: /production/deployment-topologies/kubernetes/ - text: Hybrid Mode items: - text: Overview diff --git a/app/_data/docs_nav_gateway_3.8.x.yml b/app/_data/docs_nav_gateway_3.8.x.yml index 134eea0966be..97017539862a 100644 --- a/app/_data/docs_nav_gateway_3.8.x.yml +++ b/app/_data/docs_nav_gateway_3.8.x.yml @@ -143,6 +143,8 @@ items: items: - text: Overview url: /production/deployment-topologies/ + - text: Kubernetes Topologies + url: /production/deployment-topologies/kubernetes/ - text: Hybrid Mode items: - text: Overview diff --git a/app/_data/docs_nav_gateway_3.9.x.yml b/app/_data/docs_nav_gateway_3.9.x.yml index dc89ad417da4..386e0455a3ce 100644 --- a/app/_data/docs_nav_gateway_3.9.x.yml +++ b/app/_data/docs_nav_gateway_3.9.x.yml @@ -145,6 +145,8 @@ items: items: - text: Overview url: /production/deployment-topologies/ + - text: Kubernetes Topologies + url: /production/deployment-topologies/kubernetes/ - text: Hybrid Mode items: - text: Overview diff --git a/app/_src/gateway/production/deployment-topologies/kubernetes.md b/app/_src/gateway/production/deployment-topologies/kubernetes.md new file mode 100644 index 000000000000..ba384d99f7dc --- /dev/null +++ b/app/_src/gateway/production/deployment-topologies/kubernetes.md @@ -0,0 +1,52 @@ +--- +title: Kubernetes Topologies +content_type: explanation +--- + +Running {{ site.base_gateway }} on Kubernetes is a common deployment pattern. When running on Kubernetes, there are two configuration options available: + +* [Hybrid mode](#hybrid-mode), with a CP (either on-prem or via Konnect) and multiple DPs +* [DB-less mode](/gateway/{{ page.release }}/production/deployment-topologies/db-less-and-declarative-config/), configured using CRDs and the {{ site.kic_product_name }} + +Running Kong in Hybrid mode is commonly referred to as "Kong _on_ Kubernetes". Running Kong with {{ site.kic_product_name }} is commonly referred to as "Kong _for_ Kubernetes", as it provides a Kubernetes native way of configuring Kong entities using {{ site.kic_product_name }}. + +{:.note} +> You can also use {{ site.kic_product_name }} to configure a Hybrid mode deployment. This should only be used in a small set of circumstances. We recommend using Hybrid mode without KIC, or DB-less mode with KIC, unless you've been otherwise advised by a member of the Kong team. + +## Hybrid mode + +Deploying {{ site.base_gateway }} in [Hybrid mode](/gateway/{{ page.release }}/production/deployment-topologies/hybrid-mode/) uses Kubernetes as a runtime for your data planes. + +Configuring Kong on Kubernetes is identical to deploying Kong running on a virtual machine or bare metal. The Data Planes connect to a Control Plane (Konnect, or an in-cluster control plane) and receive configuration from the CP. Configuration is managed using the UI, the Kong Admin API or via [deck](/deck/latest/). + +We provide detailed [installation instructions](/gateway/{{ page.release }}/install/kubernetes/proxy/) for Hybrid mode, including ingress definitions for EKS, GKE and AKS. + +## DB-less mode with {{ site.kic_product_name }} + +{{ site.kic_product_name }} provides a Kubernetes native way to configure {{ site.base_gateway }} using custom resource definitions (CRDs). In this deployment pattern, {{ site.base_gateway }} is deployed in DB-less mode, where the data plane configuration is held in memory. + +Operators configure {{ site.base_gateway }} using standard CRDs such as `Ingress` and `HTTPRoute`, and {{ site.kic_product_name }} translates those resources in to Kong entities before sending a request to update the running data plane configurations. + +In this topology, the Kubernetes API server is your source of truth. {{ site.kic_product_name }} reads resources stored on the API server and translates them in to a valid Kong configuration object. You can think of {{ site.kic_product_name }} as the control plane for your DB-less data planes. + +For more information about {{ site.base_gateway }} and {{ site.kic_product_name }}, see the {{ site.kic_product_name }} [getting started guide](/kubernetes-ingress-controller/latest/get-started/). This guide walks you through installing {{ site.base_gateway }}, configuring a service and route, then adding a rate limiting and caching plugin to your deployment. + +## Deciding which to use + +Both topologies are supported by Kong, and deciding between the two options depends on your team's capabilities. + +If you're a Kubernetes-native company who are comfortable managing CRDs and have pre-existing workflows around Kubernetes resources, we recommend using {{ site.kic_product_name }} to manage your deployment. {{ site.kic_product_name }} can be attached to Konnect to provide visibility in to the generated configuration and live traffic through analytics. + +If your team is not familiar with CRDs, or you're migrating an existing configuration from bare metal machines or VMs to Kubernetes, you should choose Hybrid mode. In this topology, Kubernetes is a place to run your data planes and nothing more. There are no CRDs to learn, no Ingress Controller to maintain and update. All configuration is stored in the control plane and send to data planes using the Hybrid mode protocol. + +
+ + +
Choose Hybrid Mode
+ + + + +
Choose {{ site.kic_product_name }}
+ +
\ No newline at end of file