From bf4939be8e8ff194cb5540d53eaaec63c51f0324 Mon Sep 17 00:00:00 2001 From: shreyasiddhartha Date: Mon, 27 Oct 2025 12:45:22 +0530 Subject: [PATCH] OSSM-11012 --- gateways/ossm-about-gateways.adoc | 6 +- gateways/ossm-directing-outbound-traffic.adoc | 3 + .../ossm-getting-traffic-into-a-mesh.adoc | 34 +- ...g-a-gateway-to-accept-ingress-traffic.adoc | 65 +--- ...services-to-traffic-outside-a-cluster.adoc | 1 + ...sm-about-ingress-routing-ambient-mode.adoc | 18 + ...-gateway-using-kubernetes-gateway-api.adoc | 2 +- ...de-the-cluster-using-openshift-routes.adoc | 11 +- ...ubernetes-gateway-api-in-ambient-mode.adoc | 309 ++++++++++++++++++ ...e-by-using-the-kubernetes-gateway-api.adoc | 71 ++-- ...sing-istio-gateway-and-virtualservice.adoc | 29 +- 11 files changed, 438 insertions(+), 111 deletions(-) create mode 100644 modules/ossm-about-ingress-routing-ambient-mode.adoc create mode 100644 modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api-in-ambient-mode.adoc diff --git a/gateways/ossm-about-gateways.adoc b/gateways/ossm-about-gateways.adoc index 86ae4c96d50d..c3921952d45c 100644 --- a/gateways/ossm-about-gateways.adoc +++ b/gateways/ossm-about-gateways.adoc @@ -6,7 +6,11 @@ include::_attributes/common-attributes.adoc[] toc::[] -A gateway is a standalone Envoy proxy deployment and an associated Kubernetes service operating at the edge of a service mesh. You can configure a gateway to provide fine-grained control over the traffic that enters or leaves the mesh. In {SMProductName}, you install gateways using gateway injection. +[role="_abstract"] +A gateway is a standalone Envoy proxy deployment and an associated Kubernetes service operating at the edge of a service mesh. You can configure a gateway to give fine-grained control over the traffic that enters or leaves the mesh. In {SMProductName}, you can install gateways by using gateway injection or via the Gateway API. + +{SMProductName} supports different gateway configurations based on the deployment mode. You can deploy gateways by using gateway injection and configure them with {istio} Gateway and `VirtualService` resources in sidecar mode or with {k8s} Gateway API resources in both sidecar and ambient modes. include::modules/ossm-about-gateway-injection.adoc[leveloffset=+1] + include::modules/ossm-installing-gateway-using-gateway-injection.adoc[leveloffset=+2] diff --git a/gateways/ossm-directing-outbound-traffic.adoc b/gateways/ossm-directing-outbound-traffic.adoc index 7a0e18447cde..280f6573ba6d 100644 --- a/gateways/ossm-directing-outbound-traffic.adoc +++ b/gateways/ossm-directing-outbound-traffic.adoc @@ -10,8 +10,11 @@ toc::[] Using {istio} APIs, you can configure gateway proxies that were installed using gateway injection to direct traffic that is bound for an external service. include::modules/ossm-about-directing-egress-traffic-through-a-gateway.adoc[leveloffset=+1] + include::modules/ossm-directing-egress-traffic-through-a-gateway-using-istio-apis.adoc[leveloffset=+1] + include::modules/ossm-directing-egress-traffic-through-a-gateway-using-kubernetes-gateway-api.adoc[leveloffset=+1] + include::modules/ossm-directing-egress-traffic-through-a-gateway-kubernetes-gateway-api-ambient-mode.adoc[leveloffset=+1] [role="_additional-resources-egress"] diff --git a/gateways/ossm-getting-traffic-into-a-mesh.adoc b/gateways/ossm-getting-traffic-into-a-mesh.adoc index 55e2e88604a6..5beae55de5db 100644 --- a/gateways/ossm-getting-traffic-into-a-mesh.adoc +++ b/gateways/ossm-getting-traffic-into-a-mesh.adoc @@ -6,12 +6,42 @@ include::_attributes/common-attributes.adoc[] toc::[] +[role="_abstract"] Using {istio} APIs, you can configure gateway proxies that were installed using gateway injection to accept traffic originating from outside the mesh, and route that traffic to the services within the mesh. You can expose gateway proxies to traffic outside a cluster by using either a `LoadBalancer` type `Service` or {ocp-short-name} `Routes`. include::modules/ossm-about-configuring-a-gateway-to-accept-ingress-traffic.adoc[leveloffset=+1] -include::modules/ossm-exposing-service-using-istio-gateway-and-virtualservice.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* xref:../gateways/ossm-about-gateways.adoc#ossm-about-gateway-injection_ossm-about-gateways[About gateway injection] + +include::modules/ossm-exposing-service-using-istio-gateway-and-virtualservice.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* https://istio.io/latest/docs/reference/config/networking/gateway/#Gateway[Istio Gateway resource API reference (Istio documentation)] +* https://istio.io/latest/docs/reference/config/networking/virtual-service/#VirtualService[VirtualService API reference (Istio documentation)] + include::modules/ossm-about-exposing-services-to-traffic-outside-a-cluster.adoc[leveloffset=+1] + include::modules/ossm-exposing-a-gateway-to-traffic-outside-the-cluster-using-openshift-routes.adoc[leveloffset=+2] -include::modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api.adoc[leveloffset=+1] \ No newline at end of file + +[role="_additional-resources"] +.Additional resources + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/networking/configuring-routes#nw-creating-a-route_route-configuration[Creating an HTTP-based Route] + +include::modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* link:https://kubernetes.io/docs/concepts/services-networking/gateway/[Kubernetes Gateway API concept (Kubernetes documentation)] + +include::modules/ossm-about-ingress-routing-ambient-mode.adoc[leveloffset=+1] + +include::modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api-in-ambient-mode.adoc[leveloffset=+1] \ No newline at end of file diff --git a/modules/ossm-about-configuring-a-gateway-to-accept-ingress-traffic.adoc b/modules/ossm-about-configuring-a-gateway-to-accept-ingress-traffic.adoc index 16d1b0a1ab95..28246a54f3de 100644 --- a/modules/ossm-about-configuring-a-gateway-to-accept-ingress-traffic.adoc +++ b/modules/ossm-about-configuring-a-gateway-to-accept-ingress-traffic.adoc @@ -1,66 +1,21 @@ // Module included in the following assemblies: -// gateways/ossm-about-gateways.adoc +// gateways/ossm-getting-traffic-into-a-mesh.adoc :_mod-docs-content-type: CONCEPT [id="ossm-about-configuring-a-gateway-to-accept-ingress-traffic_{context}"] -= About configuring a gateway installed using gateway injection to accept ingress traffic += About ingress traffic routing approaches -When you install a gateway using gateway injection you can configure it to receive ingress traffic using the {istio} `Gateway` and `VirtualService` resources in combination. The {istio} `Gateway` resource describes a load balancer operating at the edge of the mesh that receives incoming or outgoing HTTP/TCP connections. The `Gateway` specification describes a set of ports that should be exposed, the type of protocol to use, and the Server Name Indication (SNI) configuration for the load balancer. `VirtualServices` define routing rules to apply to an {istio} `Gateway`, similar to how you can use `VirtualServices` to define routing rules for internal mesh traffic. +[role="_abstract"] +{SMProductName} offers two approaches to configure ingress traffic routing to services in the mesh. The approach depends on the service mesh deployment mode and traffic management requirements. -In the following example an {istio} `Gateway` resource configures a gateway proxy to act as an entry point for external traffic. This configuration exposes port 443 (HTTPS) for the host, `bookinfo.com`. The example configuration applies to pods with the `istio: ingressgateway` label. The `tls` mode is configured as `SIMPLE`, which terminates the incoming HTTPS traffic using the certificate and private key the example provides. +Ingress routing with gateway injection and {istio} APIs:: +When you install a gateway by using gateway injection, you can configure it to receive ingress traffic by using the {istio} `Gateway` and `VirtualService` resources in combination. -.Sample configuration -[source,yaml,subs="attributes,verbatim"] ----- -apiVersion: networking.istio.io/v1 -kind: Gateway -metadata: - name: bookinfo-gateway - namespace: bookinfo -spec: - selector: - istio: ingressgateway - servers: - - port: - number: 443 - name: https-443 - protocol: HTTPS - hosts: - - bookinfo.com - tls: - mode: SIMPLE - serverCertificate: /etc/certs/servercert.pem - privateKey: /etc/certs/privatekey.pem ----- +The gateway injection approach is compatible with sidecar-based service mesh deployments where you enable sidecar injection in namespaces by using the `istio-injection=enabled` label or the `istio.io/rev=` label. -The following `VirtualService` is bound to the {istio} `Gateway` resource shown in the previous example configuration. The specification defines rules to route traffic with the `/reviews/` path prefix to the reviews service in the `bookinfo` namespace. The `VirtualService` explicitly references the `Gateway` resource shown previously. This ensures that the routing rules are only applied to the traffic that enters through the specified gateway. +Ingress routing with {k8s} Gateway API:: -.Sample configuration -[source,yaml,subs="attributes,verbatim"] ----- -kind: VirtualService -metadata: - name: bookinfo-rule - namespace: bookinfo -spec: - hosts: - - bookinfo.com - gateways: - - bookinfo/bookinfo-gateway - http: - - match: - - uri: - prefix: /reviews/ - route: - - destination: - port: - number: 9080 - host: reviews.bookinfo.svc.cluster.local ----- +The {k8s} Gateway API provides a standardized approach for configuring ingress traffic routing using native {k8s} resources. With this approach, you use `Gateway` and `HTTPRoute` (or `GRPCRoute`) resources to configure how traffic enters the mesh and routes to services. -[role="_additional-resources"] -[id="ossm-about-configuring-gateways-additional-resources_{context}"] -.Additional resources - -* xref:../gateways/ossm-about-gateways.adoc#ossm-about-gateway-injection_ossm-about-gateways[About gateway injection] +While {istio} `Gateway` and `VirtualService` resources can be used for certain ingress use cases in ambient mode, the recommended approach is to use the {k8s} Gateway API, which provides full support and integration with ambient. You can also use the Gateway API with sidecar-based deployments. \ No newline at end of file diff --git a/modules/ossm-about-exposing-services-to-traffic-outside-a-cluster.adoc b/modules/ossm-about-exposing-services-to-traffic-outside-a-cluster.adoc index 1f7d00f55a09..25f658eed813 100644 --- a/modules/ossm-about-exposing-services-to-traffic-outside-a-cluster.adoc +++ b/modules/ossm-about-exposing-services-to-traffic-outside-a-cluster.adoc @@ -6,6 +6,7 @@ [id="ossm-about-exposing-services-to-traffic-outside-a-cluster_{context}"] = About exposing services to traffic outside a cluster +[role="_abstract"] To enable traffic from outside an {ocp-short-name} cluster to access services in a mesh, you must expose a gateway proxy by either setting its `Service` type to `LoadBalancer` or by using the {ocp-short-name} Router. Using Kubernetes load balancing to handle incoming traffic directly through the inbound gateway can reduce latency associated with data encryption. By managing encryption at the inbound gateway, you avoid the intermediate decryption and re-encryption steps within the mesh that often add latency. This approach allows mesh traffic to be encrypted and decrypted only once, which is generally more efficient. diff --git a/modules/ossm-about-ingress-routing-ambient-mode.adoc b/modules/ossm-about-ingress-routing-ambient-mode.adoc new file mode 100644 index 000000000000..7163896e75f0 --- /dev/null +++ b/modules/ossm-about-ingress-routing-ambient-mode.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: + +// gateways/ossm-getting-traffic-into-a-mesh.adoc + +:_mod-docs-content-type: CONCEPT +[id="ossm-about-ingress-routing-ambient-mode_{context}"] += About ingress traffic routing approaches in ambient mode + +[role="_abstract"] +When using the {istio} ambient mode, you can use the {k8s} Gateway API to configure ingress traffic routing. + +Waypoint proxies for Layer 7 routing:: +You can deploy a waypoint proxy in the namespace that has your service to apply Layer 7 (L7) routing policies, such as path-based routing or header matching. In ambient mode, waypoint proxies process L7 traffic and enforce `HTTPRoute` and `GRPCRoute` rules. + +[IMPORTANT] +==== +`VirtualService` resources are considered technology preview in ambient mode and should not be mixed with Gateway API configuration. The recommended approach in ambient mode is to use {k8s} Gateway API resources. +==== diff --git a/modules/ossm-directing-egress-traffic-through-a-gateway-using-kubernetes-gateway-api.adoc b/modules/ossm-directing-egress-traffic-through-a-gateway-using-kubernetes-gateway-api.adoc index 97aefe056e50..12ff0453546f 100644 --- a/modules/ossm-directing-egress-traffic-through-a-gateway-using-kubernetes-gateway-api.adoc +++ b/modules/ossm-directing-egress-traffic-through-a-gateway-using-kubernetes-gateway-api.adoc @@ -16,7 +16,7 @@ Use the {k8s} Gateway API to direct outbound HTTP traffic through an egress gate .Procedure -. Optional: Enable the {k8} Gateway API custom resource definitions (CRDs). +. Optional: Enable the {k8s} Gateway API custom resource definitions (CRDs). + [NOTE] ==== diff --git a/modules/ossm-exposing-a-gateway-to-traffic-outside-the-cluster-using-openshift-routes.adoc b/modules/ossm-exposing-a-gateway-to-traffic-outside-the-cluster-using-openshift-routes.adoc index 8095c6764986..f1167217b659 100644 --- a/modules/ossm-exposing-a-gateway-to-traffic-outside-the-cluster-using-openshift-routes.adoc +++ b/modules/ossm-exposing-a-gateway-to-traffic-outside-the-cluster-using-openshift-routes.adoc @@ -5,6 +5,7 @@ [id="ossm-exposing-a-gateway-to-traffic-outside-the-cluster-using-openshift-routes_{context}"] = Exposing a gateway to traffic outside the cluster by using OpenShift Routes +[role="_abstract"] You can expose a gateway to traffic outside the cluster by using {ocp-short-name} Routes. This approach provides an alternative to using Kubernetes load balancer service when you have to expose gateways to traffic outside the cluster. .Prerequisites @@ -22,7 +23,7 @@ $ oc patch service -n -p '{"spec": {"type": " . Create a YAML file named `httpbin-route.yaml` that defines a `Route` for the `httpbin` service. + -[source,yaml,subs="attributes,verbatim"] +[source,yaml] ---- apiVersion: route.openshift.io/v1 kind: Route @@ -70,10 +71,4 @@ $ INGRESS_HOST=$(oc get service router-default -n openshift-ingress -o jsonpath= $ curl -s -I -H Host:httpbin.example.com http://$INGRESS_HOST/headers ---- -. Verify that the response has the `HTTP/1.1 200 OK` status, which indicates that the request was successful. - -[role="_additional-resources"] -[id="ossm-exposing-gateway-outside-cluster-additional-resources_{context}"] -.Additional resources - -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/networking/configuring-routes#nw-creating-a-route_route-configuration[Creating an HTTP-based Route] \ No newline at end of file +. Verify that the response has the `HTTP/1.1 200 OK` status, which indicates that the request was successful. \ No newline at end of file diff --git a/modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api-in-ambient-mode.adoc b/modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api-in-ambient-mode.adoc new file mode 100644 index 000000000000..faed6ef335eb --- /dev/null +++ b/modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api-in-ambient-mode.adoc @@ -0,0 +1,309 @@ +// Module included in the following assemblies: +// * service-mesh-docs-main/gateways/ossm-getting-traffic-into-a-mesh.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ossm-exposing-a-service-by-using-the-kubernetes-gateway-api-in-ambient-mode_{context}"] += Exposing a service by using the {k8s} Gateway API in ambient mode + +[role="_abstract"] +You can use the {k8s} Gateway API to create `Gateway` and `HTTPRoute` resources and deploy a gateway in ambient mode. The resources configure the gateway to expose a service in the mesh to traffic outside the mesh. + +.Prerequisites + +* You are logged in to the {ocp-product-title} web console as a user with the `cluster-admin` role. + +* You have installed the {SMProductName} Operator. + +* You have deployed the `{istio}` resource. + +* You use the {k8s}-native Gateway API resources. + +* You are either using the {istio} ambient mode or planning on migrating to the ambient mode. + +[NOTE] +==== +When using ambient mode (`istio.io/dataplane-mode=ambient`), it is recommended to use the {k8s} Gateway API for ingress configuration, as {istio} `Gateway` and `VirtualService` resources are not fully compatible with ambient mode. +==== + +.Procedure + +. Create a namespace called `httpbin` by running the following command: ++ +[source,terminal] +---- +$ oc create namespace httpbin +---- + +. Apply the label for ambient mode by running the following command: ++ +[source,terminal] +---- +$ oc label namespace httpbin istio.io/dataplane-mode=ambient +---- + +. Deploy a sample service named `httpbin` by running the following command: ++ +[source,terminal] +---- +$ oc apply -n httpbin -f https://raw.githubusercontent.com/openshift-service-mesh/istio/refs/heads/master/samples/httpbin/httpbin.yaml +---- + +. Deploy a waypoint proxy by creating a YAML file named `httpbin-waypoint.yaml`, similar to the following example: ++ +[source,yaml] +---- +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: httpbin-waypoint + namespace: httpbin + labels: + istio.io/waypoint-for: service +spec: + gatewayClassName: istio-waypoint + listeners: + - name: mesh + port: 15008 + protocol: HBONE + +---- + +. Apply the YAML file by running the following command: ++ +[source,terminal] +---- +$ oc apply -f httpbin-waypoint.yaml +---- + +. Enable ingress waypoint routing on the `httpbin` service by running the following command: ++ +[source,terminal] +---- +$ oc label service httpbin -n httpbin istio.io/ingress-use-waypoint=true +---- ++ +The label ensures that traffic from the ingress gateway routes through the waypoint proxy and the L7 policies configured on the waypoint proxy are applied to the ingress traffic, before it reaches the `httpbin` service. + +. Apply the waypoint label to the namespace so that all the services inside the namespace routes through the waypoint, by running the following command: ++ +[source,terminal] +---- +$ oc label ns httpbin istio.io/use-waypoint=httpbin-waypoint +---- + +. Create a YAML file named `httpbin-gw.yaml` that defines a {k8s} Gateway resource. This resource configures gateway proxies to expose port 80 (HTTP) for the host, `httpbin.example.com`. ++ +[source,yaml] +---- +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: httpbin-gateway + namespace: httpbin +spec: + gatewayClassName: istio + listeners: + - name: default + hostname: "httpbin.example.com" + port: 80 + protocol: HTTP + allowedRoutes: + namespaces: + from: All +---- +`"httpbin.example.com"`:: Specifies the virtual hostname that clients use when attempting to access a mesh service on the associated port. + +. Apply the YAML file by running the following command: ++ +[source,terminal] +---- +$ oc apply -f httpbin-gw.yaml +---- + +. Create a YAML file named `httpbin-ingress-hr.yaml` that defines an `HTTPRoute` resource for the ingress gateway, similar to the following example: ++ +[source,yaml] +---- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: httpbin-ingress + namespace: httpbin +spec: + parentRefs: + - name: httpbin-gateway + namespace: httpbin + hostnames: + - "httpbin.example.com" + rules: + - backendRefs: + - name: httpbin + port: 8000 +---- +* `spec.parentRefs` binds the `HTTPROUTE` resource to the {k8s} Gateway resource that was created in the earlier step. + +* `spec.rules.backendRefs` routes the matching traffic to the `httpbin` service by defining a `backendRefs` that includes the name and port of the `httpbin` service. + ++ +The `HTTPRoute` resource specifies the rules that route traffic from the gateway proxy to the `httpbin` service. + +. Apply the YAML file by running the following command: ++ +[source,terminal] +---- +$ oc apply -f httpbin-ingress-hr.yaml +---- + +. Create a YAML file named `httpbin-waypoint-hr.yaml` that defines an `HTTPRoute` resource for the waypoint proxy. ++ +[source,yaml] +---- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: httpbin-waypoint-route + namespace: httpbin +spec: + parentRefs: + - name: httpbin-waypoint + namespace: httpbin + rules: + - matches: + - path: + type: PathPrefix + value: /status + - path: + type: PathPrefix + value: /headers + backendRefs: + - name: httpbin + port: 8000 + +---- +* `spec.parentRefs` binds the `HTTPROUTE` resource to the waypoint Gateway resource. It configures L7 routing rules that the waypoint will enforce. + +* `spec.rules.backendRefs` routes the matching traffic to the `httpbin` service by defining a `backendRefs` that includes the name and port of the `httpbin` service. + +. Apply the YAML file by running the following command: ++ +[source,terminal] +---- +$ oc apply -f httpbin-waypoint-hr.yaml +---- + +[NOTE] +==== +In this example use case, traffic from the ingress gateway flows through the waypoint proxy because of the `istio.io/ingress-use-waypoint=true` label. The `HTTPRoute` resource then applies path-based routing policies before the traffic reaches the httpbin service. +==== + +. Ensure that the waypoint proxy is ready by running the following command: ++ +[source,terminal] +---- +$ oc wait --for=condition=programmed gtw httpbin-waypoint -n httpbin +---- + +.Verification + +. Create a namespace for a `curl` client by running the following command: ++ +[source,terminal] +---- +$ oc create namespace curl +---- + +. Deploy a `curl` client by running the following command: ++ +[source,terminal] +---- +$ oc apply -n curl +---- + +. Apply the label for ambient mode to the `curl` namespace by running the following command: ++ +[source,terminal] +---- +$ oc label namespace curl istio.io/dataplane-mode=ambient +---- + +. Set a `CURL_POD` variable with the name of the `curl` pod by running the following command: ++ +[source,terminal] +---- +$ CURL_POD=$(oc get pods -n curl -l app=curl -o jsonpath='{.items[*].metadata.name}') +---- + +. Using the `curl` client, send a request to the `/headers` endpoint of the `httpbin` application through the ingress gateway `Service` resource. Set the Host header of the request to `httpbin.example.com` to match the host that the {k8s} Gateway and `HTTPROUTE` resources specify. Send the `curl` request by running the following command: ++ +[source,terminal] +---- +$ oc exec $CURL_POD -n curl -- \ + curl -s -I \ + -H Host:httpbin.example.com \ + -istio..svc.cluster.local/headers +---- ++ +The response should return a `200 OK` HTTP status, which indicates that the request was successful, similar to the following example: ++ +[source,terminal] +---- +HTTP/1.1 200 OK +server: istio-envoy +... +---- + +. Send a `curl` request to an endpoint that does not have a corresponding Uniform Resource Identifier (URI) prefix match defined in the `httpbin` `HTTPROUTE` by running the following command: ++ +[source,terminal] +---- +$ oc exec $CURL_POD -n curl -- \ + curl -s -I \ + -H Host:httpbin.example.com \ + -istio..svc.cluster.local/get +---- ++ +The response returns a `404 Not Found` status, as expected, because the `/get` endpoint does not have a matching URI prefix in the `httpbin` `HTTPROUTE` resource, similar to the following example: ++ +[source,terminal] +---- +HTTP/1.1 404 Not Found +server: istio-envoy +... +---- + +. Expose the gateway proxy to traffic outside the cluster by setting the `Service` type to `LoadBalancer`. Run the following command: ++ +[source,terminal] +---- +$ oc patch service -istio -n -p '{"spec": {"type": "LoadBalancer"}}' +---- ++ +[NOTE] +==== +A gateway can also be exposed to traffic outside the cluster by using {ocp-short-name} Routes. For more information, see "Exposing a gateway to traffic outside the cluster using {ocp-short-name} Routes". +==== + +. Verify that the `httpbin` service can be accessed from outside the cluster when using the external hostname or IP address of the gateway Service resource. Ensure that you set the `INGRESS_HOST` variable appropriately for the environment in which your cluster is running. + +.. Set the `INGRESS_HOST` variable by running the following command: ++ +[source,terminal] +---- +$ export INGRESS_HOST=$(oc get gtw -n -o jsonpath='{.status.addresses[0].value}') +---- + +.. Set the `INGRESS_PORT` variable by running the following command: ++ +[source,terminal] +---- +$ INGRESS_PORT=$(oc get gtw -n -o jsonpath='{.spec.listeners[?(@.name=="http")].port}') +---- + +.. Using the gateway host, send a `curl` request to the `httpbin` service by running the following command: ++ +[source,terminal] +---- +$ curl -s -I -H Host:httpbin.example.com http://$INGRESS_HOST:$INGRESS_PORT/headers +---- + +. Verify that the response has the `HTTP/1.1 200 OK` status, which indicates that the request was successful. diff --git a/modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api.adoc b/modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api.adoc index f100c0fb62e4..9273ee5dcceb 100644 --- a/modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api.adoc +++ b/modules/ossm-exposing-a-service-by-using-the-kubernetes-gateway-api.adoc @@ -3,9 +3,10 @@ :_mod-docs-content-type: PROCEDURE [id="ossm-exposing-a-service-by-using-the-kubernetes-gateway-api_{context}"] -= Exposing a service by using the {k8s} Gateway API += Exposing a service by using the {k8s} Gateway API in sidecar mode -Use the {k8s} Gateway API to create `Gateway` and `HTTPRoute` resources and deploy a gateway. The resources configure the gateway to expose a service in the mesh to traffic outside the mesh. Then, you can set the `Service` for the gateway to `LoadBalancer` to expose the gateway to traffic outside the cluster. +[role="_abstract"] +You can use the {k8s} Gateway API to create `Gateway` and `HTTPRoute` resources and deploy a gateway. The resources configure the gateway to expose a service in the mesh to traffic outside the mesh. .Prerequisites @@ -13,7 +14,7 @@ Use the {k8s} Gateway API to create `Gateway` and `HTTPRoute` resources and depl * You installed the {SMProductName} Operator. -* You deployed the {istio} resource. +* You have deployed the `{istio}` resource. .Procedure @@ -24,6 +25,22 @@ Use the {k8s} Gateway API to create `Gateway` and `HTTPRoute` resources and depl $ oc create namespace httpbin ---- +. When using sidecar injection instead of ambient mode, you must enable the sidecar injection in the namespace: + +.. For the `InPlace` upgrade strategy, run the following command: ++ +[source,terminal] +---- +$ oc label namespace httpbin istio-injection=enabled +---- + +.. For the `RevisionBased` upgrade strategy, run the following command: ++ +[source,terminal] +---- +$ oc label namespace httpbin istio.io/rev= +---- + . Deploy a sample service named `httpbin` by running the following command: + [source,terminal] @@ -31,10 +48,9 @@ $ oc create namespace httpbin $ oc apply -n httpbin -f https://raw.githubusercontent.com/openshift-service-mesh/istio/refs/heads/master/samples/httpbin/httpbin.yaml ---- -. Create a YAML file named `httpbin-gw.yaml` that defines a {k8s} Gateway resource. This resource configures gateway proxies to expose port 80 (HTTP) for the host, `httpbin.example.com`. +. Create a YAML file named `httpbin-gw.yaml` that defines a {k8s} Gateway resource, similar to the following example: + -.Example gateway resource file -[source,yaml,subs="attributes,verbatim"] +[source,yaml] ---- apiVersion: gateway.networking.k8s.io/v1 kind: Gateway @@ -45,14 +61,17 @@ spec: gatewayClassName: istio listeners: - name: default - hostname: "httpbin.example.com" # <1> + hostname: "httpbin.example.com" port: 80 protocol: HTTP allowedRoutes: namespaces: from: All ---- -<1> Specifies the virtual hostname that clients use when attempting to access a mesh service on the associated port. +`"httpbin.example.com"`:: Specifies the virtual hostname that clients use when attempting to access a mesh service on the associated port. + ++ +The `HTTPRoute` resource specifies the rules that route traffic from the gateway proxy to the `httpbin` service. . Apply the YAML file by running the following command: + @@ -61,20 +80,21 @@ spec: $ oc apply -f httpbin-gw.yaml ---- -. Create a YAML file named `httpbin-hr.yaml` that defines an `HTTPRoute` resource. The `HTTPRoute` resource specifies the rules that route traffic from the gateway proxy to the `httpbin` service. +. Create a YAML file named `httpbin-ingress-hr.yaml` that defines an `HTTPRoute` resource for the ingress gateway, similar to the following example: + -.Example HTTPRoute file -[source,yaml,subs="attributes,verbatim"] +[source,yaml] ---- apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: - name: httpbin + name: httpbin-ingress namespace: httpbin spec: - parentRefs: # <1> + parentRefs: - name: httpbin-gateway namespace: httpbin + hostnames: + - "httpbin.example.com" rules: - matches: - path: @@ -83,18 +103,22 @@ spec: - path: type: PathPrefix value: /headers - backendRefs: # <2> + - backendRefs: - name: httpbin port: 8000 ---- -<1> Binds the `HTTPROUTE` resource to the {k8s} Gateway resource that was created in the previous step by adding the name of the gateway resource to the list of gateways. -<2> Routes the matching traffic to the `httpbin` service by defining a `backendRefs` that includes the name and port of the `httpbin` Service. +* `spec.parentRefs` binds the `HTTPROUTE` resource to the {k8s} Gateway resource that was created in the earlier step. + +* `spec.rules.backendRefs` routes the matching traffic to the `httpbin` service by defining a `backendRefs` that includes the name and port of the `httpbin` service. + ++ +The `HTTPRoute` resource specifies the rules that route traffic from the gateway proxy to the `httpbin` service. . Apply the YAML file by running the following command: + [source,terminal] ---- -$ oc apply -f httpbin-hr.yaml +$ oc apply -f httpbin-ingress-hr.yaml ---- . Ensure that the Gateway API service is ready, and that an address is allocated to the service, by running the following command: @@ -137,9 +161,7 @@ $ oc exec $CURL_POD -n curl -- \ -istio..svc.cluster.local/headers ---- + -The response should return a `200 OK` HTTP status, which indicates that the request was successful. -+ -.Example output +The response should return a `200 OK` HTTP status, which indicates that the request was successful, similar to the following example: + [source,terminal] ---- @@ -158,9 +180,7 @@ $ oc exec $CURL_POD -n curl -- \ -istio..svc.cluster.local/get ---- + -The response returns a `404 Not Found` status. This is expected because the `/get` endpoint does not have a matching URI prefix in the `httpbin` `HTTPROUTE` resource. -+ -.Example output +The response returns a `404 Not Found` status, as expected, because the `/get` endpoint does not have a matching URI prefix in the `httpbin` `HTTPROUTE` resource, similar to the following example: + [source,terminal] ---- @@ -205,8 +225,3 @@ $ curl -s -I -H Host:httpbin.example.com http://$INGRESS_HOST:$INGRESS_PORT/head ---- . Verify that the response has the `HTTP/1.1 200 OK` status, which indicates that the request was successful. - -[role="_additional-resources"] -.Additional resources - -* link:https://kubernetes.io/docs/concepts/services-networking/gateway/[Kubernetes Gateway API concept] (Kubernetes documentation) diff --git a/modules/ossm-exposing-service-using-istio-gateway-and-virtualservice.adoc b/modules/ossm-exposing-service-using-istio-gateway-and-virtualservice.adoc index 7b66ddd7e55f..3d0e84b69133 100644 --- a/modules/ossm-exposing-service-using-istio-gateway-and-virtualservice.adoc +++ b/modules/ossm-exposing-service-using-istio-gateway-and-virtualservice.adoc @@ -5,11 +5,17 @@ [id="ossm-exposing-service-using-istio-gateway-and-virtualservice_{context}"] = Exposing a service by using the {istio} Gateway and VirtualService resources -This procedure uses the {istio} `Gateway` and `VirtualService` resources to configure a gateway that was deployed by using gateway injection. The resources configure the gateway to expose a service in the mesh to traffic outside the mesh. Then, you expose the gateway to traffic outside the cluster by setting the `Service` for the gateway to type `LoadBalancer`. +[role="_abstract"] +You can use the {istio} `Gateway` and `VirtualService` resources to configure a gateway that was deployed by using gateway injection. The resources expose a service in the mesh to traffic outside the mesh. You can set the gateway `Service` type to `LoadBalancer` to allow traffic from outside the cluster. .Prerequisites -* You have installed an {istio} gateway using gateway injection. +* You have installed {istio} gateways using gateway injection. + +* You are using the {istio} `Gateway` and `VirtualService` resources. + +* You have existing `VirtualService` configurations and do not plan on migrating to ambient mode. + .Procedure @@ -37,13 +43,13 @@ If you are using the `RevisionBased` upgrade strategy, run the following command ---- $ oc get istiorevisions.sailoperator.io ---- -+ -.Sample output: +You will get an output similar to the following example: [source,terminal] ---- NAME TYPE READY STATUS IN USE VERSION AGE default Local True Healthy True v1.24.3 3m33s ---- + . Label the namespace with the revision name to enable sidecar injection: + [source, terminal] @@ -61,7 +67,7 @@ $ oc apply -n httpbin -f https://raw.githubusercontent.com/openshift-service-mes . Create a YAML file named `httpbin-gw.yaml` that defines an {istio} `Gateway` resource. This resource configures gateway proxies to expose port 80 (HTTP) for the host, `httpbin.example.com`. + -[source,yaml,subs="attributes,verbatim"] +[source,yaml] ---- apiVersion: networking.istio.io/v1 kind: Gateway @@ -91,7 +97,7 @@ $ oc apply -f httpbin-gw.yaml . Create a YAML file named `httpbin-vs.yaml` for a `VirtualService`. The `VirtualService` defines the rules that route traffic from the gateway proxy to the `httpbin` service. + -[source,yaml,subs="attributes,verbatim"] +[source,yaml] ---- apiVersion: networking.istio.io/v1 kind: VirtualService @@ -159,7 +165,6 @@ $ oc exec $CURL_POD -n curl -- \ . The response should have a `200 OK HTTP` status indicating that the request was successful. + -.Example output [source,terminal] ---- HTTP/1.1 200 OK @@ -179,7 +184,6 @@ $ oc exec $CURL_POD -n curl -- \ + The response should return a `404 Not Found` status. This is expected because the `/get` endpoint does not have a matching URI prefix in the `httpbin` `VirtualService` resource. + -.Example output [source,terminal] ---- HTTP/1.1 404 Not Found @@ -222,11 +226,4 @@ $ INGRESS_HOST=$(oc get service -n -o jsonpat $ curl -s -I -H Host:httpbin.example.com http://$INGRESS_HOST/headers ---- -. Verify that the response has the `HTTP/1.1 200 OK` status, which indicates that the request was successful. - -[role="_additional-resources"] -[id="ossm-exposing-service-additional-resources_{context}"] -.Additional resources - -* https://istio.io/latest/docs/reference/config/networking/gateway/#Gateway[Istio Gateway resource API reference] (Istio documentation) -* https://istio.io/latest/docs/reference/config/networking/virtual-service/#VirtualService[VirtualService API reference] (Istio documentation) \ No newline at end of file +. Verify that the response has the `HTTP/1.1 200 OK` status, which indicates that the request was successful. \ No newline at end of file