From 69981b01b186f449297e107becc13f62bd2c5969 Mon Sep 17 00:00:00 2001 From: Frank Budinsky Date: Thu, 10 Nov 2022 14:32:57 -0500 Subject: [PATCH] gateway-api: add gateway api instruction to request routing task (#12204) * gateway-api: add gateway api instruction to request routing task * lint * regen * improve gamma tip/warning * lint * add port * fix samples.sh * fixes --- content/en/boilerplates/gateway-api-choose.md | 5 + .../boilerplates/gateway-api-gamma-support.md | 18 + .../en/boilerplates/gateway-api-support.md | 4 +- .../snips/gateway-api-gamma-support.sh | 25 ++ .../ingress/gateway-api/index.md | 4 +- .../request-routing/gtwapi_test.sh | 29 ++ .../request-routing/index.md | 353 ++++++++++++------ .../request-routing/snips.sh | 102 ++++- .../request-routing/test.sh | 62 +-- tests/util/samples.sh | 31 +- 10 files changed, 492 insertions(+), 141 deletions(-) create mode 100644 content/en/boilerplates/gateway-api-choose.md create mode 100644 content/en/boilerplates/gateway-api-gamma-support.md create mode 100644 content/en/boilerplates/snips/gateway-api-gamma-support.sh create mode 100644 content/en/docs/tasks/traffic-management/request-routing/gtwapi_test.sh diff --git a/content/en/boilerplates/gateway-api-choose.md b/content/en/boilerplates/gateway-api-choose.md new file mode 100644 index 0000000000..ce0178c488 --- /dev/null +++ b/content/en/boilerplates/gateway-api-choose.md @@ -0,0 +1,5 @@ +--- +--- +The following instructions allow you to choose to use either the Gateway API or the Istio configuration API when configuring +traffic management in the mesh. Follow instructions under either the `Gateway API` or `Istio classic` tab, +according to your preference. diff --git a/content/en/boilerplates/gateway-api-gamma-support.md b/content/en/boilerplates/gateway-api-gamma-support.md new file mode 100644 index 0000000000..c976c1d187 --- /dev/null +++ b/content/en/boilerplates/gateway-api-gamma-support.md @@ -0,0 +1,18 @@ +--- +--- +{{< tip >}} +{{< boilerplate gateway-api-future >}} +{{< boilerplate gateway-api-choose >}} + +Note that this document uses the Gateway API to configure internal mesh (east-west) traffic, +i.e., not just ingress (north-south) traffic. +Configuring internal mesh traffic using the Gateway API is an +[experimental feature](https://gateway-api.sigs.k8s.io/concepts/versioning/#release-channels-eg-experimental-standard) +currently under development and pending [upstream agreement](https://gateway-api.sigs.k8s.io/contributing/gamma/). +Make sure to install the experimental CRDs before using the Gateway API: + +{{< text syntax=bash snip_id=install_experimental_crds >}} +$ kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref={{< k8s_gateway_api_version >}}" | kubectl apply -f - +{{< /text >}} + +{{< /tip >}} diff --git a/content/en/boilerplates/gateway-api-support.md b/content/en/boilerplates/gateway-api-support.md index 727510a47b..6120118776 100644 --- a/content/en/boilerplates/gateway-api-support.md +++ b/content/en/boilerplates/gateway-api-support.md @@ -2,9 +2,7 @@ --- {{< tip >}} {{< boilerplate gateway-api-future >}} -The following instructions allow you to choose to use either the Gateway API or the Istio configuration API when configuring -traffic management in the mesh. Follow instructions under either the `Gateway API` or `Istio classic` tab, -according to your preference. +{{< boilerplate gateway-api-choose >}} Note that the Kubernetes Gateway API CRDs do not come installed by default on most Kubernetes clusters, so make sure they are installed before using the Gateway API: diff --git a/content/en/boilerplates/snips/gateway-api-gamma-support.sh b/content/en/boilerplates/snips/gateway-api-gamma-support.sh new file mode 100644 index 0000000000..b619096295 --- /dev/null +++ b/content/en/boilerplates/snips/gateway-api-gamma-support.sh @@ -0,0 +1,25 @@ +#!/bin/bash +# shellcheck disable=SC2034,SC2153,SC2155,SC2164 + +# Copyright Istio Authors. All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +#################################################################################################### +# WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL MARKDOWN FILE: +# boilerplates/gateway-api-gamma-support.md +#################################################################################################### + +bpsnip_gateway_api_gamma_support_install_experimental_crds() { +kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=v0.5.1" | kubectl apply -f - +} diff --git a/content/en/docs/tasks/traffic-management/ingress/gateway-api/index.md b/content/en/docs/tasks/traffic-management/ingress/gateway-api/index.md index 6f5caeb08e..36a078ee3d 100644 --- a/content/en/docs/tasks/traffic-management/ingress/gateway-api/index.md +++ b/content/en/docs/tasks/traffic-management/ingress/gateway-api/index.md @@ -252,7 +252,7 @@ currently under development and pending [upstream agreement](https://gateway-api {{< /warning >}} The Gateway API can also be used to configure mesh traffic. -This is done by configuring the `parentRef` to point to a service, instead of a gateway. +This is done by configuring the `parentRef` to point to a service, instead of a gateway. For example, to add a header on all calls to an in-cluster `Service` named `example`: @@ -277,6 +277,8 @@ spec: port: 80 {{< /text >}} +More details and examples can be found in other [traffic management tasks](/docs/tasks/traffic-management/). + ## Cleanup 1. Uninstall Istio and the `httpbin` sample: diff --git a/content/en/docs/tasks/traffic-management/request-routing/gtwapi_test.sh b/content/en/docs/tasks/traffic-management/request-routing/gtwapi_test.sh new file mode 100644 index 0000000000..306d344b50 --- /dev/null +++ b/content/en/docs/tasks/traffic-management/request-routing/gtwapi_test.sh @@ -0,0 +1,29 @@ +#!/usr/bin/env bash +# shellcheck disable=SC1090,SC2154 + +# Copyright Istio Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +source "tests/util/gateway-api.sh" +install_gateway_api_crds + +# @setup profile=default +source "content/en/docs/tasks/traffic-management/request-routing/test.sh" + +# @cleanup +source "tests/util/samples.sh" +snip_cleanup_2 +cleanup_bookinfo_sample +cleanup_sleep_sample +remove_gateway_api_crds diff --git a/content/en/docs/tasks/traffic-management/request-routing/index.md b/content/en/docs/tasks/traffic-management/request-routing/index.md index ff4b3b390f..eb028b0769 100644 --- a/content/en/docs/tasks/traffic-management/request-routing/index.md +++ b/content/en/docs/tasks/traffic-management/request-routing/index.md @@ -12,6 +12,8 @@ test: yes This task shows you how to route requests dynamically to multiple versions of a microservice. +{{< boilerplate gateway-api-gamma-support >}} + ## Before you begin * Setup Istio by following the instructions in the @@ -19,13 +21,16 @@ microservice. * Deploy the [Bookinfo](/docs/examples/bookinfo/) sample application. -* Review the [Traffic Management](/docs/concepts/traffic-management) concepts doc. Before attempting this task, you should be familiar with important terms such as *destination rule*, *virtual service*, and *subset*. +* Review the [Traffic Management](/docs/concepts/traffic-management) concepts doc. ## About this task The Istio [Bookinfo](/docs/examples/bookinfo/) sample consists of four separate microservices, each with multiple versions. Three different versions of one of the microservices, `reviews`, have been deployed and are running concurrently. To illustrate the problem this causes, access the Bookinfo app's `/productpage` in a browser and refresh several times. +The URL is `http://$GATEWAY_URL/productpage`, where `$GATEWAY_URL` is the External IP address of the ingress, as explained in +the [Bookinfo](/docs/examples/bookinfo/#determine-the-ingress-ip-and-port) doc. + You’ll notice that sometimes the book review output contains star ratings and other times it does not. This is because without an explicit default service version to route to, Istio routes requests to all available versions in a round robin fashion. @@ -33,79 +38,168 @@ in a round robin fashion. The initial goal of this task is to apply rules that route all traffic to `v1` (version 1) of the microservices. Later, you will apply a rule to route traffic based on the value of an HTTP request header. -## Apply a virtual service +## Route to version 1 -To route to one version only, you apply virtual services that set the default version for the microservices. -In this case, the virtual services will route all traffic to `v1` of each microservice. +To route to one version only, you configure route rules that send traffic to default versions for the microservices. {{< warning >}} -If you haven't already applied destination rules, follow the instructions in [Apply Default Destination Rules](/docs/examples/bookinfo/#apply-default-destination-rules). +If you haven't already, follow the instructions in [define the service versions](/docs/examples/bookinfo/#define-the-service-versions). {{< /warning >}} -1. Run the following command to apply the virtual services: +1. Run the following command to create the route rules: - {{< text bash >}} - $ kubectl apply -f @samples/bookinfo/networking/virtual-service-all-v1.yaml@ - {{< /text >}} +{{< tabset category-name="config-api" >}} - Because configuration propagation is eventually consistent, wait a few seconds - for the virtual services to take effect. +{{< tab name="Istio classic" category-value="istio-classic" >}} -1. Display the defined routes with the following command: +Istio uses virtual services to define route rules. +Run the following command to apply virtual services that will route all traffic to `v1` of each microservice: - {{< text bash yaml >}} - $ kubectl get virtualservices -o yaml - - apiVersion: networking.istio.io/v1beta1 - kind: VirtualService - ... - spec: - hosts: - - details - http: - - route: - - destination: - host: details - subset: v1 - - apiVersion: networking.istio.io/v1beta1 - kind: VirtualService - ... - spec: - hosts: - - productpage - http: - - route: - - destination: - host: productpage - subset: v1 - - apiVersion: networking.istio.io/v1beta1 - kind: VirtualService - ... - spec: - hosts: - - ratings - http: - - route: - - destination: - host: ratings - subset: v1 - - apiVersion: networking.istio.io/v1beta1 - kind: VirtualService - ... - spec: - hosts: - - reviews - http: - - route: - - destination: - host: reviews - subset: v1 - {{< /text >}} +{{< text bash >}} +$ kubectl apply -f @samples/bookinfo/networking/virtual-service-all-v1.yaml@ +{{< /text >}} -1. You can also display the corresponding `subset` definitions with the following command: +Because configuration propagation is eventually consistent, wait a few seconds +for the virtual services to take effect. - {{< text bash >}} - $ kubectl get destinationrules -o yaml - {{< /text >}} +{{< /tab >}} + +{{< tab name="Gateway API" category-value="gateway-api" >}} + +{{< text bash >}} +$ kubectl apply -f - <}} + +{{< /tab >}} + +{{< /tabset >}} + +2) Display the defined routes with the following command: + +{{< tabset category-name="config-api" >}} + +{{< tab name="Istio classic" category-value="istio-classic" >}} + +{{< text bash yaml >}} +$ kubectl get virtualservices -o yaml +- apiVersion: networking.istio.io/v1beta1 + kind: VirtualService + ... + spec: + hosts: + - details + http: + - route: + - destination: + host: details + subset: v1 +- apiVersion: networking.istio.io/v1beta1 + kind: VirtualService + ... + spec: + hosts: + - productpage + http: + - route: + - destination: + host: productpage + subset: v1 +- apiVersion: networking.istio.io/v1beta1 + kind: VirtualService + ... + spec: + hosts: + - ratings + http: + - route: + - destination: + host: ratings + subset: v1 +- apiVersion: networking.istio.io/v1beta1 + kind: VirtualService + ... + spec: + hosts: + - reviews + http: + - route: + - destination: + host: reviews + subset: v1 +{{< /text >}} + +You can also display the corresponding `subset` definitions with the following command: + +{{< text bash >}} +$ kubectl get destinationrules -o yaml +{{< /text >}} + +{{< /tab >}} + +{{< tab name="Gateway API" category-value="gateway-api" >}} + +{{< text bash >}} +$ kubectl get httproute reviews -o yaml +... +spec: + parentRefs: + - group: gateway.networking.k8s.io + kind: Service + name: reviews + port: 9080 + rules: + - backendRefs: + - group: "" + kind: Service + name: reviews-v1 + port: 9080 + weight: 1 + matches: + - path: + type: PathPrefix + value: / +status: + parents: + - conditions: + - lastTransitionTime: "2022-11-08T19:56:19Z" + message: Route was valid + observedGeneration: 8 + reason: Accepted + status: "True" + type: Accepted + - lastTransitionTime: "2022-11-08T19:56:19Z" + message: All references resolved + observedGeneration: 8 + reason: ResolvedRefs + status: "True" + type: ResolvedRefs + controllerName: istio.io/gateway-controller + parentRef: + group: gateway.networking.k8s.io + kind: Service + name: reviews + port: 9080 +{{< /text >}} + +In the resource status, make sure that the `Accepted` condition is `True` for the `reviews` parent. + +{{< /tab >}} + +{{< /tabset >}} You have configured Istio to route to the `v1` version of the Bookinfo microservices, most importantly the `reviews` service version 1. @@ -113,15 +207,11 @@ most importantly the `reviews` service version 1. ## Test the new routing configuration You can easily test the new configuration by once again refreshing the `/productpage` -of the Bookinfo app. - -1. Open the Bookinfo site in your browser. The URL is `http://$GATEWAY_URL/productpage`, where `$GATEWAY_URL` is the External IP address of the ingress, as explained in -the [Bookinfo](/docs/examples/bookinfo/#determine-the-ingress-ip-and-port) doc. - - Notice that the reviews part of the page displays with no rating stars, no - matter how many times you refresh. This is because you configured Istio to route - all traffic for the reviews service to the version `reviews:v1` and this - version of the service does not access the star ratings service. +of the Bookinfo app in your browser. +Notice that the reviews part of the page displays with no rating stars, no +matter how many times you refresh. This is because you configured Istio to route +all traffic for the reviews service to the version `reviews:v1` and this +version of the service does not access the star ratings service. You have successfully accomplished the first part of this task: route traffic to one version of a service. @@ -143,41 +233,78 @@ Remember, `reviews:v2` is the version that includes the star ratings feature. 1. Run the following command to enable user-based routing: - {{< text bash >}} - $ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-test-v2.yaml@ - {{< /text >}} +{{< tabset category-name="config-api" >}} -1. Confirm the rule is created: +{{< tab name="Istio classic" category-value="istio-classic" >}} - {{< text bash yaml >}} - $ kubectl get virtualservice reviews -o yaml - apiVersion: networking.istio.io/v1beta1 - kind: VirtualService - ... - spec: - hosts: - - reviews - http: - - match: - - headers: - end-user: - exact: jason - route: - - destination: - host: reviews - subset: v2 - - route: - - destination: - host: reviews - subset: v1 - {{< /text >}} +{{< text bash >}} +$ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-test-v2.yaml@ +{{< /text >}} -1. On the `/productpage` of the Bookinfo app, log in as user `jason`. +You can confirm the rule is created using the following command: + +{{< text bash yaml >}} +$ kubectl get virtualservice reviews -o yaml +apiVersion: networking.istio.io/v1beta1 +kind: VirtualService +... +spec: + hosts: + - reviews + http: + - match: + - headers: + end-user: + exact: jason + route: + - destination: + host: reviews + subset: v2 + - route: + - destination: + host: reviews + subset: v1 +{{< /text >}} + +{{< /tab >}} + +{{< tab name="Gateway API" category-value="gateway-api" >}} + +{{< text bash >}} +$ kubectl apply -f - <}} + +{{< /tab >}} + +{{< /tabset >}} + +2) On the `/productpage` of the Bookinfo app, log in as user `jason`. Refresh the browser. What do you see? The star ratings appear next to each review. -1. Log in as another user (pick any name you wish). +3) Log in as another user (pick any name you wish). Refresh the browser. Now the stars are gone. This is because traffic is routed to `reviews:v1` for all users except Jason. @@ -201,12 +328,28 @@ gradually send traffic from one version of a service to another. ## Cleanup -1. Remove the application virtual services: +1. Remove the application route rules: - {{< text bash >}} - $ kubectl delete -f @samples/bookinfo/networking/virtual-service-all-v1.yaml@ - {{< /text >}} +{{< tabset category-name="config-api" >}} -1. If you are not planning to explore any follow-on tasks, refer to the +{{< tab name="Istio classic" category-value="istio-classic" >}} + +{{< text bash >}} +$ kubectl delete -f @samples/bookinfo/networking/virtual-service-all-v1.yaml@ +{{< /text >}} + +{{< /tab >}} + +{{< tab name="Gateway API" category-value="gateway-api" >}} + +{{< text bash >}} +$ kubectl delete httproute reviews +{{< /text >}} + +{{< /tab >}} + +{{< /tabset >}} + +2) If you are not planning to explore any follow-on tasks, refer to the [Bookinfo cleanup](/docs/examples/bookinfo/#cleanup) instructions to shutdown the application. diff --git a/content/en/docs/tasks/traffic-management/request-routing/snips.sh b/content/en/docs/tasks/traffic-management/request-routing/snips.sh index c0d9ce8bd1..0b2b653c19 100644 --- a/content/en/docs/tasks/traffic-management/request-routing/snips.sh +++ b/content/en/docs/tasks/traffic-management/request-routing/snips.sh @@ -19,16 +19,35 @@ # WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL MARKDOWN FILE: # docs/tasks/traffic-management/request-routing/index.md #################################################################################################### +source "content/en/boilerplates/snips/gateway-api-gamma-support.sh" -snip_apply_a_virtual_service_1() { +snip_route_to_version_1_1() { kubectl apply -f samples/bookinfo/networking/virtual-service-all-v1.yaml } -snip_apply_a_virtual_service_2() { +snip_route_to_version_1_2() { +kubectl apply -f - <