tutorials for exposing workloads with gateway API (#931)

* tutorial for exposing httpbin with gateway API * tutorial for exposing tcpecho with gateway API * Apply suggestions from code review Co-authored-by: Natalia Sitko <[email protected]> Co-authored-by: Tim Riffer <[email protected]> * review fix * review fix --------- Co-authored-by: Natalia Sitko <[email protected]> Co-authored-by: Tim Riffer <[email protected]>
kyma-project · Aug 2, 2024 · 604184d · 604184d
1 parent eef35bd
commit 604184d
Show file tree

Hide file tree

Showing 3 changed files with 235 additions and 0 deletions.
diff --git a/docs/user/_sidebar.md b/docs/user/_sidebar.md
@@ -13,6 +13,8 @@
 * [Tutorials](/istio/user/tutorials/README.md)
   * [Forward Client IP](/istio/user/tutorials/01-00-x-forwarded-for-header.md)
   * [Use External Authorization Provider](/istio/user/tutorials/01-10-external-authorization-provider.md)
+  * [Use Gateway API to Expose HTTPBin](/istio/user/tutorials/01-20-expose-httbin-gateway-api.md)
+  * [Use Gateway API to Expose TCP Service](/istio/user/tutorials/01-30-expose-tcp-gateway-api.md)
 * [Technical Reference](/istio/user/technical-reference/README.md)
   * [Istio Controller Parameters](/istio/user/technical-reference/05-00-istio-controller-parameters.md)
   * [Istio Controller RBAC Configuration](/istio/user/technical-reference/05-10-istio-controller-rbac.md)

diff --git a/docs/user/tutorials/01-20-expose-httbin-gateway-api.md b/docs/user/tutorials/01-20-expose-httbin-gateway-api.md
@@ -0,0 +1,109 @@
+# Use Gateway API to Expose HTTPBin
+
+This tutorial shows how to expose an HTTPBin Service using Gateway API.
+
+> [!WARNING]
+> Exposing a workload to the outside world is a potential security vulnerability, so tread carefully. This example is not meant to be used in the production environment. 
+
+## Prerequisites
+
+* Kyma installation with the Istio module added. 
+
+## Steps
+
+### Install Gateway API CustomResourceDefinitions
+
+The Istio module does not install Gateway API CustomResourceDefinitions (CRDs). To install the CRDs from the standard channel, run the following command:
+
+    ```bash
+    kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \
+    { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v1.1.0" | kubectl apply -f -; }
+    ```
+> [!NOTE]
+> If you've already installed Gateway API CRDs from the experimental channel, you must delete them before installing Gateway API CRDs from the standard channel.
+
+### Create a Workload
+
+1. Export the name of the namespace in which you want to deploy the HTTPBin Service:
+
+    ```bash
+    export NAMESPACE={NAMESPACE_NAME}
+    ```
+
+2. Create a namespace with Istio injection enabled and deploy the HTTPBin Service:
+
+    ```bash
+    kubectl create ns $NAMESPACE
+    kubectl label namespace $NAMESPACE istio-injection=enabled --overwrite
+    kubectl create -n $NAMESPACE -f https://raw.githubusercontent.com/istio/istio/master/samples/httpbin/httpbin.yaml
+    ```
+
+### Expose an HTTPBin Service
+
+1. Create a Kubernetes Gateway to deploy Istio Ingress Gateway.
+
+    ```bash
+    cat <<EOF | kubectl apply -f -
+    apiVersion: gateway.networking.k8s.io/v1
+    kind: Gateway
+    metadata:
+      name: httpbin-gateway
+      namespace: ${NAMESPACE}
+    spec:
+      gatewayClassName: istio
+      listeners:
+      - name: http
+        hostname: "httpbin.kyma.example.com"
+        port: 80
+        protocol: HTTP
+        allowedRoutes:
+          namespaces:
+            from: Same
+    EOF
+    ```
+
+> [!NOTE]
+> This command deploys the Istio Ingress service in your namespace with the corresponding Kubernetes Service of type `LoadBalanced` and an assigned external IP address.
+
+2. Create an HTTPRoute to configure access to your workload:
+
+    ```bash
+    cat <<EOF | kubectl apply -f -
+    apiVersion: gateway.networking.k8s.io/v1
+    kind: HTTPRoute
+    metadata:
+      name: httpbin
+      namespace: ${NAMESPACE}
+    spec:
+      parentRefs:
+      - name: httpbin-gateway
+      hostnames: ["httpbin.kyma.example.com"]
+      rules:
+      - matches:
+        - path:
+            type: PathPrefix
+            value: /headers
+        backendRefs:
+        - name: httpbin
+          namespace: ${NAMESPACE}
+          port: 8000
+    EOF
+    ```
+
+### Access an HTTPBin Service
+
+1. Discover Istio Ingress Gateway's IP and port:
+
+    ```bash
+    export INGRESS_HOST=$(kubectl get gtw httpbin-gateway -n $NAMESPACE -o jsonpath='{.status.addresses[0].value}')
+    export INGRESS_PORT=$(kubectl get gtw httpbin-gateway -n $NAMESPACE -o jsonpath='{.spec.listeners[?(@.name=="http")].port}')
+    ```
+
+2. Call an HTTPBin Service:
+
+    ```bash
+    curl -s -I -HHost:httpbin.kyma.example.com "http://$INGRESS_HOST:$INGRESS_PORT/headers"
+    ```
+> [!NOTE]
+> This tutorial assumes there's no DNS setup for the `httpbin.kyma.example.com` host, so the call contains the host header.
+
diff --git a/docs/user/tutorials/01-30-expose-tcp-gateway-api.md b/docs/user/tutorials/01-30-expose-tcp-gateway-api.md
@@ -0,0 +1,124 @@
+# Use Gateway API to Expose a TCP Service
+
+This tutorial shows how to expose a TCP Service using Gateway API.
+
+> [!WARNING]
+> This tutorial is based on the experimental version of the Istio module.
+> Exposing a workload to the outside world is a potential security vulnerability, so tread carefully. This example is not meant to be used in the production environment. 
+
+## Prerequisites
+
+* The Istio module installation in the experimental version
+
+## Steps
+
+### Configure Gateway API Alpha Support
+
+Edit the Istio custom resource by setting **enableAlphaGatewayAPI** to `true`:
+
+    ```bash
+    kubectl patch istios/default -n kyma-system --type merge -p '{"spec":{"experimental":{"pilot": {"enableAlphaGatewayAPI": true}}}}'
+    ```
+
+### Install the experimental version of Gateway API CustomResourceDefinitions
+
+The Istio module does not install Gateway API CustomResourceDefinitions (CRDs). To install the CRDs from the experimental channel, run the following command:
+
+    ```bash
+    kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \
+    { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd/experimental?ref=v1.1.0" | kubectl apply -f -; }
+    ```
+> [!NOTE]
+> If you've already installed Gateway API CRDs from the standard channel, you must delete them before installing Gateway API CRDs from the experimental channel.
+
+### Create a Workload
+
+1. Export the name of the namespace in which you want to deploy the TCPEcho Service:
+
+    ```bash
+    export NAMESPACE={NAMESPACE_NAME}
+    ```
+
+2. Create a namespace with Istio injection enabled and deploy the TCPEcho Service:
+
+    ```bash
+    kubectl create ns $NAMESPACE
+    kubectl label namespace $NAMESPACE istio-injection=enabled --overwrite
+    kubectl create -n $NAMESPACE -f https://raw.githubusercontent.com/istio/istio/release-1.22/samples/tcp-echo/tcp-echo.yaml
+    ```
+
+### Expose an TCPEcho Service
+
+1. Create a Kubernetes Gateway to deploy Istio Ingress Gateway:
+
+    ```bash
+    cat <<EOF | kubectl apply -f -
+    apiVersion: gateway.networking.k8s.io/v1
+    kind: Gateway
+    metadata:
+      name: tcp-echo-gateway
+      namespace: ${NAMESPACE}
+    spec:
+      gatewayClassName: istio
+      listeners:
+      - name: tcp-31400
+        port: 31400
+        protocol: TCP
+        allowedRoutes:
+          namespaces:
+            from: Same
+    EOF
+    ```
+
+> [!NOTE]
+> This command deploys the Istio Ingress service in your namespace with the corresponding Kubernetes Service of type `LoadBalanced` and an assigned external IP address.
+
+2. Create a TCPRoute to configure access to your worklad:
+
+    ```bash
+    cat <<EOF | kubectl apply -f -
+    apiVersion: gateway.networking.k8s.io/v1alpha2
+    kind: TCPRoute
+    metadata:
+      name: tcp-echo
+      namespace: ${NAMESPACE}
+    spec:
+      parentRefs:
+      - name: tcp-echo-gateway
+        sectionName: tcp-31400
+      rules:
+      - backendRefs:
+        - name: tcp-echo
+          port: 9000
+    EOF
+    ```
+
+### Send TCP Traffic to an TCPEcho Service
+
+1. Discover Istio Ingress Gateway's IP and port:
+
+    ```bash
+    export INGRESS_HOST=$(kubectl get gtw tcp-echo-gateway -n $NAMESPACE -o jsonpath='{.status.addresses[0].value}')
+    export INGRESS_PORT=$(kubectl get gtw tcp-echo-gateway -n $NAMESPACE -o jsonpath='{.spec.listeners[?(@.name=="tcp-31400")].port}')
+    ```
+
+2. Deploy a `sleep` Service:
+
+    ```bash
+    kubectl create -n $NAMESPACE -f https://raw.githubusercontent.com/istio/istio/release-1.22/samples/sleep/sleep.yaml
+    ```
+
+
+2. Send TCP traffic:
+
+    ```bash
+    export SLEEP=$(kubectl get pod -l app=sleep -n $NAMESPACE -o jsonpath={.items..metadata.name})
+    for i in {1..3}; do \
+    kubectl exec "$SLEEP" -c sleep -n $NAMESPACE -- sh -c "(date; sleep 1) | nc $INGRESS_HOST $INGRESS_PORT"; \
+    done
+    ```
+    You should see similar output:
+    ```
+    hello Mon Jul 29 12:43:56 UTC 2024
+    ```
+