Gateway API doc improvements (#11737)

* Gateway API doc improvements

* add header

* grammar tweak

* fix lint

* one more

content/en/docs/tasks/traffic-management/ingress/gateway-api/index.md

@@ -14,17 +14,19 @@ This task describes how to configure Istio to expose a service outside the servi
 These APIs are an actively developed evolution of the Kubernetes [Service](https://kubernetes.io/docs/concepts/services-networking/service/)
 and [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) APIs.
 
-{{< warning >}}
-This feature is currently considered [alpha](/docs/releases/feature-stages/).
-Both the API (owned by Kubernetes SIG-NETWORK) and the Istio implementation are likely to change before being promoted further.
-{{< /warning >}}
-
 ## Setup
 
 1. The Gateway APIs do not come installed by default on most Kubernetes clusters. Install the Gateway API CRDs if they are not present:
 
     {{< text bash >}}
-    $ kubectl get crd gateways.gateway.networking.k8s.io || { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v0.4.0" | kubectl apply -f -; }
+    $ kubectl get crd gateways.gateway.networking.k8s.io || \
+      { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v0.5.0" | kubectl apply -f -; }
+    {{< /text >}}
+
+1. Install Istio using the `minimal` profile:
+
+    {{< text bash >}}
+    $ istioctl install --set profile=minimal -y
     {{< /text >}}
 
 ## Differences from Istio APIs
@@ -51,13 +53,13 @@ See the [Gateway API](https://gateway-api.sigs.k8s.io/) documentation for inform
 
 In this example, we will deploy a simple application and expose it externally using a `Gateway`.
 
-1. First, deploy a test application:
+1. First, deploy the `httpbin` test application:
 
     {{< text bash >}}
     $ kubectl apply -f @samples/httpbin/httpbin.yaml@
     {{< /text >}}
 
-1. Deploy the Gateway API configuration:
+1. Deploy the Gateway API configuration including a single exposed route (i.e., `/get`):
 
     {{< text bash >}}
     $ kubectl create namespace istio-ingress
@@ -93,26 +95,20 @@ In this example, we will deploy a simple application and expose it externally us
         - path:
             type: PathPrefix
             value: /get
-        filters:
-        - type: RequestHeaderModifier
-          requestHeaderModifier:
-            add:
-            - name: my-added-header
-              value: added-value
         backendRefs:
         - name: httpbin
           port: 8000
     EOF
     {{< /text >}}
 
-1.  Set the Ingress Host
+1.  Set the Ingress Host environment variable:
 
     {{< text bash >}}
     $ kubectl wait -n istio-ingress --for=condition=ready gateways.gateway.networking.k8s.io gateway
     $ export INGRESS_HOST=$(kubectl get gateways.gateway.networking.k8s.io gateway -n istio-ingress -ojsonpath='{.status.addresses[*].value}')
     {{< /text >}}
 
-1.  Access the _httpbin_ service using _curl_:
+1.  Access the `httpbin` service using _curl_:
 
     {{< text bash >}}
     $ curl -s -I -HHost:httpbin.example.com "http://$INGRESS_HOST/get"
@@ -133,6 +129,69 @@ In this example, we will deploy a simple application and expose it externally us
     ...
     {{< /text >}}
 
+1.  Update the route rule to also expose `/headers` and to add a header to the request:
+
+    {{< text bash >}}
+    $ kubectl apply -f - <<EOF
+    apiVersion: gateway.networking.k8s.io/v1alpha2
+    kind: HTTPRoute
+    metadata:
+      name: http
+      namespace: default
+    spec:
+      parentRefs:
+      - name: gateway
+        namespace: istio-ingress
+      hostnames: ["httpbin.example.com"]
+      rules:
+      - matches:
+        - path:
+            type: PathPrefix
+            value: /get
+        - path:
+            type: PathPrefix
+            value: /headers
+        filters:
+        - type: RequestHeaderModifier
+          requestHeaderModifier:
+            add:
+            - name: my-added-header
+              value: added-value
+        backendRefs:
+        - name: httpbin
+          port: 8000
+    EOF
+    {{< /text >}}
+
+1.  Access `/headers` again and notice header `My-Added-Header` has been added to the request:
+
+    {{< text bash >}}
+    $ curl -s -HHost:httpbin.example.com "http://$INGRESS_HOST/headers"
+    {
+      "headers": {
+        "Accept": "*/*",
+        "Host": "httpbin.example.com",
+        "My-Added-Header": "added-value",
+    ...
+    {{< /text >}}
+
+## Cleanup
+
+1. Uninstall Istio and the `httpbin` sample:
+
+    {{< text bash >}}
+    $ kubectl delete -f @samples/httpbin/httpbin.yaml@
+    $ istioctl uninstall -y --purge
+    $ kubectl delete ns istio-system
+    $ kubectl delete ns istio-ingress
+    {{< /text >}}
+
+1. Remove the Gateway API CRDs if they are no longer needed:
+
+    {{< text bash >}}
+    $ kubectl kustomize "github.com/kubernetes-sigs/service-apis/config/crd?ref=v0.5.0" | kubectl delete -f -
+    {{< /text >}}
+
 ## Deployment methods
 
 In the example above, you did not need to install an ingress gateway `Deployment` prior to configuring a Gateway.
@@ -194,6 +253,10 @@ spec:
 
 ## Mesh Traffic
 
+{{< warning >}}
+This feature is under development and pending [upstream agreement](https://gateway-api.sigs.k8s.io/contributing/gamma/).
+{{< /warning >}}
+
 The Gateway API can also be used to configure mesh traffic.
 This is done by configuring the `parentRef`, to point to the `istio` `Mesh`.
 This resource does not actually exist in the cluster and is only used to signal that the Istio mesh should be used.

content/en/docs/tasks/traffic-management/ingress/gateway-api/snips.sh

@@ -21,7 +21,12 @@
 ####################################################################################################
 
 snip_setup_1() {
-kubectl get crd gateways.gateway.networking.k8s.io || { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v0.4.0" | kubectl apply -f -; }
+kubectl get crd gateways.gateway.networking.k8s.io || \
+  { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v0.5.0" | kubectl apply -f -; }
+}
+
+snip_setup_2() {
+istioctl install --set profile=minimal -y
 }
 
 snip_configuring_a_gateway_1() {
@@ -62,12 +67,6 @@ spec:
     - path:
         type: PathPrefix
         value: /get
-    filters:
-    - type: RequestHeaderModifier
-      requestHeaderModifier:
-        add:
-        - name: my-added-header
-          value: added-value
     backendRefs:
     - name: httpbin
       port: 8000
@@ -98,6 +97,62 @@ HTTP/1.1 404 Not Found
 ...
 ENDSNIP
 
+snip_configuring_a_gateway_6() {
+kubectl apply -f - <<EOF
+apiVersion: gateway.networking.k8s.io/v1alpha2
+kind: HTTPRoute
+metadata:
+  name: http
+  namespace: default
+spec:
+  parentRefs:
+  - name: gateway
+    namespace: istio-ingress
+  hostnames: ["httpbin.example.com"]
+  rules:
+  - matches:
+    - path:
+        type: PathPrefix
+        value: /get
+    - path:
+        type: PathPrefix
+        value: /headers
+    filters:
+    - type: RequestHeaderModifier
+      requestHeaderModifier:
+        add:
+        - name: my-added-header
+          value: added-value
+    backendRefs:
+    - name: httpbin
+      port: 8000
+EOF
+}
+
+snip_configuring_a_gateway_7() {
+curl -s -HHost:httpbin.example.com "http://$INGRESS_HOST/headers"
+}
+
+! read -r -d '' snip_configuring_a_gateway_7_out <<\ENDSNIP
+{
+  "headers": {
+    "Accept": "*/*",
+    "Host": "httpbin.example.com",
+    "My-Added-Header": "added-value",
+...
+ENDSNIP
+
+snip_cleanup_1() {
+kubectl delete -f samples/httpbin/httpbin.yaml
+istioctl uninstall -y --purge
+kubectl delete ns istio-system
+kubectl delete ns istio-ingress
+}
+
+snip_cleanup_2() {
+kubectl kustomize "github.com/kubernetes-sigs/service-apis/config/crd?ref=v0.5.0" | kubectl delete -f -
+}
+
 ! read -r -d '' snip_automated_deployment_1 <<\ENDSNIP
 apiVersion: gateway.networking.k8s.io/v1alpha2
 kind: Gateway

content/en/docs/tasks/traffic-management/ingress/gateway-api/test.sh

@@ -27,7 +27,7 @@ source "tests/util/samples.sh"
 snip_setup_1
 
 # install Istio with PILOT_ENABLED_SERVICE_APIS flag enabled
-istioctl install --set profile=minimal -y
+snip_setup_2
 _wait_for_deployment istio-system istiod
 
 startup_httpbin_sample
@@ -41,13 +41,16 @@ snip_configuring_a_gateway_3
 # send CURL traffic to http://$INGRESS_HOST/get (expected 200)
 _verify_elided snip_configuring_a_gateway_4 "$snip_configuring_a_gateway_4_out"
 
-# send CURL traffic to http://$INGRESS_HOST/get (expected 404)
+# send CURL traffic to http://$INGRESS_HOST/headers (expected 404)
 _verify_elided snip_configuring_a_gateway_5 "$snip_configuring_a_gateway_5_out"
 
+# configure add a header to the request
+snip_configuring_a_gateway_6
+
+# send CURL traffic to http://$INGRESS_HOST/headers (expect added header)
+_verify_elided snip_configuring_a_gateway_7 "$snip_configuring_a_gateway_7_out"
 
 # @cleanup
 cleanup_httpbin_sample
-kubectl kustomize "github.com/kubernetes-sigs/service-apis/config/crd?ref=v0.4.0" | kubectl delete -f -
+snip_cleanup_1
-echo y | istioctl x uninstall --revision=default
+snip_cleanup_2
-kubectl delete ns istio-system
-kubectl delete ns istio-ingress