Skip to content

Commit db25871

Browse files
briandooleybriandooley
authored
Merge pull request #95032 from shreyasiddhartha/OSSM_9322
OSSM-9322 Istio ambient mode getting started docs
2 parents f291b2e + 5750403 commit db25871

8 files changed

+434
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,8 @@ Topics:
7272
File: ossm-installing-openshift-service-mesh
7373
- Name: Sidecar injection
7474
File: ossm-sidecar-injection
75+
- Name: Istio ambient mode
76+
File: ossm-istio-ambient-mode
7577
- Name: Red Hat OpenShift Service Mesh and cert-manager
7678
File: ossm-cert-manager
7779
- Name: Multi-Cluster topologies

‎install/ossm-istio-ambient-mode.adoc

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="ossm-istio-ambient-mode"]
3+
= Istio ambient mode
4+
include::_attributes/common-attributes.adoc[]
5+
:context: ossm-istio-ambient-mode
6+
7+
toc::[]
8+
9+
{istio} ambient mode introduces an architecture for {SMProductName} without sidecar injection. This mode is designed to simplify operations and reduce resource usage. Instead of injecting a sidecar proxy into each application pod, ambient mode uses a shared node-level proxy for Layer 4 (L4) functionality and an optional, dedicated proxy for Layer 7 (L7) features.
10+
11+
include::snippets/technology-preview-istio-ambient-mode.adoc[]
12+
13+
include::modules/ossm-about-istio-ambient-mode.adoc[leveloffset=+1]
14+
include::modules/ossm-installing-istio-ambient-mode.adoc[leveloffset=+2]
15+
16+
.Next steps
17+
* xref:../install/ossm-istio-ambient-mode.adoc#ossm-scoping-sm-discovery-selectors-istio-ambient-mode_ossm-istio-ambient-mode[Scoping Service Mesh with discovery selectors in Istio ambient mode]
18+
* xref:../install/ossm-istio-ambient-mode.adoc#ossm-deploying-bookinfo-application-istio-ambient-mode_ossm-istio-ambient-mode[Deploying the Bookinfo application in Istio ambient mode]
19+
20+
include::modules/ossm-about-discovery-selectors-istio-ambient-mode.adoc[leveloffset=+1]
21+
22+
[role="_additional-resources"]
23+
.Additional resources
24+
* xref:../install/ossm-installing-openshift-service-mesh.adoc#ossm-scoping-service-mesh-with-discoveryselectors_ossm-creating-istiocni-resource[Scoping the Service Mesh with discovery selectors]
25+
26+
include::modules/ossm-scoping-sm-discovery-selectors-istio-ambient-mode.adoc[leveloffset=+2]
27+
include::modules/ossm-deploying-bookinfo-application-istio-ambient-mode.adoc[leveloffset=+1]
28+
29+
[role="_additional-resources"]
30+
.Additional resources
31+
* xref:../install/ossm-installing-openshift-service-mesh.adoc#ossm-about-bookinfo-application_ossm-discoveryselectors-scope-service-mesh[About the Bookinfo application]
32+
33+
[role="_additional-resources"]
34+
[id="additional-resources_{context}"]
35+
== Additional resources
36+
* link:https://istio.io/latest/docs/ambient/architecture/[Ambient mode architecture (Istio documentation)]
37+
* link:https://istio.io/latest/docs/ambient/usage/add-workloads/[Adding workloads to a mesh in ambient mode (Istio documentation)]

‎modules/ossm-about-discovery-selectors-istio-ambient-mode.adoc

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
// Module included in the following assemblies:
2+
3+
// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="ossm-about-discovery-selectors-istio-ambient-mode_{context}"]
7+
= About discovery selectors and Istio ambient mode
8+
9+
{istio} ambient mode includes workloads when the control plane discovers each workload and the appropriate label enables traffic redirection through the Ztunnel proxy. By default, the control plane discovers workloads in all namespaces across the cluster. As a result, each proxy receives configuration for every namespace, including workloads that are not enrolled in the mesh. In shared or multi-tenant clusters, limiting mesh participation to specific namespaces helps reduce configuration overhead and supports multiple service meshes within the same cluster.
10+
11+
For more information on discovery selectors, see "Scoping the Service Mesh with discovery selectors".

