Install guide for ambient multi network #16709

jaellio · 2025-07-28T23:34:42Z

Description

@keithmattix and Mitch Conners are the current owners of this PR

PR is now ready for review

Reviewers

istio-testing · 2025-07-28T23:34:44Z

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

istio-policy-bot · 2025-07-28T23:34:46Z

😊 Welcome! This is either your first contribution to the Istio documentation repo, or
it's been a while since you've been here. A few things you should know:

You can learn about how we write and maintain documentation, our style guidelines,
and the available web site features by visiting Contributing to the Docs.
In the next few minutes, an automatic preview of your change will be built with
a full copy of the istio.io website. You can find this preview by clicking on
the Details link next to the deploy/netlify entry in the status section of this
page.
We care about quality, so we've put in place a number of checks to ensure our documentation
is top-notch. We do spell checking, sanitize the Markdown, ensure all hyperlinks point to a
valid location, and more. If your PR doesn't pass one of these checks, you'll see a red X in the
lint_istio.io entry in the status section. Click on the Details link to get a list of the
problems with your PR. Fix those problems and push an update; this will automatically re-run the
tests. Hopefully this time everything will be perfect!
Once your changes are accepted and merged into the repository, they will initially show up
on https://preliminary.istio.io. The changes will be published to https://istio.io
the next time we do a major release (which typically happens every 3 months or so).
To publish them sooner, add a cherrypick/release-x.xx label, where x.xx is the current
release of Istio.

Thanks for contributing!

Courtesy of your friendly welcome wagon.

content/en/docs/ambient/install/multicluster/_index.md

content/en/docs/ambient/install/multicluster/index.md

content/en/docs/ambient/install/multicluster/multi-primary_multi-network/index.md

Stevenjin8 · 2025-08-04T16:08:29Z

content/en/docs/ambient/install/multicluster/_index.md

+
+Currently, ambient multicluster **only supports**:
+- **Multi-network topologies** with multiple primary clusters
+- **Double HBONE encapsulation** for cross-cluster traffic


Sorry I'm a bit late to the party.

Multi-network topologies with multiple primary clusters

More accurately, each cluster has to be a primary cluster (have its own istiod). If you have 10 clusters but only two primary cluster, then you would have "multiply primary clusters" but this topology would not be supported.

Double HBONE encapsulation for cross-cluster traffic

Can we configure the this at all? is there any way for someone to try any other inner/outer tunnel protocol configuration. If not, then I think we can omit this.

More accurately, each cluster has to be a primary cluster (have its own istiod). If you have 10 clusters but only two primary cluster, then you would have "multiply primary clusters" but this topology would not be supported.

Totally agree - good clarification

Can we configure the this at all? is there any way for someone to try any other inner/outer tunnel protocol configuration. If not, then I think we can omit this.

Even if we don't support other configurations, it might be good to explicitly clarify we currently don't support protocols other than double hbone. I could be convinced either way.

I took a stab at rewording; let me know your thoughts

Stevenjin8 · 2025-08-04T16:09:20Z

content/en/docs/ambient/install/multicluster/_index.md

+Currently, ambient multicluster **only supports**:
+- **Multi-network topologies** with multiple primary clusters
+- **Double HBONE encapsulation** for cross-cluster traffic
+- **Universal waypoint deployments** across all clusters with identical names


waypoint deployment or configuration? You don't have to deploy waypoints in all clusters, but maybe we do want to require this to avoid confusion.

If a service is using a waypoint does it have to have one locally available (as well as globally)?

Yes, but the services also have the same waypoints across clusters

I guess we talk about it later

Stevenjin8 · 2025-08-04T16:11:30Z

content/en/docs/ambient/install/multicluster/_index.md

+  - Waypoint configurations must be synchronized manually across clusters
+  - Traffic routing relies on consistent waypoint naming conventions
+
+#### Service Visibility and Scoping


