feat(mesh): Mesh v3 scenarios by lmilan · Pull Request #7184 · Kong/developer.konghq.com

lmilan · 2026-09-09T16:06:22Z

Description

Preview Links

How-tos

Guidelines for scenario updates

Use the release PR for reference about the v3 docs structure: WIP: Release/mesh 3 #7176
Use the style guide (app/contributing/style-guide.md)
How-to guides should be under app/_how-tos/mesh and reference docs under app/mesh
Add new includes under app/_includes/md/mesh/v3
For how-tos:
- Don't omit any prerequisites, a how-to should contain all the steps needed to run the example, and each step should be a copy-pastable command (unless it's a UI step)
- Avoid documenting multiple ways to do the same thing as separate steps in the same how-to, either split the how-to, or pick one way and add the other as an FAQ
- Don't add too much reference information in how-to guides, link to reference pages instead
- Avoid using placeholders, and don't use variables that haven't been declared
- When a how-to builds on another one, create a series

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).

don't inherit pages from the kuma repo

…ause we" This reverts commit d973067248730acf5d68c48d3ff4ed7aa364c94d.

app/mesh/v2/sbom.md, upgrade.md, and validated-versions.md are evergreen but were still preseint in the v2 release map, so ReleaseMapLoader aborted every build with "No page found".

site.data.mesh_latest.version is the newest release across all majors, so every /mesh/v2/ page rendered 3.0.0 after the 3.0 cut. Replace it with a value scoped to the page's major: - how-tos use page.latest_release.version (2.14.3) - reference pages use page.release.version, set by ReferencePages::Versioner - app/mesh/sbom.md keeps site.data.mesh_latest.version, it is evergreen Both latest_version.html endpoints now declare content_type: reference so Versioner reaches them. They also need no_wrap, because content_type: reference triggers the section wrapper. Drops::Release gains #version for the patch number. MinVersion now sets latest_release before the min_version guard, because the major alone resolves it; two how-tos that render the kumactl prereq declare no min_version.

The v2 pages pulled includes from shared, unversioned paths, so a mesh 3 edit to any of them would silently change the version 2 snapshot. Move all 33 mesh includes to md/mesh/v2/, the layout the ai-gateway cut established (md/<product>/<segment>/). Every user of every moved file is a /v2/ page, so no evergreen page is affected. Drop the now-redundant product prefix from the basenames, e.g. faqs/mesh-zone-authentication -> md/mesh/v2/faqs/zone-authentication. Two includes also pointed at the evergreen installer. Both now use /mesh/v2/installer.sh, and deploy-zone-cp-universal moves from http to https. Left in place: prereqs/mesh.md, which has no users at all, and support/mesh.md, whose user is the evergreen support-policy page.

/mesh/policies/*/ are left alone. The generated policy pages have no v2 snapshot at all, which is recorded as a follow-up.

These need a description and title and update app/_headers so that it also handles /mesh/v2/latest_version gracefully

we start the server with ---skip-wait-port

from the subrepo

The shared overview and reference address builders, and the mesh, AI Gateway and Event Gateway page classes, now take the policy so a later change can vary the address by policy major. AI Gateway and Event Gateway still ignore the argument; every generated address is unchanged.

The mesh policy generator now discovers a policy set at the top level of the mesh policy source folder plus one policy set per version subfolder, deriving the policy major from the folder name. Release resolution, addresses, breadcrumbs, the policy lookup table and the policy tag are all policy-major aware, and the version segment comes from the product data template rather than a hardcoded value. No policy has moved yet, so the live site output is unchanged.

All 22 mesh policies move into the v2 policy set, keeping their bodies, examples and version constraints untouched. A new major-2 hub page lists them, and the dropped external-services policy's old address redirects to its v2 address. The missing-redirects tool now strips the version subfolder when building a mesh policy address, and the generator seeds the current-major alias so the (now empty) current hub renders without error.

Each mesh* policy gets a frontmatter-only stub at the top level of app/_mesh_policies, carrying every field from its v2 source except min_version, which named a 2.x release and has no meaning inside major 3. external-services stays major-2-only, since 3.0 drops it. Mesh writers fill in prose and examples later; the generator and the current-major hub already render placeholders correctly once the frontmatter exists. A spec locks in that the examples redirect builder already skips a policy with no examples, so no line is emitted for these until they gain examples.

19 of the 22 major-2 policies link to other mesh pages with no version segment, so those links now resolve against major-3 content. Every /mesh/... link in the major-2 policy bodies, frontmatter related resources, and example files gains the v2 segment, so a major-2 reader stays in major 2.

Major-2 prose and how-to pages link to policy addresses with no version segment, so a major-2 reader following one of those links lands on major-3 policy documentation instead. Every /mesh/policies/... link, including the hub link and the legacy health-check alias, now carries the v2 segment and resolves inside the major-2 policy set.

Add a major-2 documentation index that mirrors the mesh index with every mesh address given the v2 segment, declares the policy major, and points canonically back at the mesh index. Reduce the mesh index to its title and description until major-3 pages land. Guard the index generator against a missing groups key so a sectionless index still renders.

…rom v2 folder Read each v2 mesh policy's major from a hardcoded major_version frontmatter key instead of parsing it out of the v2 folder name, for consistency with how every other policy fact lives in frontmatter. The v2 folder stays for organization only; the generator still recurses into it, but no longer uses its name to compute the major.

evergreen ones

references to it

Even though reference pages don't have a source file, the pages are generated with a dummy value set to its relative_path. Adding the entries in the app/_config/releases file will set the right canonical_url to them.

specific order

post_processor, both the links and the toc are generated correctly

netlify · 2026-09-09T16:06:31Z

✅ Deploy Preview for kongdeveloper ready!

Name	Link
🔨 Latest commit	`49b4ef1`
🔍 Latest deploy log	https://app.netlify.com/projects/kongdeveloper/deploys/6ab64a0483479500097d2592
😎 Deploy Preview	https://deploy-preview-7184--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.

fabianrbz added 30 commits September 9, 2026 13:55

chore(mesh): remove copy_mesh_assets we no longer need it because we

3f01fac

don't inherit pages from the kuma repo

chore(mesh): run major-version-cut skill

4e771d3

chore(mesh): remove pages, they'll be written from scracth

77a5d5e

chore(mesh): add dummy release

946a28c

chore(mesh): add redirects to v2 pages

fe70218

Revert "chore(mesh): remove copy_mesh_assets we no longer need it bec…

5207b6d

…ause we" This reverts commit d973067248730acf5d68c48d3ff4ed7aa364c94d.

chore(mesh): add v2 installers

8b8665c

chore(mesh): update installer.sh references in v2 pages

0638d2d

chore(mesh): make 3.0 latest

2a0ecb6

fix(mesh): remove pages that should be evergreen

e0c3ad4

fix(mesh): bring back some pages that should be evergreen

f66cecf

fix(mesh): remove stale v2 release map entries

b75690d

app/mesh/v2/sbom.md, upgrade.md, and validated-versions.md are evergreen but were still preseint in the v2 release map, so ReleaseMapLoader aborted every build with "No page found".

fix(mesh): point v2 include links at the v2 pages

6cabd5f

/mesh/policies/*/ are left alone. The generated policy pages have no v2 snapshot at all, which is recorded as a follow-up.