‎modules/ossm-about-istio-ambient-mode.adoc

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
// Module included in the following assemblies:
2+
3+
// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="ossm-about-istio-ambient-mode_{context}"]
7+
= About Istio ambient mode
8+
9+
To understand the {istio} ambient mode architecture, see the following definitions:
10+
11+
ZTunnel proxy:: A per-node proxy that manages secure, transparent Transmission Control Protocol (TCP) connections for all workloads on the node. It operates at Layer 4 (L4), offloading mutual Transport Layer Security (mTLS) and L4 policy enforcement from application pods.
12+
13+
Waypoint proxy:: An optional proxy that runs per service account or namespace to provide advanced Layer 7 (L7) features such as traffic management, policy enforcement, and observability. You can apply L7 features selectively to avoid the overhead of sidecars for every service.
14+
15+
Istio CNI plugin:: Redirects traffic to the Ztunnel proxy on each node, enabling transparent interception without requiring modifications to application pods.
16+
17+
{Istio} ambient mode offers the following benefits:
18+
19+
* *Simplified operations* that remove the need to manage sidecar injection, reducing the complexity of mesh adoption and operations.
20+
21+
* *Reduced resource consumption* with a per-node Ztunnel proxy that provides L4 service mesh features and an optional `waypoint` proxy that reduces resource overhead per pod.
22+
23+
* *Incremental adoption* that enables workloads to join the mesh with the L4 features like mutual Transport Layer Security (mTLS) and basic policies with optional `waypoint` proxies added later to use L7 service mesh features, such as HTTP(L7) traffic management.
24+
+
25+
[NOTE]
26+
====
27+
The L7 features require deploying `waypoint` proxies, which introduces minimal additional overhead for the selected services.
28+
====
29+
30+
* *Enhanced security* that provides a secure, zero-trust network foundation with mTLS by default for all meshed workloads.
31+
32+
[NOTE]
33+
====
34+
Ambient mode is a newer architecture and may involve different operational considerations than traditional sidecar models.
35+
====
36+
37+
While well-defined discovery selectors allow a service mesh deployed in ambient mode alongside a mesh in sidecar mode, this scenario has not been thoroughly validated. To avoid potential conflicts, install {istio} ambient mode only on clusters that do not have an existing {SMProductName} installation. Ambient mode remains a Technology Preview feature.
38+
39+
[IMPORTANT]
40+
====
41+
{istio} ambient mode is not compatible with clusters that use {SMProductName} 2.6 or earlier. You must not install or use them together.
42+
====

