feat(mesh): Scenarios by justindavies · Pull Request #4346 · Kong/developer.konghq.com

justindavies · 2026-02-26T01:58:37Z

Description

New scenario based docs for Mesh

Preview Links

https://deploy-preview-4346--kongdeveloper.netlify.app/mesh/scenarios/

Checklist

Tested how-to docs. If not, note why here.
All pages contain metadata.
Any new docs link to existing docs.
All autogenerated instructions render correctly (API, decK, Konnect, Kong Manager).
Style guide (capitalized gateway entities, placeholder URLs) implemented correctly.
Every page has a description entry in frontmatter.
Add new pages to the product documentation index (if applicable).

netlify · 2026-02-26T01:58:42Z

✅ Deploy Preview for kongdeveloper ready!

Name	Link
🔨 Latest commit	`d85a453`
🔍 Latest deploy log	https://app.netlify.com/projects/kongdeveloper/deploys/6a3ab1f3cf07a800085f1db4
😎 Deploy Preview	https://deploy-preview-4346--kongdeveloper.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

Copilot

Pull request overview

Adds a new “Scenarios / Learning Path” documentation track for Kong Mesh, including foundational concepts, practical how-tos, persona-based guides, and navigation updates so the new content is discoverable from the Mesh landing page and docs index.

Changes:

Introduces a full set of scenario-based Mesh docs (learning path, hands-on scenarios, and persona guides).
Adds/updates navigation and discovery entries for the new scenarios content in the Mesh landing page and Mesh docs index.
Expands scenario coverage to include identity/trust, multi-zone ops, traffic management, observability, perimeter security, and migration guidance.

Reviewed changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
app/mesh/scenarios/workload-identity.md	New scenario doc covering Workload Identity model (`MeshIdentity`, `MeshTrust`, `MeshTLS`).
app/mesh/scenarios/using-policies.md	New scenario doc explaining TargetRef policy structure, hierarchy, and flows.
app/mesh/scenarios/traffic-splitting-meshservices.md	New scenario doc demonstrating weighted routing with explicit `MeshService` resources.
app/mesh/scenarios/subsets-and-targeting.md	New scenario doc comparing `MeshSubset` vs explicit `MeshService` targeting.
app/mesh/scenarios/resource-scoping.md	New foundational doc explaining Global vs Zone CP ownership and K8s namespace rules.
app/mesh/scenarios/persona/security.md	Persona guide focused on zero-trust, authorization, and governance.
app/mesh/scenarios/persona/operator.md	Persona guide focused on multi-zone infra, gateways, and observability ops.
app/mesh/scenarios/persona/index.md	Persona landing page linking to persona deep dives.
app/mesh/scenarios/persona/developer.md	Persona guide focused on routing, resilience, observability, and gateway integration.
app/mesh/scenarios/observability-in-practice.md	New scenario doc for metrics/tracing/logging with Mesh policies and bundled stack.
app/mesh/scenarios/multi-zone-architecture.md	New scenario doc describing multi-zone components and service federation.
app/mesh/scenarios/multi-tenancy-strategies.md	New scenario doc explaining soft vs hard multi-tenancy models.
app/mesh/scenarios/meshexternalservice.md	New scenario doc for first-class external dependencies via `MeshExternalService`.
app/mesh/scenarios/mesh-proxy-patch.md	New scenario doc for advanced Envoy patching using `MeshProxyPatch`.
app/mesh/scenarios/mesh-passthrough.md	New scenario doc for perimeter control using `MeshPassthrough`.
app/mesh/scenarios/kong-mesh-vs-ambient.md	New comparison doc: Kong Mesh sidecar model vs Istio Ambient trade-offs.
app/mesh/scenarios/istio-to-kong-mesh.md	New migration guide doc mapping concepts and outlining migration approach.
app/mesh/scenarios/introduction.md	New scenarios track introduction and roadmap framing.
app/mesh/scenarios/ingress-mtls-bridge.md	New scenario doc describing ExternalName bridge pattern for gateway-to-mesh mTLS.
app/mesh/scenarios/index.md	New Learning Path index organizing scenarios into phases.
app/mesh/scenarios/global-color-routing.md	New scenario doc for cross-zone “color” affinity routing with MMZS + routes.
app/mesh/scenarios/global-canary-releases.md	New scenario doc for zone-scoped canary rollouts with cross-region failover.
app/mesh/scenarios/getting-started-policy.md	New starter scenario for enabling mTLS and introducing default deny + targeted allow.
app/mesh/scenarios/external-ca-vault.md	New scenario doc for external CA integration (Vault, cert-manager, ACM, MeshIdentity).
app/mesh/scenarios/chaos-engineering.md	New scenario doc for validating resilience using `MeshFaultInjection`.
app/mesh/scenarios/architecture-overview.md	New architectural overview doc (CP/DP, multi-zone, key resources).
app/_landing_pages/mesh.yaml	Adds a featured learning-path card and new CTAs to surface scenarios content.
app/_indices/mesh.yaml	Adds scenarios and persona guides into the Mesh documentation index.