The locality of services with waypoints is also confusing and worth mentioning. Like if service is local, but its waypoint service is labeled as global, then it is global.

Hmm, this makes sense when I think of the implementation, but it's probably something to make an adjustment to in beta (/cc @therealmitchconnors @krinkinmu)

content/en/docs/ambient/install/multicluster/verify/index.md

Stevenjin8 · 2025-08-04T16:24:41Z

content/en/docs/ambient/install/multicluster/verify/index.md

+
+## Deploy the `HelloWorld` Service
+
+In order to make the `HelloWorld` service callable from any cluster, the DNS


TECHNICALLY, kubernetes also allows you to do service discovery though environment variables (crazy). But I think that mentioning DNS distracts from the point a bit. I think its more like, we want to create a helloworld service that we're eventually going to use to csend cross-cluster traffic. To start, we need to create the service in each cluster

I like the reference to the DNS doc though because it's important consideration for anyone trying to do multicluster (I remember stumbling through this when I first gave it a try). The k8s env var service disovery approach only works within single-cluster on the namespace, so I think this belongs

content/en/docs/ambient/install/multicluster/multi-primary_multi-network/index.md

linux-foundation-easycla · 2025-08-06T16:54:33Z

The committers listed above are authorized under a signed CLA.

✅ login: jaellio / name: Jackie Maertens (Elliott) (f7b85b5)
✅ login: keithmattix / name: Keith Mattix II (5e2f61c, 747d470, 26f2bec, 68058c4, 3a3b262, 1a1ce5b, e6b080d, 2455bd0, 4d41a25, caab262, c7444e7)

content/en/docs/ambient/install/multicluster/_index.md

craigbox · 2025-08-11T10:25:38Z

content/en/docs/ambient/install/multicluster/before-you-begin/index.md

+Before you begin a multicluster installation, review the
+[deployment models guide](/docs/ops/deployment/deployment-models)
+which describes the foundational concepts used throughout this guide.


Will sending people to the sidecar version of the doc confuse them?

IIUC, the link isn't a sidecar specific doc; in theory, ambient can support all of the deployment models listed there.

content/en/docs/ambient/install/multicluster/verify/index.md

go.mod

craigbox · 2025-08-11T10:31:44Z

scripts/lint_site.sh