‎modules/ossm-deploying-bookinfo-application-istio-ambient-mode.adoc

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
// Module included in the following assemblies:
2+
3+
// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="ossm-deploying-bookinfo-application-istio-ambient-mode_{context}"]
7+
= Deploying the Bookinfo application in Istio ambient mode
8+
9+
You can deploy the `bookinfo` sample application in {istio} ambient mode without sidecar injection by using the `ZTunnel` proxy. For more information on `bookinfo` application, see "About the Bookinfo application".
10+
11+
.Prerequisites
12+
13+
* You have deployed a cluster on {ocp-product-title} 4.15 or later, which includes the supported {k8s} Gateway API custom resource definitions (CRDs) required for {istio} ambient mode.
14+
* You are logged in to the {ocp-product-title} cluster either through the web console as a user with the `cluster-admin` role, or with the `oc login` command, depending on the installation method.
15+
* You have installed the {SMProductName} Operator, created the {istio} resource, and the Operator has deployed {istio}.
16+
* You have created an `IstioCNI` resource, and the Operator has deployed the necessary `IstioCNI` pods.
17+
* You have created a `Ztunnel` resource, and the Operator has deployed the necessary `Ztunnel` pods.
18+
19+
.Procedure
20+
21+
. Create the `bookinfo` namespace by running the following command:
22+
+
23+
[source,terminal]
24+
----
25+
$ oc create namespace bookinfo
26+
----
27+
28+
. Add the `istio-discovery=enabled` label to the `bookinfo` namespace by running the following command:
29+
+
30+
[source,terminal]
31+
----
32+
$ oc label namespace bookinfo istio-discovery=enabled
33+
----
34+
35+
. Apply the `bookinfo` YAML file to deploy the `bookinfo` application by running the following command:
36+
+
37+
[source,terminal]
38+
----
39+
$ oc apply -n bookinfo -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.26/samples/bookinfo/platform/kube/bookinfo.yaml
40+
----
41+
42+
. Apply the `bookinfo-versions` YAML file to deploy the `bookinfo` application by running the following command:
43+
+
44+
[source,terminal]
45+
----
46+
$ oc apply -n bookinfo -f https://raw.githubusercontent.com/openshift-service-mesh/istio/release-1.26/samples/bookinfo/platform/kube/bookinfo-versions.yaml
47+
----
48+
49+
. Verify that the `bookinfo` pods are running by entering the following command:
50+
+
51+
[source,terminal]
52+
----
53+
$ oc -n bookinfo get pods
54+
----
55+
+
56+
.Example output
57+
[source,terminal]
58+
----
59+
NAME READY STATUS RESTARTS AGE
60+
details-v1-54ffdd5947-8gk5h 1/1 Running 0 5m9s
61+
productpage-v1-d49bb79b4-cb9sl 1/1 Running 0 5m3s
62+
ratings-v1-856f65bcff-h6kkf 1/1 Running 0 5m7s
63+
reviews-v1-848b8749df-wl5br 1/1 Running 0 5m6s
64+
reviews-v2-5fdf9886c7-8xprg 1/1 Running 0 5m5s
65+
reviews-v3-bb6b8ddc7-bvcm5 1/1 Running 0 5m5s
66+
----
67+
68+
. Verify that the `bookinfo` application is running by entering the following command:
69+
+
70+
[source,terminal]
71+
----
72+
$ oc exec "$(oc get pod -l app=ratings -n bookinfo \
73+
-o jsonpath='{.items[0].metadata.name}')" \
74+
-c ratings -n bookinfo \
75+
-- curl -sS productpage:9080/productpage | grep -o "<title>.*</title>"
76+
----
77+
78+
. Add the bookinfo application to the {istio} ambient mesh by labeling either the entire namespace or the individual pods:
79+
80+
.. To include all workloads in the bookinfo namespace, apply the `istio.io/dataplane-mode=ambient` label to the `bookinfo` namespace, by running the following command:
81+
+
82+
[source,terminal]
83+
----
84+
$ oc label namespace bookinfo istio.io/dataplane-mode=ambient
85+
----
86+
87+
.. To include only specific workloads, apply the `istio.io/dataplane-mode=ambient` label directly to individual pods. See the "Additional resources" section for more details on the labels used to add or exclude workloads in a mesh.
88+
89+
+
90+
[NOTE]
91+
====
92+
Adding workloads to the ambient mesh does not require restarting or redeploying application pods. Unlike sidecar mode, the number of containers in each pod remains unchanged.
93+
====
94+
95+
. Confirm that Ztunnel proxy has successfully opened listening sockets in the pod network namespace by running the following command:
96+
+
97+
[source,terminal]
98+
----
99+
$ istioctl ztunnel-config workloads --namespace ztunnel
100+
----
101+
+
102+
.Example output
103+
[source,terminal]
104+
----
105+
NAMESPACE POD NAME ADDRESS NODE WAYPOINT PROTOCOL
106+
bookinfo details-v1-54ffdd5947-cflng 10.131.0.69 ip-10-0-47-239.ec2.internal None HBONE
107+
bookinfo productpage-v1-d49bb79b4-8sgwx 10.128.2.80 ip-10-0-24-198.ec2.internal None HBONE
108+
bookinfo ratings-v1-856f65bcff-c6ldn 10.131.0.70 ip-10-0-47-239.ec2.internal None HBONE
109+
bookinfo reviews-v1-848b8749df-45hfd 10.131.0.72 ip-10-0-47-239.ec2.internal None HBONE
110+
bookinfo reviews-v2-5fdf9886c7-mvwft 10.128.2.78 ip-10-0-24-198.ec2.internal None HBONE
111+
bookinfo reviews-v3-bb6b8ddc7-fl8q2 10.128.2.79 ip-10-0-24-198.ec2.internal None HBONE
112+
istio-cni istio-cni-node-7hwd2 10.0.61.108 ip-10-0-61-108.ec2.internal None TCP
113+
istio-cni istio-cni-node-bfqmb 10.0.30.129 ip-10-0-30-129.ec2.internal None TCP
114+
istio-cni istio-cni-node-cv8cw 10.0.75.71 ip-10-0-75-71.ec2.internal None TCP
115+
istio-cni istio-cni-node-hj9cz 10.0.47.239 ip-10-0-47-239.ec2.internal None TCP
116+
istio-cni istio-cni-node-p8wrg 10.0.24.198 ip-10-0-24-198.ec2.internal None TCP
117+
istio-system istiod-6bd6b8664b-r74js 10.131.0.80 ip-10-0-47-239.ec2.internal None TCP
118+
ztunnel ztunnel-2w5mj 10.128.2.61 ip-10-0-24-198.ec2.internal None TCP
119+
ztunnel ztunnel-6njq8 10.129.0.131 ip-10-0-75-71.ec2.internal None TCP
120+
ztunnel ztunnel-96j7k 10.130.0.146 ip-10-0-61-108.ec2.internal None TCP
121+
ztunnel ztunnel-98mrk 10.131.0.50 ip-10-0-47-239.ec2.internal None TCP
122+
ztunnel ztunnel-jqcxn 10.128.0.98 ip-10-0-30-129.ec2.internal None TCP
123+
----