You can also share your feedback on Copilot code review. Take the survey.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…er.konghq.com into kong-mesh-scenarios

lobkovilya · 2026-03-04T10:40:53Z

+
+* **Dataplane (DP)**: The sidecar component that runs alongside your application workload to manage all incoming and outgoing traffic. It provides your service with a secure identity and enforces the networking rules defined by your policies.
+* **Control Plane (CP)**: The authoritative management layer responsible for discovering workloads and distributing configuration updates to every Dataplane in the mesh.
+* **Kuma Distribution Service (KDS)**: The high-speed protocol used to synchronize policies and service state between a **Global CP** and its **Zone CPs**.


Not that it matters too much, but it was originally named Kuma Discovery Service kumahq/kuma#839 :)

It's called like that because it's a generalization of an existing Envoy xDS protocol, stands for X Discovery Service.

lobkovilya · 2026-03-04T10:50:38Z

+
+---
+
+## {{site.mesh_product_name}} Architecture


The chart probably can be a bit more rigorous with lines. Initially I thought solid line is a DP traffic and dashed line is a CP traffic, however line between Global CP and Zone CP is solid. Also it would be nice to have a legend

lobkovilya · 2026-03-04T11:01:57Z

+---
+{{site.mesh_product_name}} can be deployed in two main architectures:
+
+### 1. Standalone Mode (Simple)


I'm not sure we should use the term "standalone". We previously had an actual mode called standalone, which was later deprecated, so using the term again might cause confusion.

In the docs, we usually refer to federated and non-federated zones, depending on whether a zone is connected to Global. It makes migrations from non-federated to federated easier https://developer.konghq.com/mesh/federate-zone/ as you don't need to redeploy zone cp in another mode.

lobkovilya · 2026-03-04T11:07:24Z

+Each resource type in {{site.mesh_product_name}} has a defined **owner**: the tier that is authorised to create, modify, and delete it.
+
+{% danger %}
+If you apply a **Global-only** resource to a Zone CP, the resource will be rejected or overwritten when KDS syncs. You may not see an immediate error, making this hard to debug.


Is it indeed the case? IIRC we're not allowing Global only resources to be applied on Zone CP. If it's not true then I'd consider it a bug and wouldn't mention in docs anyway.

lobkovilya · 2026-03-04T11:12:54Z

+
+| Resource | Namespace |
+| :--- | :--- |
+| `Mesh` | Applied to Global CP (any ns or CRD) |


TBH, I wouldn’t even mention in this doc that it’s possible to deploy the Global CP as a Kubernetes-native deployment that uses etcd and CRDs. For simplicity, and because it likely covers the overwhelming majority of use cases, the Global CP is typically a regular deployment backed by a PostgreSQL database.

If you still want to mention it, note that you can’t use arbitrary namespaces or CRDs. Only the system namespace is supported.

Automaat · 2026-03-05T08:40:45Z

+```
+
+{% tip %}
+Ollie often uses **`MeshSubset`** at the top level of his policies to target entire zones or environments without needing to list every service individually. Learn more in the [Subsets & Targeting Guide](/mesh/scenarios/subsets-and-targeting/).


We dont use MeshSubset in top level anymore. it should be Dataplane

Automaat · 2026-03-05T08:44:51Z

+---
+{{site.mesh_product_name}} is an enterprise-grade service mesh that provides a unified control plane to manage services across Kubernetes, VMs, and bare metal. Unlike traditional meshes that require complex, platform-specific configurations, {{site.mesh_product_name}} offers a simplified, policy-driven approach that works identically regardless of your underlying infrastructure.
+
+## The Kong Air Journey


We should link to actual Kong Air intro if there is any, and it would be nice to have some simple diagram here to show components of Kong Air

Automaat · 2026-03-05T08:53:45Z

+
+## {{site.mesh_product_name}} Architecture
+
+{% mermaid %}


For me this graph is too complex, It would be better to split this into two graphs, one high level overview and second one with detailed zone components

Automaat · 2026-03-05T08:56:31Z

+
+Because AeroPay is now a first-class citizen, Devin (the Developer) can apply standard mesh policies to it. If AeroPay is momentarily slow or returns a 5xx error, the mesh can automatically retry.
+
+```yaml


this whole policy is incorrect. It looks like it was halucinated ;) We need to use MeshRetry policy here. And it cannot be applied to route.

Automaat · 2026-03-05T09:01:01Z

