Skip to content

OSSM-1148 [DOCS] Istio Ambient mode waypoint docs: L7 features #100107

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: service-mesh-docs-main
Choose a base branch
from
+118 −0
Open

OSSM-1148 [DOCS] Istio Ambient mode waypoint docs: L7 features #100107

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions install/ossm-istio-ambient-mode.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,12 @@ include::modules/ossm-deploying-waypoint-proxy.adoc[leveloffset=+1]

include::modules/ossm-enabling-cross-namespace-waypoint-usage.adoc[leveloffset=+1]

include::modules/ossm-about-l7-features-ambient-mode.adoc[leveloffset=+1]

include::modules/ossm-routing-traffic-using-waypoint-proxies.adoc[leveloffset=+1]

include::modules/ossm-adding-authorization-policy.adoc[leveloffset=+1]

[role="_additional-resources"]
[id="additional-resources_{context}"]
== Additional resources
Expand Down
15 changes: 15 additions & 0 deletions modules/ossm-about-l7-features-ambient-mode.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
// Module included in the following assemblies:

// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc

:_mod-docs-content-type: CONCEPT
[id="ossm-about-l7-features-ambient-mode_{context}"]
= About Layer 7 features in ambient mode

Ambient mode includes stable Layer 7 (L7) capabilities implemented through the Gateway API `HTTPRoute` resource and the {istio} `AuthorizationPolicy` resource.

The `AuthorizationPolicy` resource works in both sidecar and ambient modes. In ambient mode, authorization policies can be targeted for `ztunnel` enforcement or attached for waypoint enforcement. To attach a policy to a waypoint, include a `targetRef` that references either the waypoint itself or a Service configured to use that waypoint.

You can attach Layer 4 (L4) or L7 policies to the waypoint proxy to ensure correct identity-based enforcement, as the destination `ztunnel` recognizes traffic by the identity of the waypoint, once it is part of the traffic path.

{istio} peer authentication policies, which configure mutual TLS (mTLS) modes, are supported by ztunnel. In ambient mode, policies that set the mode to `DISABLE` are ignored because ztunnel and HBONE always enforce mTLS. For more information, see "Peer authentication".
49 changes: 49 additions & 0 deletions modules/ossm-adding-authorization-policy.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
// Module included in the following assemblies:

// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc

:_mod-docs-content-type: PROCEDURE
[id="ossm-adding-authorization-policy_{context}"]
= Adding authorization policy

Use an Layer 7 (L7) authorization policy to explicitly allow the `curl` service to send `GET` requests to the `productpage` service while blocking all other operations.

.Procedure

. Create the authorization policy similar to the following example:
+
.Example configuration
[source,yaml]
----
apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
name: productpage-waypoint
namespace: bookinfo
spec:
targetRefs:
- kind: Service
group: ""
name: productpage
action: ALLOW
rules:
- from:
- source:
principals:
- cluster.local/ns/default/sa/curl
to:
- operation:
methods: ["GET"]
----

. Apply the authorization policy by running the following command:
+
[source,terminal]
----
$ oc apply -f authorization-policy.yaml
----

[NOTE]
====
The `targetRefs` field specifies the service targeted by the authorization policy of the waypoint proxy.
====
Copy link

@unsortedhashsets unsortedhashsets Oct 13, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add .Verification section like (example without doc styling) :

To verify access control, deploy a curl application in the default namespace. This is required because the example policy references the cluster.local/ns/default/sa/curl service account:

a. Apply curl application deployment

$ oc apply -n default -f https://raw.githubusercontent.com/openshift-service-mesh/istio/refs/heads/master/samples/curl/curl.yaml

b. Wait curl application is ready

$ oc -n default rollout status deploy/curl --timeout=3m

A GET request to the productpage service should succeed (HTTP 200) when made from the default/curl pod:

$ oc -n default exec deploy/curl -- sh -c \
  'curl -s -o /dev/null -w "HTTP %{http_code}\n" http://productpage.bookinfo.svc.cluster.local:9080/productpage'

A POST request to the same service should be denied (HTTP 403) due to the applied authorization policy, even when made from the same pod:

$ oc -n default exec deploy/curl -- sh -c \
  'curl -s -o /dev/null -w "HTTP %{http_code}\n" -X POST http://productpage.bookinfo.svc.cluster.local:9080/productpage'

A GET request from another service, such as the ratings pod in the bookinfo namespace, will also be denied with RBAC: access denied. This confirms that only requests from the explicitly allowed service account are permitted.:

$ oc exec "$(oc get pod -l app=ratings -n bookinfo \
-o jsonpath='{.items[0].metadata.name}')" \
-c ratings -n bookinfo \
-- curl -sS productpage:9080/productpage

Clean-up curl application

$ oc delete -n default -f https://raw.githubusercontent.com/openshift-service-mesh/istio/refs/heads/master/samples/curl/curl.yaml

48 changes: 48 additions & 0 deletions modules/ossm-routing-traffic-using-waypoint-proxies.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
// Module included in the following assemblies:

// * service-mesh-docs-main/install/ossm-istio-ambient-mode.adoc

:_mod-docs-content-type: PROCEDURE
[id="ossm-routing-traffic-using-waypoint-proxies_{context}"]
= Routing traffic using waypoint proxies

You can use a deployed waypoint proxy to split traffic between different versions of the Bookinfo `reviews` service for feature testing or A/B testing.

.Procedure

. Create the traffic routing configuration similar to the following example:
+
.Example configuration
[source,yaml]
----
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: reviews
namespace: bookinfo
spec:
parentRefs:
- group: ""
kind: Service
name: reviews
port: 9080
rules:
- backendRefs:
- name: reviews-v1
port: 9080
weight: 90
- name: reviews-v2
port: 9080
weight: 10
----

. Apply the traffic routing configuration by running the following command:
+
[source,terminal]
----
$ oc apply -f traffic-route.yaml
----

.Verification

* Open the `bookinfo` application in a web browser and refresh the page several times. Most requests (90%) are routed to `reviews-v1`, which displays no stars, while a smaller portion (10%) are routed to `reviews-v2`, which displays black stars.
Copy link

@unsortedhashsets unsortedhashsets Oct 13, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

Open the `bookinfo` application in a web browser and refresh the page several times. Most requests (90%) are routed to `reviews-v1`, which displays no stars, while a smaller portion (10%) are routed to `reviews-v2`, which displays black stars.

Need to replace verification section as we did not applied gw/route before to make bookinfo accessible in browser, like (example without doc styling) :

Run the following curl command from within the ratings pod to access the productpage. Most responses (90%) will contain reviews-v1, while a smaller portion (10%) will contain reviews-v2 output.

$ oc exec "$(oc get pod -l app=ratings -n bookinfo \
-o jsonpath='{.items[0].metadata.name}')" -c ratings -n bookinfo \
-- curl -sS productpage:9080/productpage | grep -om1 'reviews-v[12]'