Skip to content

Commit dd96a14

Browse files
jaelliokeithmattix
andauthored
Install guide for ambient multi network (#16709)
* Install guide for ambient multi network Signed-off-by: Jackie Elliott <[email protected]> * Adopt Mitch's changes Signed-off-by: Keith Mattix II <[email protected]> * Fix helm cleanup Signed-off-by: Keith Mattix II <[email protected]> * Stash Signed-off-by: Keith Mattix II <[email protected]> * Address the rest of the feedback Signed-off-by: Keith Mattix II <[email protected]> * Change some of the tips Signed-off-by: Keith Mattix II <[email protected]> * Make gen Signed-off-by: Keith Mattix II <[email protected]> * Spellcheck Signed-off-by: Keith Mattix II <[email protected]> * Use latest for news link Signed-off-by: Keith Mattix II <[email protected]> * Add prev and next designations to frontmatter Signed-off-by: Keith Mattix II <[email protected]> * Fixup Signed-off-by: Keith Mattix II <[email protected]> * Put the breadcrumb on the right pages Signed-off-by: Keith Mattix II <[email protected]> --------- Signed-off-by: Jackie Elliott <[email protected]> Signed-off-by: Keith Mattix II <[email protected]> Co-authored-by: Keith Mattix II <[email protected]>
1 parent 9dca650 commit dd96a14

File tree

17 files changed

+1665
-39
lines changed

17 files changed

+1665
-39
lines changed

.gitignore

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,3 +41,9 @@ archived_version
4141

4242
# Local Netlify folder
4343
.netlify
44+
45+
# Local artifacts when running tests
46+
artifacts
47+
48+
# Certs generated during tests
49+
certs

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ aliases:
88
owner: istio/wg-environment-maintainers
99
test: n/a
1010
list_below: yes
11+
keywords: [kubernetes,ambient,install]
1112
---
1213

1314
{{< tip >}}
Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
title: Install Multicluster
3+
description: Install an Istio mesh in ambient mode across multiple Kubernetes clusters.
4+
weight: 40
5+
keywords: [kubernetes,multicluster,ambient]
6+
simple_list: true
7+
content_above: true
8+
test: table-of-contents
9+
owner: istio/wg-environments-maintainers
10+
next: /docs/ambient/install/multicluster/before-you-begin
11+
---
12+
13+
Follow this guide to install an Istio {{< gloss "ambient" >}}ambient service mesh{{< /gloss >}}
14+
that spans multiple {{< gloss "cluster" >}}clusters{{< /gloss >}}.
15+
16+
## Current Status and Limitations
17+
18+
{{< warning >}}
19+
**Ambient multicluster is currently in alpha status** and has significant limitations.
20+
This feature is under active development and should not be used in production environments.
21+
{{< /warning >}}
22+
23+
Before proceeding with ambient multicluster installation, it's critical to understand
24+
the current state and limitations of this feature:
25+
26+
### Supported Configurations
27+
28+
Currently, ambient multicluster only supports:
29+
Before proceeding with an ambient multicluster installation, it is critical to understand
30+
the current state and limitations of this feature.
31+
32+
### Critical Limitations
33+
34+
#### Network Topology Restrictions
35+
36+
**Multi-cluster single-network configurations are untested, and may be broken**
37+
- Use caution when deploying ambient across clusters that share the same network
38+
- Only multi-network configurations are supported
39+
40+
#### Control Plane Limitations
41+
42+
**Primary remote configuration is not currently supported**
43+
- You can only have multiple primary clusters
44+
- Configurations with one or more remote clusters will not work correctly
45+
46+
#### Waypoint Requirements
47+
48+
**Universal waypoint deployments are assumed across clusters**
49+
- All clusters must have identically named waypoint deployments
50+
- Waypoint configurations must be synchronized manually across clusters (e.g. using Flux, ArgoCD, or similar tools)
51+
- Traffic routing relies on consistent waypoint naming conventions
52+
53+
#### Service Visibility and Scoping
54+
55+
**Service scope configurations are not read from across clusters**
56+
- Only the local cluster's service scope configuration is used as the source of truth
57+
- Remote cluster service scopes are not respected, which can lead to unexpected traffic behavior
58+
- Cross-cluster service discovery may not respect intended service boundaries
59+
60+
**If a service's waypoint is marked as global, that service will also be global**
61+
- This can lead to unintended cross-cluster traffic if not managed carefully
62+
63+
#### Gateway Limitations
64+
65+
**Ambient east-west gateways currently only support meshed mTLS traffic**
66+
- Cannot currently expose `istiod` across networks using ambient east-west gateways. You can still use a classic e/w gateway for this.
67+
68+
{{< tip >}}
69+
As ambient multicluster matures, many of these limitations will be addressed.
70+
Check the [Istio release notes](https://istio.io/latest/news/) for updates on
71+
ambient multicluster capabilities.
72+
{{< /tip >}}
Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
title: Before you begin
3+
description: Initial steps before installing Istio on multiple clusters.
4+
weight: 1
5+
keywords: [kubernetes,multicluster,ambient]
6+
test: n/a
7+
owner: istio/wg-environments-maintainers
8+
next: /docs/ambient/install/multicluster/multi-primary_multi-network
9+
prev: /docs/ambient/install/multicluster
10+
---
11+
12+
{{< boilerplate alpha >}}
13+
14+
Before you begin a multicluster installation, review the
15+
[deployment models guide](/docs/ops/deployment/deployment-models)
16+
which describes the foundational concepts used throughout this guide.
17+
18+
In addition, review the requirements and perform the initial steps below.
19+
20+
## Requirements
21+
22+
### Cluster
23+
24+
This guide requires that you have two Kubernetes clusters with support for LoadBalancer `Services` on any of the
25+
[supported Kubernetes versions:](/docs/releases/supported-releases#support-status-of-istio-releases) {{< supported_kubernetes_versions >}}.
26+
27+
### API Server Access
28+
29+
The API Server in each cluster must be accessible to the other clusters in the
30+
mesh. Many cloud providers make API Servers publicly accessible via network
31+
load balancers (NLB). The ambient east-west gateway cannot be used to expose
32+
the API server as it only supports double HBONE traffic. A non-ambient
33+
[east-west](https://en.wikipedia.org/wiki/East-west_traffic) gateway could be
34+
used to enable access to the API Server.
35+
36+
## Environment Variables
37+
38+
This guide will refer to two clusters: `cluster1` and `cluster2`. The following
39+
environment variables will be used throughout to simplify the instructions:
40+
41+
Variable | Description
42+
-------- | -----------
43+
`CTX_CLUSTER1` | The context name in the default [Kubernetes configuration file](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) used for accessing the `cluster1` cluster.
44+
`CTX_CLUSTER2` | The context name in the default [Kubernetes configuration file](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) used for accessing the `cluster2` cluster.
45+
46+
Set the two variables before proceeding:
47+
48+
{{< text syntax=bash snip_id=none >}}
49+
$ export CTX_CLUSTER1=<your cluster1 context>
50+
$ export CTX_CLUSTER2=<your cluster2 context>
51+
{{< /text >}}
52+
53+
## Configure Trust
54+
55+
A multicluster service mesh deployment requires that you establish trust
56+
between all clusters in the mesh. Depending on the requirements for your
57+
system, there may be multiple options available for establishing trust.
58+
See [certificate management](/docs/tasks/security/cert-management/) for
59+
detailed descriptions and instructions for all available options.
60+
Depending on which option you choose, the installation instructions for
61+
Istio may change slightly.
62+
63+
This guide will assume that you use a common root to generate intermediate
64+
certificates for each primary cluster.
65+
Follow the [instructions](/docs/tasks/security/cert-management/plugin-ca-cert/)
66+
to generate and push a CA certificate secret to both the `cluster1` and `cluster2`
67+
clusters.
68+
69+
{{< tip >}}
70+
If you currently have a single cluster with a self-signed CA (as described
71+
in [Getting Started](/docs/setup/getting-started/)), you need to
72+
change the CA using one of the methods described in
73+
[certificate management](/docs/tasks/security/cert-management/). Changing the
74+
CA typically requires reinstalling Istio. The installation instructions
75+
below may have to be altered based on your choice of CA.
76+
{{< /tip >}}
77+
78+
## Next steps
79+
80+
You're now ready to install an Istio ambient mesh across multiple clusters.
81+
82+
- [Install Multi-Primary on Different Networks](/docs/ambient/install/multicluster/multi-primary_multi-network)
83+
84+
{{< tip >}}
85+
If you plan on installing Istio multi-cluster using Helm, follow the
86+
[Helm prerequisites](/docs/setup/install/helm/#prerequisites) in the Helm install guide first.
87+
{{< /tip >}}
Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
#!/usr/bin/env bash
2+
# shellcheck disable=SC1090,SC2034,SC2154
3+
4+
# Copyright Istio Authors
5+
#
6+
# Licensed under the Apache License, Version 2.0 (the "License");
7+
# you may not use this file except in compliance with the License.
8+
# You may obtain a copy of the License at
9+
#
10+
# http://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# Unless required by applicable law or agreed to in writing, software
13+
# distributed under the License is distributed on an "AS IS" BASIS,
14+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
# See the License for the specific language governing permissions and
16+
# limitations under the License.
17+
18+
# Initialize KUBECONFIG_FILES and KUBE_CONTEXTS
19+
_set_kube_vars
20+
21+
source content/en/docs/ambient/install/multicluster/verify/snips.sh
22+
23+
# set_single_network_vars initializes all variables for a single network config.
24+
function set_single_network_vars
25+
{
26+
export KUBECONFIG_CLUSTER1="${KUBECONFIG_FILES[0]}"
27+
export KUBECONFIG_CLUSTER2="${KUBECONFIG_FILES[1]}"
28+
export CTX_CLUSTER1="${KUBE_CONTEXTS[0]}"
29+
export CTX_CLUSTER2="${KUBE_CONTEXTS[1]}"
30+
}
31+
32+
# set_multi_network_vars initializes all variables for a multi-network config.
33+
function set_multi_network_vars
34+
{
35+
export KUBECONFIG_CLUSTER1="${KUBECONFIG_FILES[0]}"
36+
export KUBECONFIG_CLUSTER2="${KUBECONFIG_FILES[2]}"
37+
export CTX_CLUSTER1="${KUBE_CONTEXTS[0]}"
38+
export CTX_CLUSTER2="${KUBE_CONTEXTS[2]}"
39+
}
40+
41+
# configure_trust creates a hierarchy of
42+
function configure_trust
43+
{
44+
# Keeps the certs under a separate directory.
45+
mkdir -p certs
46+
pushd certs || exit
47+
48+
# Create the root cert.
49+
make -f ../tools/certs/Makefile.selfsigned.mk root-ca
50+
51+
# Create and deploy intermediate certs for cluster1 and cluster2.
52+
make -f ../tools/certs/Makefile.selfsigned.mk cluster1-cacerts
53+
make -f ../tools/certs/Makefile.selfsigned.mk cluster2-cacerts
54+
55+
# Create the istio-system namespace in each cluster so that we can create the secrets.
56+
kubectl --context="$CTX_CLUSTER1" create namespace istio-system
57+
kubectl --context="$CTX_CLUSTER2" create namespace istio-system
58+
59+
# Deploy secret to each cluster
60+
kubectl --context="$CTX_CLUSTER1" create secret generic cacerts -n istio-system \
61+
--from-file=cluster1/ca-cert.pem \
62+
--from-file=cluster1/ca-key.pem \
63+
--from-file=cluster1/root-cert.pem \
64+
--from-file=cluster1/cert-chain.pem
65+
kubectl --context="$CTX_CLUSTER2" create secret generic cacerts -n istio-system \
66+
--from-file=cluster2/ca-cert.pem \
67+
--from-file=cluster2/ca-key.pem \
68+
--from-file=cluster2/root-cert.pem \
69+
--from-file=cluster2/cert-chain.pem
70+
71+
popd || exit # Return to the previous directory.
72+
}
73+
74+
# cleanup_istioctl removes all resources created by the tests with istioctl.
75+
function cleanup_istioctl
76+
{
77+
# Remove temp files.
78+
rm -f cluster1.yaml cluster2.yaml certs
79+
80+
# Cleanup both clusters concurrently
81+
cleanup_cluster1_istioctl &
82+
cleanup_cluster2_istioctl &
83+
wait
84+
snip_delete_crds
85+
}
86+
87+
# cleanup_cluster1_istioctl removes the istio-system and sample namespaces on CLUSTER1 with istioctl.
88+
function cleanup_cluster1_istioctl
89+
{
90+
echo y | istioctl uninstall --revision=default --context="${CTX_CLUSTER1}"
91+
kubectl delete ns istio-system sample --context="${CTX_CLUSTER1}" --ignore-not-found
92+
}
93+
94+
# cleanup_cluster2_istioctl removes the istio-system and sample namespaces on CLUSTER2 with istioctl.
95+
function cleanup_cluster2_istioctl
96+
{
97+
echo y | istioctl uninstall --revision=default --context="${CTX_CLUSTER2}"
98+
kubectl delete ns istio-system sample --context="${CTX_CLUSTER2}" --ignore-not-found
99+
}
100+
101+
# verify_load_balancing verifies that traffic is load balanced properly
102+
# between CLUSTER1 and CLUSTER2.
103+
function verify_load_balancing
104+
{
105+
# Verify istiod is synced
106+
echo "Verifying istiod is synced to remote cluster."
107+
_verify_like snip_verify_multicluster_1 "$snip_verify_multicluster_1_out"
108+
109+
# Deploy the HelloWorld service.
110+
snip_deploy_the_helloworld_service_1
111+
snip_deploy_the_helloworld_service_2
112+
snip_deploy_the_helloworld_service_3
113+
114+
# Deploy HelloWorld v1 and v2
115+
snip_deploy_helloworld_v1_1
116+
snip_deploy_helloworld_v2_1
117+
118+
# Deploy curl
119+
snip_deploy_curl_1
120+
121+
# Wait for all the deployments.
122+
_wait_for_deployment sample helloworld-v1 "${CTX_CLUSTER1}"
123+
_wait_for_deployment sample curl "${CTX_CLUSTER1}"
124+
_wait_for_deployment sample helloworld-v2 "${CTX_CLUSTER2}"
125+
_wait_for_deployment sample curl "${CTX_CLUSTER2}"
126+
127+
# Expose the helloworld service in both clusters.
128+
echo "Exposing helloworld in cluster1"
129+
kubectl --context="${CTX_CLUSTER1}" label svc helloworld -n sample istio.io/global="true"
130+
echo "Exposing helloworld in cluster2"
131+
kubectl --context="${CTX_CLUSTER2}" label svc helloworld -n sample istio.io/global="true"
132+
133+
# Verify everything is deployed as expected.
134+
VERIFY_TIMEOUT=0 # Don't retry.
135+
echo "Verifying helloworld v1 deployment"
136+
_verify_like snip_deploy_helloworld_v1_2 "$snip_deploy_helloworld_v1_2_out"
137+
echo "Verifying helloworld v2 deployment"
138+
_verify_like snip_deploy_helloworld_v2_2 "$snip_deploy_helloworld_v2_2_out"
139+
echo "Verifying curl deployment in ${CTX_CLUSTER1}"
140+
_verify_like snip_deploy_curl_2 "$snip_deploy_curl_2_out"
141+
echo "Verifying curl deployment in ${CTX_CLUSTER2}"
142+
_verify_like snip_deploy_curl_3 "$snip_deploy_curl_3_out"
143+
unset VERIFY_TIMEOUT # Restore default
144+
145+
local EXPECTED_RESPONSE_FROM_CLUSTER1="Hello version: v1, instance:"
146+
local EXPECTED_RESPONSE_FROM_CLUSTER2="Hello version: v2, instance:"
147+
148+
# Verify we hit both clusters from CLUSTER1
149+
echo "Verifying load balancing from ${CTX_CLUSTER1}"
150+
_verify_contains snip_verifying_crosscluster_traffic_1 "$EXPECTED_RESPONSE_FROM_CLUSTER1"
151+
_verify_contains snip_verifying_crosscluster_traffic_1 "$EXPECTED_RESPONSE_FROM_CLUSTER2"
152+
153+
# Verify we hit both clusters from CLUSTER2
154+
echo "Verifying load balancing from ${CTX_CLUSTER2}"
155+
_verify_contains snip_verifying_crosscluster_traffic_3 "$EXPECTED_RESPONSE_FROM_CLUSTER1"
156+
_verify_contains snip_verifying_crosscluster_traffic_3 "$EXPECTED_RESPONSE_FROM_CLUSTER2"
157+
}
158+
159+
# For Helm multi-cluster installation steps
160+
161+
function create_istio_system_ns
162+
{
163+
snip_create_istio_system_namespace_cluster_1
164+
snip_create_istio_system_namespace_cluster_2
165+
}
166+
167+
function setup_helm_repo
168+
{
169+
snip_setup_helm_repo_cluster_1
170+
snip_setup_helm_repo_cluster_2
171+
}
172+
173+
snip_create_istio_system_namespace_cluster_1() {
174+
kubectl create namespace istio-system --context "${CTX_CLUSTER1}"
175+
}
176+
177+
snip_create_istio_system_namespace_cluster_2() {
178+
kubectl create namespace istio-system --context "${CTX_CLUSTER2}"
179+
}
180+
181+
snip_setup_helm_repo_cluster_1() {
182+
helm repo add istio https://istio-release.storage.googleapis.com/charts --kube-context "${CTX_CLUSTER1}"
183+
helm repo update --kube-context "${CTX_CLUSTER1}"
184+
}
185+
186+
snip_setup_helm_repo_cluster_2() {
187+
helm repo add istio https://istio-release.storage.googleapis.com/charts --kube-context "${CTX_CLUSTER2}"
188+
helm repo update --kube-context "${CTX_CLUSTER2}"
189+
}
190+
191+
snip_delete_sample_ns_cluster_1() {
192+
kubectl delete namespace sample --context "${CTX_CLUSTER1}"
193+
}
194+
195+
snip_delete_sample_ns_cluster_2() {
196+
kubectl delete namespace sample --context "${CTX_CLUSTER2}"
197+
}

content/en/docs/ambient/install/multicluster/multi-primary_multi-network/arch.svg

Lines changed: 1 addition & 0 deletions
Loading

0 commit comments

Comments
 (0)