+### Predictable DNS with HostnameGenerators
+To avoid messy auto-generated names, Devin uses a **HostnameGenerator** to create a standard naming scheme for the airline.
+
+```yaml


examples in personas docs should also cover k8s/univeral examples as other docs do

Automaat · 2026-03-05T09:04:14Z

+  - mesh
+---
+
+Devin is a Senior Software Engineer at **Kong Air**. He is responsible for the **Ticket Booking** ecosystem. His goal is to build a high-performance, resilient booking platform that handles millions of searches while integrating safely with external partners.


again it would be nice to link to actual kong air

Automaat · 2026-03-05T09:04:57Z

+
+Devin needs his services to be reachable by beautiful, predictable DNS names, regardless of which cloud or zone they are running in.
+
+### Predictable DNS with HostnameGenerators


on kuberenetes this is not needed and kubernetes addresses could be used

Also, I dont think that creating hostnameGenerator is part of SE concern. It should be probably done be mesh operator

Automaat · 2026-03-05T09:05:36Z

+kind: HostnameGenerator
+metadata:
+  name: kong-air-dns
+  namespace: {{site.mesh_system_namespace}}


this namespace renders empty on preview

Automaat · 2026-03-05T09:10:10Z

+  - mesh
+---
+
+Devin is a Senior Software Engineer at **Kong Air**. He is responsible for the **Ticket Booking** ecosystem. His goal is to build a high-performance, resilient booking platform that handles millions of searches while integrating safely with external partners.


It would be nice to use some specific mesh name, like kong-air-mesh in this doc, and reference it in all examples

Automaat · 2026-03-05T09:14:04Z

+  - mesh
+---
+
+Devin is a Senior Software Engineer at **Kong Air**. He is responsible for the **Ticket Booking** ecosystem. His goal is to build a high-performance, resilient booking platform that handles millions of searches while integrating safely with external partners.


Is Devin responsible for whole Kong Air or only some parts of it?

It would be nice to start this with a diagram what we have and what devin is responsible for. We should assume that people reding this does not understand hhow Kong Air works

Automaat · 2026-03-05T09:18:59Z

+kind: MeshHTTPRoute
+spec:
+  targetRef:
+    kind: MeshService


we should have Dataplane in top level target ref

Co-authored-by: Marcin Skalski <skalskimarcin33@gmail.com>

lmilan · 2026-09-17T09:49:40Z

@justindavies Can we close this since we have a the Mesh 3 PR?

Initial commit for Angel

bc98b75

justindavies requested a review from a team as a code owner February 26, 2026 01:58

Fix linting

440fe7a

Copilot AI review requested due to automatic review settings March 4, 2026 03:46

Copilot started reviewing on behalf of justindavies March 4, 2026 03:46 View session

Copilot AI reviewed Mar 4, 2026

View reviewed changes

justindavies and others added 8 commits March 3, 2026 19:55

more lintining errors

41661c4

Update app/mesh/scenarios/observability-in-practice.md

4edf8ef

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Apply suggestions from code review

3840b23

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

fix https

8b00b0c

Merge branch 'kong-mesh-scenarios' of https://github.com/Kong/develop…

1882160

…er.konghq.com into kong-mesh-scenarios

Fix {{}}

0213376

final vale fixes

73fa2c9

Update meshexternalservice.md

7d9da6c

lobkovilya reviewed Mar 4, 2026

View reviewed changes

Automaat reviewed Mar 5, 2026

View reviewed changes

Comment thread app/mesh/scenarios/index.md Outdated

Automaat reviewed Mar 5, 2026

View reviewed changes

Comment thread app/mesh/scenarios/index.md Outdated

Automaat reviewed Mar 5, 2026

View reviewed changes

Update app/mesh/scenarios/index.md

3dc5c1d

Co-authored-by: Marcin Skalski <skalskimarcin33@gmail.com>

Update app/mesh/scenarios/index.md

0decc74

Co-authored-by: Marcin Skalski <skalskimarcin33@gmail.com>

lmilan self-assigned this Mar 30, 2026

lmilan changed the title ~~Initial commit for Angel~~ feat(mesh): Scenarios Mar 30, 2026

lmilan added the product:mesh label Mar 30, 2026

justindavies added 3 commits May 27, 2026 14:35

interim testing for 2.13 -> 3.0

86b94ab

Initial review for @lmilan

5365e47

updates

d85a453

lmilan mentioned this pull request Sep 3, 2026

Mesh: Migrate scenarios to v3 docs #7117

Closed

justindavies closed this Sep 17, 2026


		Because AeroPay is now a first-class citizen, Devin (the Developer) can apply standard mesh policies to it. If AeroPay is momentarily slow or returns a 5xx error, the mesh can automatically retry.

		```yaml


		Devin needs his services to be reachable by beautiful, predictable DNS names, regardless of which cloud or zone they are running in.

		### Predictable DNS with HostnameGenerators

Conversation

justindavies commented Feb 26, 2026 • edited by lmilan Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Preview Links

Checklist

Uh oh!

netlify Bot commented Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for kongdeveloper ready!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lmilan commented Sep 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

justindavies commented Feb 26, 2026 •

edited by lmilan

Loading

netlify Bot commented Feb 26, 2026 •

edited

Loading