test(mesh): avoid a leaked constant in the MinVersion spec

37dc5da

fix(mesh): update mesh/latest_version

41853d3

These need a description and title and update app/_headers so that it also handles /mesh/v2/latest_version gracefully

fix(mesh): remove unneeded redirects, those pages are evergreen

3be6cae

fix: use memoized variable

4af67d8

fix(chrome): links to evergreen urls

4a36192

fix(makefile): redirects locally, they weren't being picked up because

531c01a

we start the server with ---skip-wait-port

refactor(mesh): copy cpinstall, refactor it and don't load some plugins

cdad8bd

from the subrepo

fix(mesh): nested kuma tabs in markdown mode

1b4a6e4

fabianrbz and others added 20 commits September 9, 2026 13:55

fix(mesh): remove wrong file in mesh releases

b599a95

chore(mesh): add canonical urls to mesh policies v2

0652148

fix(mesh): exclude policy reference pages from /index/mesh/v2/

9ac171a

fix(mesh): links to policies

de21691

fix(mesh): links in mesh/v2 should point to v2 pages except for the

1f93278

evergreen ones

fix(mesh): broken links that used relative paths

e977f87

test(mesh): Refactor some method names and add specs

4b1f8c3

fix(mesh): /mesh/validated-versions/ is an evergreen url, update all

52632d8

references to it

chore(mesh): refactor mesh policies hub (latest and v2)

aa3daef

refactor(generators): orchestrate the generator so they run in a

1fde93d

specific order

fix(mesh): fix include after rebase

ddef9c2

refactor(mesh): policy_yaml tag

6044dd7

fix(mesh): remove changelog v2

6fbccb3

fix(mesh): we no longer need to pass this page through the

8d0b20c

post_processor, both the links and the toc are generated correctly

fix(gh-action): install all dependencies before running rpsec

c4218ed

make vale happy

84edade

fix(mesh): add policy examples redirects

a46e809

migrate scenarios

07b8307

lmilan self-assigned this Sep 9, 2026

lmilan requested a review from a team as a code owner September 9, 2026 16:06

lmilan linked an issue Sep 9, 2026 that may be closed by this pull request

Mesh: Migrate scenarios to v3 docs #7117

Closed

lmilan marked this pull request as draft September 9, 2026 16:25

WIP for scenarios update

4d1507d

lmilan mentioned this pull request Sep 17, 2026

feat(mesh): Scenarios #4346

Closed

7 tasks

fabianrbz force-pushed the release/mesh-3 branch from 1e9bfde to d41c003 Compare September 21, 2026 15:44

justindavies added 2 commits September 23, 2026 17:28

Interim v3 commit of scenario based docs

5a1f3a5

Technical review of scenarios complete

49b4ef1

Navigation Menu

feat(mesh): Mesh v3 scenarios - #7184

feat(mesh): Mesh v3 scenarios#7184
lmilan wants to merge 56 commits into
release/mesh-3from
feat/migrate-scenarios

lmilan commented Sep 9, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Sep 9, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

lmilan commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Preview Links

Landing and index

Concepts

Personas

How-tos

Guidelines for scenario updates

Checklist

Uh oh!

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

Uh oh!

✅ Deploy Preview for kongdeveloper ready!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lmilan commented Sep 9, 2026 •

edited

Loading

netlify Bot commented Sep 9, 2026 •

edited

Loading