@@ -95,7 +95,7 @@ check_content() {
        FAILED=1
    fi

-    if grep -nrP --include "*.md" -e "\(https://istio.io/(?!v[0-9]\.[0-9]/|archive/)" .; then
+    if grep -nrP --include "*.md" -e "\(https://istio.io/(?!v[0-9]\.[0-9]/|archive|news/)" .; then


What is this trying to do?

We shouldn't have any content at https://istio.io/news/ any more, which I think is what is being added.

We do link to news in one of these new docs to tell people to check there for updates on the feature status of ambient multi cluster

Should be /latest/news, then, instead of /news.

Doesn't /news redirect to /latest/news? I can update the regex and reference though if that's preferred

please do yes; everything without a /latest/ is a leftover from before we put versioning in the site, rather than having archives on archive.istio.io. Which I still don't understand why we did, but I assume David had a really good reason :)

Gotcha, updated!

.spelling

content/en/docs/ambient/install/multicluster/before-you-begin/index.md

content/en/docs/ambient/install/multicluster/multi-primary_multi-network/index.md

Stevenjin8 · 2025-08-11T14:19:28Z

content/en/docs/ambient/install/multicluster/verify/index.md

+
+Before proceeding, be sure to complete the steps under
+[before you begin](/docs/setup/install/multicluster/before-you-begin) as well as
+choosing and following one of the multicluster installation guides.


some links missing here?

One was incorrect and one was missing. Should be fixed, but I'll try and look through the Netlify preview

content/en/docs/ambient/install/multicluster/verify/index.md

Signed-off-by: Jackie Elliott <[email protected]>

Signed-off-by: Keith Mattix II <[email protected]>

keithmattix · 2025-08-11T17:30:48Z

/test doc.test.profile-default

content/en/docs/ambient/install/multicluster/_index.md

Signed-off-by: Keith Mattix II <[email protected]>

istio-testing · 2025-08-12T22:45:13Z

In response to a cherrypick label: new pull request created: #16776

istio-testing added the do-not-merge/work-in-progress Block merging of a PR because it isn't ready yet. label Jul 28, 2025

istio-policy-bot added area/ambient area/networking kind/docs labels Jul 28, 2025

istio-testing added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Jul 28, 2025

therealmitchconnors reviewed Jul 29, 2025

View reviewed changes

content/en/docs/ambient/install/multicluster/_index.md Outdated Show resolved Hide resolved

therealmitchconnors reviewed Jul 29, 2025

View reviewed changes

content/en/docs/ambient/install/multicluster/_index.md Outdated Show resolved Hide resolved

therealmitchconnors reviewed Jul 29, 2025

View reviewed changes

content/en/docs/ambient/install/multicluster/_index.md Outdated Show resolved Hide resolved

therealmitchconnors reviewed Jul 29, 2025

View reviewed changes

content/en/docs/ambient/install/multicluster/_index.md Outdated Show resolved Hide resolved

therealmitchconnors reviewed Jul 29, 2025

View reviewed changes

content/en/docs/ambient/install/multicluster/index.md Outdated Show resolved Hide resolved

therealmitchconnors reviewed Jul 29, 2025

View reviewed changes

content/en/docs/ambient/install/multicluster/multi-primary_multi-network/index.md Outdated Show resolved Hide resolved

jaellio commented Jul 31, 2025

View reviewed changes

content/en/docs/ambient/install/multicluster/multi-primary_multi-network/index.md Outdated Show resolved Hide resolved

jaellio commented Jul 31, 2025

View reviewed changes

content/en/docs/ambient/install/multicluster/multi-primary_multi-network/index.md Outdated Show resolved Hide resolved

jaellio commented Jul 31, 2025

View reviewed changes

content/en/docs/ambient/install/multicluster/multi-primary_multi-network/index.md Outdated Show resolved Hide resolved

jaellio commented Jul 31, 2025

View reviewed changes

content/en/docs/ambient/install/multicluster/multi-primary_multi-network/index.md Outdated Show resolved Hide resolved

Stevenjin8 reviewed Aug 4, 2025

View reviewed changes

content/en/docs/ambient/install/multicluster/verify/index.md Outdated Show resolved Hide resolved

Stevenjin8 reviewed Aug 4, 2025

View reviewed changes

content/en/docs/ambient/install/multicluster/verify/index.md Show resolved Hide resolved

Stevenjin8 reviewed Aug 4, 2025

View reviewed changes

keithmattix mentioned this pull request Aug 6, 2025

Blog/ambient mc #16750

Merged

11 tasks

keithmattix marked this pull request as ready for review August 6, 2025 13:08

keithmattix requested a review from a team as a code owner August 6, 2025 13:08

istio-testing removed the do-not-merge/work-in-progress Block merging of a PR because it isn't ready yet. label Aug 6, 2025

krinkinmu reviewed Aug 6, 2025

View reviewed changes

content/en/docs/ambient/install/multicluster/multi-primary_multi-network/index.md Outdated Show resolved Hide resolved

keithmattix force-pushed the jaellio/ambientmultinetdocs branch from 214cd73 to c16c515 Compare August 6, 2025 16:56

craigbox reviewed Aug 11, 2025

View reviewed changes

dhawton reviewed Aug 11, 2025

View reviewed changes

.spelling Outdated Show resolved Hide resolved

Stevenjin8 reviewed Aug 11, 2025

View reviewed changes

content/en/docs/ambient/install/multicluster/before-you-begin/index.md Outdated Show resolved Hide resolved

Stevenjin8 reviewed Aug 11, 2025

View reviewed changes

content/en/docs/ambient/install/multicluster/multi-primary_multi-network/index.md Outdated Show resolved Hide resolved

Stevenjin8 reviewed Aug 11, 2025

View reviewed changes

content/en/docs/ambient/install/multicluster/multi-primary_multi-network/index.md Outdated Show resolved Hide resolved

Stevenjin8 reviewed Aug 11, 2025

View reviewed changes

content/en/docs/ambient/install/multicluster/verify/index.md Outdated Show resolved Hide resolved

Stevenjin8 reviewed Aug 11, 2025

View reviewed changes

content/en/docs/ambient/install/multicluster/verify/index.md Outdated Show resolved Hide resolved

jaellio and others added 5 commits August 11, 2025 15:17

Install guide for ambient multi network

f7b85b5

Signed-off-by: Jackie Elliott <[email protected]>

Adopt Mitch's changes

26f2bec

Signed-off-by: Keith Mattix II <[email protected]>

Fix helm cleanup

747d470

Signed-off-by: Keith Mattix II <[email protected]>

Stash

68058c4

Signed-off-by: Keith Mattix II <[email protected]>

Address the rest of the feedback

e6b080d

Signed-off-by: Keith Mattix II <[email protected]>

keithmattix force-pushed the jaellio/ambientmultinetdocs branch from 34932f4 to e6b080d Compare August 11, 2025 15:44

keithmattix added 3 commits August 11, 2025 15:56

Change some of the tips

1a1ce5b

Signed-off-by: Keith Mattix II <[email protected]>

Make gen

3a3b262

Signed-off-by: Keith Mattix II <[email protected]>

Spellcheck

2455bd0

Signed-off-by: Keith Mattix II <[email protected]>

craigbox reviewed Aug 11, 2025

View reviewed changes

content/en/docs/ambient/install/multicluster/_index.md Outdated Show resolved Hide resolved

Use latest for news link

5e2f61c

Signed-off-by: Keith Mattix II <[email protected]>

craigbox added the do-not-merge/hold Block automatic merging of a PR. label Aug 12, 2025

craigbox approved these changes Aug 12, 2025

View reviewed changes

keithmattix added 3 commits August 12, 2025 21:00

Add prev and next designations to frontmatter

caab262

Signed-off-by: Keith Mattix II <[email protected]>

Fixup

c7444e7

Signed-off-by: Keith Mattix II <[email protected]>

Put the breadcrumb on the right pages

4d41a25

Signed-off-by: Keith Mattix II <[email protected]>

keithmattix removed the do-not-merge/hold Block automatic merging of a PR. label Aug 12, 2025

istio-testing merged commit dd96a14 into istio:master Aug 12, 2025
13 checks passed

keithmattix added the cherrypick/release-1.27 Set this label on a PR to auto-merge it to the release-1.27 branch label Aug 12, 2025

istio-testing mentioned this pull request Aug 12, 2025

[release-1.27] Install guide for ambient multi network #16776

Merged


		## Deploy the `HelloWorld` Service

		In order to make the `HelloWorld` service callable from any cluster, the DNS

Install guide for ambient multi network #16709

Install guide for ambient multi network #16709

Uh oh!

Conversation

jaellio commented Jul 28, 2025 • edited by keithmattix Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Reviewers

Uh oh!

istio-testing commented Jul 28, 2025

Uh oh!

istio-policy-bot commented Jul 28, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Stevenjin8 Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

jaellio Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

linux-foundation-easycla bot commented Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

keithmattix Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jaellio commented Jul 28, 2025 •

edited by keithmattix

Loading

Stevenjin8 Aug 4, 2025 •

edited

Loading

jaellio Aug 6, 2025 •

edited

Loading

linux-foundation-easycla bot commented Aug 6, 2025 •

edited

Loading

keithmattix Aug 11, 2025 •

edited

Loading