‎modules/ossm-installing-istio-ambient-mode.adoc

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
// Module included in the following assemblies:
2+
3+
// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="ossm-installing-istio-ambient-mode_{context}"]
7+
= Installing Istio ambient mode
8+
9+
You can install {istio} ambient mode on {ocp-product-title} 4.19 or later and {SMProductName} 3.1.0 or later with the required Gateway API custom resource definitions (CRDs).
10+
11+
.Prerequisites
12+
13+
* You have deployed a cluster on {ocp-product-title} 4.19 or later.
14+
* You have installed the {SMProduct} Operator 3.1.0 or later in the {ocp-product-title} cluster.
15+
* You are logged in to the {ocp-product-title} cluster either through the web console as a user with the `cluster-admin` role, or with the `oc login` command, depending on the installation method.
16+
17+
.Procedure
18+
19+
. Install the {istio} control plane:
20+
21+
.. Create the `istio-system` namespace by running the following command:
22+
+
23+
[source,terminal]
24+
----
25+
$ oc create namespace istio-system
26+
----
27+
28+
.. Create an `{istio}` resource named `istio.yaml` similar to the following example:
29+
+
30+
.Example configuration
31+
[source,yaml]
32+
----
33+
apiVersion: sailoperator.io/v1
34+
kind: Istio
35+
metadata:
36+
name: default
37+
spec:
38+
namespace: istio-system
39+
profile: ambient
40+
values:
41+
pilot:
42+
trustedZtunnelNamespace: ztunnel
43+
----
44+
+
45+
[IMPORTANT]
46+
====
47+
You must set the `profile` field to `ambient`, and configure the `.spec.values.pilot.trustedZtunnelNamespace` value to match the namespace where the `ZTunnel` resource will be installed.
48+
====
49+
50+
.. Apply the `{istio}` custom resource (CR) by running the following command:
51+
+
52+
[source,terminal]
53+
----
54+
$ oc apply -f istio.yaml
55+
----
56+
57+
.. Wait for the {istio} control plane to contain the `Ready` status condition by running the following command:
58+
+
59+
[source,terminal]
60+
----
61+
$ oc wait --for=condition=Ready istios/default --timeout=3m
62+
----
63+
64+
. Install the {istio} Container Network Interface (CNI):
65+
66+
.. Create the `istio-cni` namespace by running the following command:
67+
+
68+
[source,terminal]
69+
----
70+
$ oc create namespace istio-cni
71+
----
72+
73+
.. Create the `IstioCNI` resource named `istio-cni.yaml` similar to the following example:
74+
+
75+
.Example configuration
76+
[source,yaml]
77+
----
78+
apiVersion: sailoperator.io/v1
79+
kind: IstioCNI
80+
metadata:
81+
name: default
82+
spec:
83+
namespace: istio-cni
84+
profile: ambient
85+
----
86+
+
87+
Set the `profile` field to `ambient`.
88+
89+
.. Apply the `IstioCNI` CR by running the following command:
90+
+
91+
[source,terminal]
92+
----
93+
$ oc apply -f istio-cni.yaml
94+
----
95+
96+
.. Wait for the `IstioCNI` pods to contain the `Ready` status condition by running the following command:
97+
+
98+
[source,terminal]
99+
----
100+
$ oc wait --for=condition=Ready istios/default --timeout=3m
101+
----
102+
103+
. Install the Ztunnel proxy:
104+
105+
.. Create the `ztunnel` namespace for Ztunnel proxy by running the following command:
106+
+
107+
[source,terminal]
108+
----
109+
$ oc create namespace ztunnel
110+
----
111+
+
112+
The namespace name for `ztunnel` project must match the `trustedZtunnelNamespace` parameter in {istio} configuration.
113+
114+
.. Create the `Ztunnel` resource named `ztunnel.yaml` similar to the following example:
115+
+
116+
.Example configuration
117+
[source,yaml]
118+
----
119+
apiVersion: sailoperator.io/v1alpha1
120+
kind: ZTunnel
121+
metadata:
122+
name: default
123+
spec:
124+
namespace: ztunnel
125+
profile: ambient
126+
----
127+
128+
.. Apply the `Ztunnel` CR by running the following command:
129+
+
130+
[source,terminal]
131+
----
132+
$ oc apply -f ztunnel.yaml
133+
----
134+
135+
.. Wait for the `Ztunnel` pods to contain the `Ready` status condition by running the following command:
136+
+
137+
[source,terminal]
138+
----
139+
$ oc wait --for=condition=Ready ztunnel/default --timeout=3m
140+
----

0 commit comments

Comments
 (0)