diff --git a/_attributes/common-attributes.adoc b/_attributes/common-attributes.adoc index 9e9952a16878..2998c668844c 100644 --- a/_attributes/common-attributes.adoc +++ b/_attributes/common-attributes.adoc @@ -108,4 +108,3 @@ :JaegerVersion: 1.47.0 //CLI :oc-first: pass:quotes[OpenShift CLI (`oc`)] - diff --git a/install/ossm-istio-ambient-mode.adoc b/install/ossm-istio-ambient-mode.adoc index 52501b35ed5b..0e5a7b75b14d 100644 --- a/install/ossm-istio-ambient-mode.adoc +++ b/install/ossm-istio-ambient-mode.adoc @@ -6,12 +6,13 @@ include::_attributes/common-attributes.adoc[] toc::[] -{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. +{istio} ambient mode introduces an architecture for {SMProductName} without sidecar injection. The {istio} ambient 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. include::snippets/technology-preview-istio-ambient-mode.adoc[] include::modules/ossm-about-istio-ambient-mode.adoc[leveloffset=+1] -include::modules/ossm-installing-istio-ambient-mode.adoc[leveloffset=+2] + +include::modules/ossm-installing-istio-ambient-mode.adoc[leveloffset=+1] .Next steps * 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] @@ -25,14 +26,24 @@ include::modules/ossm-about-discovery-selectors-istio-ambient-mode.adoc[leveloff * xref:../install/ossm-installing-openshift-service-mesh.adoc#ossm-scoping-service-mesh-with-discoveryselectors_ossm-installing-openshift-service-mesh[Scoping the mesh with discovery selectors] include::modules/ossm-scoping-sm-discovery-selectors-istio-ambient-mode.adoc[leveloffset=+2] + include::modules/ossm-deploying-bookinfo-application-istio-ambient-mode.adoc[leveloffset=+1] [role="_additional-resources"] .Additional resources * xref:../install/ossm-installing-openshift-service-mesh.adoc#ossm-about-bookinfo-application_ossm-installing-openshift-service-mesh[About the Bookinfo application] +include::modules/ossm-about-istio-ambient-waypoint.adoc[leveloffset=+1] + +include::modules/ossm-deploying-waypoint-using-gateway-api.adoc[leveloffset=+1] + +include::modules/ossm-deploying-waypoint-proxy.adoc[leveloffset=+1] + +include::modules/ossm-enabling-cross-namespace-waypoint-usage.adoc[leveloffset=+1] + [role="_additional-resources"] [id="additional-resources_{context}"] == Additional resources * link:https://istio.io/latest/docs/ambient/architecture/[Ambient mode architecture (Istio documentation)] -* link:https://istio.io/latest/docs/ambient/usage/add-workloads/[Adding workloads to a mesh in ambient mode (Istio documentation)] \ No newline at end of file +* link:https://istio.io/latest/docs/ambient/usage/add-workloads/[Adding workloads to a mesh in ambient mode (Istio documentation)] +* link:https://istio.io/latest/docs/ambient/usage/waypoint/#waypoint-traffic-types[Waypoint traffic types (Istio documentation)] \ No newline at end of file diff --git a/modules/ossm-about-istio-ambient-waypoint.adoc b/modules/ossm-about-istio-ambient-waypoint.adoc new file mode 100644 index 000000000000..728c88a22acd --- /dev/null +++ b/modules/ossm-about-istio-ambient-waypoint.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: + +// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc + +:_mod-docs-content-type: CONCEPT +[id="ossm-about-istio-ambient-waypoint_{context}"] += About waypoint proxies in Istio ambient mode + +After setting up {istio} ambient mode with ztunnel proxies, you can add waypoint proxies to enable advanced Layer 7 (L7) processing features that {istio} provides. + +{istio} ambient mode separates the functionality of {istio} into two layers: + +* A secure Layer 4 (L4) overlay managed by ztunnel proxies + +* An L7 layer managed by optional waypoint proxies + +A waypoint proxy is an Envoy-based proxy that performs L7 processing for workloads running in ambient mode. It functions as a gateway to a resource such as a namespace, service, or pod. You can install, upgrade, and scale waypoint proxies independently of applications. The configuration uses the {k8s} Gateway API. + +Unlike the sidecar model, where each workload runs its own Envoy proxy, waypoint proxies reduce resource use by serving multiple workloads within the same security boundary, such as all workloads in a namespace. + +A destination waypoint enforces policies by acting as a gateway. All incoming traffic to a resource, such as a namespace, service, or pod, passes through the waypoint for policy enforcement. + +The `ztunnel` node proxy manages L4 functions in ambient mode, including mutual Transport Layer Security (mTLS) encryption, L4 traffic processing, and telemetry. Ztunnel and waypoint proxies communicate using HBONE (HTTP-Based Overlay Network), a protocol that tunnels traffic over HTTP/2 CONNECT with mutual TLS (mTLS) on port `15008`. + +You can add a waypoint proxy if workloads require any of the following L7 capabilities: + +Traffic management:: Advanced HTTP routing, load balancing, circuit breaking, rate limiting, fault injection, retries, and timeouts + +Security:: Authorization policies based on L7 attributes such as request type or HTTP headers + +Observability:: HTTP metrics, access logging, and tracing for application traffic \ No newline at end of file diff --git a/modules/ossm-deploying-waypoint-proxy.adoc b/modules/ossm-deploying-waypoint-proxy.adoc new file mode 100644 index 000000000000..282086e70390 --- /dev/null +++ b/modules/ossm-deploying-waypoint-proxy.adoc @@ -0,0 +1,92 @@ +// Module included in the following assemblies: + +// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-deploying-waypoint-proxy_{context}"] += Deploying a waypoint proxy + +You can deploy a waypoint proxy in the `bookinfo` application namespace to route traffic through the {istio} ambient data plane and enforce L7 policies. + +.Prerequisites + +* You have logged in to the {ocp-product-title} 4.19 or later, which provides supported {k8s} Gateway API custom resource definitions (CRDs) required for ambient mode functionality. + +* You have the {SMProductName} Operator 3.2.0 or later installed on the OpenShift cluster. + +* You have {istio} deployed in ambient mode. + +* You have deployed the `bookinfo` sample application for the following example. + +* You have added the `label istio.io/dataplane-mode=ambient` to the target namespace. + +.Procedure + +. Deploy a waypoint proxy in the `bookinfo` application namespace similar to the following example: ++ +.Example configuration +[source,yaml] +---- +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + labels: + istio.io/waypoint-for: service + name: waypoint + namespace: bookinfo +spec: + gatewayClassName: istio-waypoint + listeners: + - name: mesh + port: 15008 + protocol: HBONE +---- + +. Apply the `waypoint` custom resource (CR) by running the following command: ++ +[source,terminal] +---- +$ oc apply -f waypoint.yaml +---- ++ +The `istio.io/waypoint-for: service` label indicates that the waypoint handles traffic for services. The label determines the type of traffic processed. For more information, see "Waypoint traffic types". + +. Enroll the `bookinfo` namespace to use the waypoint by running the following command: ++ +[source,terminal] +---- +$ oc label namespace bookinfo istio.io/use-waypoint=waypoint +---- + +After enrolling the namespace, requests from any pods using the ambient data plane to services in `bookinfo` will route through the waypoint for L7 processing and policy enforcement. + +.Verification + +. Confirm that the waypoint proxy is used by all the services in the `bookinfo` namespace by running the following command: ++ +[source,terminal] +---- +$ istioctl ztunnel-config svc --namespace ztunnel +---- ++ +.Example output +[source,terminal] +---- +NAMESPACE SERVICE NAME SERVICE VIP WAYPOINT ENDPOINTS +bookinfo details 172.30.15.248 waypoint 1/1 +bookinfo details-v1 172.30.114.128 waypoint 1/1 +bookinfo productpage 172.30.155.45 waypoint 1/1 +bookinfo productpage-v1 172.30.76.27 waypoint 1/1 +bookinfo ratings 172.30.24.145 waypoint 1/1 +bookinfo ratings-v1 172.30.139.144 waypoint 1/1 +bookinfo reviews 172.30.196.50 waypoint 3/3 +bookinfo reviews-v1 172.30.172.192 waypoint 1/1 +bookinfo reviews-v2 172.30.12.41 waypoint 1/1 +bookinfo reviews-v3 172.30.232.12 waypoint 1/1 +bookinfo waypoint 172.30.92.147 None 1/1 +---- + +[NOTE] +==== +You can also configure only specific services or pods to use a waypoint by labeling the respective service or pod. When enrolling a pod explicitly, also add the `istio.io/waypoint-for: workload` label to the corresponding `gateway` resource. +==== \ No newline at end of file diff --git a/modules/ossm-deploying-waypoint-using-gateway-api.adoc b/modules/ossm-deploying-waypoint-using-gateway-api.adoc new file mode 100644 index 000000000000..df98372bf064 --- /dev/null +++ b/modules/ossm-deploying-waypoint-using-gateway-api.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies: + +// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-deploying-waypoint-using-gateway-api_{context}"] += Deploying waypoint proxies using gateway API + +You can deploy waypoint proxies using {k8s} Gateway resource. + +.Prerequisites + +* You have logged in to the {ocp-product-title} 4.19 or later, which provides supported {k8s} Gateway API CRDs required for ambient mode functionality. + +* You have the {SMProductName} Operator 3.2.0 or later installed on the OpenShift cluster. + +* You have {istio} deployed in ambient mode. + +* You have applied the required labels to workloads or namespaces to enable `ztunnel` traffic redirection. + +[IMPORTANT] +==== +{istio} ambient mode is not compatible with clusters that use {SMProductName} 2.6 or earlier. You must not deploy both versions in the same cluster. +==== + +.Procedure + +* On {ocp-product-title} 4.18 and earlier, install the community-maintained {k8s} Gateway API CRDs by running the following command: ++ +[source,terminal] +---- +$ oc get crd gateways.gateway.networking.k8s.io &> /dev/null || \ + { oc apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml; } +---- ++ +From {ocp-product-title} 4.19 onwards, the Gateway API CRDs are installed by default. + +[NOTE] +==== +The CRDs are community maintained and not supported by Red Hat. Upgrading to {ocp-product-title} 4.19 or later, which includes supported Gateway API CRDs, may disrupt applications. +==== \ No newline at end of file diff --git a/modules/ossm-enabling-cross-namespace-waypoint-usage.adoc b/modules/ossm-enabling-cross-namespace-waypoint-usage.adoc new file mode 100644 index 000000000000..35c83cd84456 --- /dev/null +++ b/modules/ossm-enabling-cross-namespace-waypoint-usage.adoc @@ -0,0 +1,58 @@ +// Module included in the following assemblies: + +// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-enabling-cross-namespace-waypoint-usage_{context}"] += Enabling cross-namespace waypoint usage + +You can use a cross-namespace waypoint to allow resources in one namespace to route traffic through a waypoint deployed in a different namespace. + +.Procedure + +. Create a `Gateway` resource that allows workloads in the `bookinfo` namespace to use the `waypoint-default` from the `default` namespace similar to the following example: ++ +.Example configuration +[source,yaml] +---- +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: waypoint-default + namespace: default +spec: + gatewayClassName: istio-waypoint + listeners: + - name: mesh + port: 15008 + protocol: HBONE + allowedRoutes: + namespaces: + from: Selector + selector: + matchLabels: + kubernetes.io/metadata.name: bookinfo +---- + +. Apply the cross-namespace waypoint by running the following command: ++ +[source,terminal] +---- +$ oc apply -f waypoint-default.yaml +---- + +. Add the labels required to use a cross-namespace waypoint: + +.. Add the `istio.io/use-waypoint-namespace` label to specify the namespace where the waypoint resides by running the following command: ++ +[source,terminal] +---- +$ oc label namespace bookinfo istio.io/use-waypoint-namespace=default +---- + +.. Add the `istio.io/use-waypoint` label to specify the waypoint to use by running the following command: ++ +[source,terminal] +---- +$ oc label namespace bookinfo istio.io/use-waypoint=waypoint-default +---- \ No newline at end of file