Chapter 2. Getting traffic into a mesh

Procedure

1. Create namespace called httpbin by running the following command:

   $ oc create namespace httpbin

2. Enable sidecar injection in the namespace. If you are using the InPlace upgrade strategy, run the following command:

   $ oc label namespace httpbin istio-injection=enabled

   Note

   If you are using the RevisionBased upgrade strategy, run the following commands:

   1. To find your <revision-name>, run the following command:

      $ oc get istiorevisions.sailoperator.io

      You should see output similar to the following example:

      NAME      TYPE    READY   STATUS    IN USE   VERSION   AGE
      default   Local   True    Healthy   True    v1.24.3   3m33s

   2. Label the namespace with the revision name to enable sidecar injection:

      $ oc label namespace httpbin istio.io/rev=default

3. Deploy a sample service named httpbin by running the following command:

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

4. 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.

   You can see the following example configuration for reference:

   apiVersion: networking.istio.io/v1
   kind: Gateway
   metadata:
     name: httpbin-gateway
     namespace: httpbin
   spec:
     selector:
       istio: <gateway_name>
     servers:
     - port:
         number: 80
         name: http
         protocol: HTTP
       hosts:
       - httpbin.example.com

   • spec.selector specifies the unique label or set of labels in the pod template of the gateway proxy Deployment. By default, the Istio Gateway resource configuration will apply to matching gateway pods in all namespaces.
   • spec.servers.hosts specifies a list of addresses that the clients use when attempting to access a mesh service at the associated port.

5. Apply the YAML file by running the following command:

   $ oc apply -f httpbin-gw.yaml

6. 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.

   You can see the following example configuration for reference:

   apiVersion: networking.istio.io/v1
   kind: VirtualService
   metadata:
     name: httpbin
     namespace: httpbin
   spec:
     hosts:
     - httpbin.example.com
     gateways:
     - httpbin-gateway
     http:
     - match:
       - uri:
           prefix: /status
       - uri:
           prefix: /headers
       route:
       - destination:
           port:
             number: 8000
           host: httpbin

   • spec.hosts the destination hosts for the VirtualService routing rules. The Istio Gateway resource must expose the hosts that you bind to the VirtualService.
   • spec.gateways binds the VirtualService to the Istio Gateway resource created in the previous step by adding the Gateway name to the list of gateways.
   • spec.http.route route matching traffic to the httpbin service deployed earlier by defining a destination that includes the host and port of the httpbin Service.

7. Apply the YAML file by running the following command:

   $ oc apply -f httpbin-vs.yaml

8. For verification purposes, create a namespace for a curl client by running the following command:

   $ oc create namespace curl

9. Deploy the curl client by running the following command:

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

10. Set a CURL_POD variable with the name of the curl pod by running the following command:

    $ CURL_POD=$(oc get pods -n curl -l app=curl -o jsonpath='{.items[*].metadata.name}')

11. 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 Istio Gateway and VirtualService resources specify. Run the following curl command to send the request:

    $ oc exec $CURL_POD -n curl -- \
      curl -s -I \
        -H Host:httpbin.example.com \
        <gateway_name>.<gateway_namespace>.svc.cluster.local/headers

12. The response should have a 200 OK HTTP status indicating that the request was successful.

    Example output

    HTTP/1.1 200 OK
    server: istio-envoy
    ...

13. Send a curl request to an endpoint that does not have a corresponding URI prefix match defined in the httpbin VirtualService by running the following command:

    $ oc exec $CURL_POD -n curl -- \
      curl -s -I \
        -H Host:httpbin.example.com \
        <gateway_name>.<gateway_namespace>.svc.cluster.local/get

    The response should return a 404 Not Found status as the httpbin VirtualService resource lacks a matching URI prefix for the /get endpoint.

    Example output

    HTTP/1.1 404 Not Found
    server: istio-envoy
    ...

14. Expose the gateway proxy to traffic outside the cluster by setting the Service type to LoadBalancer:

    $ oc patch service <gateway_name> -n <gateway_namespace> -p '{"spec": {"type": "LoadBalancer"}}'

    Note

    OpenShift Routes can also expose a gateway to traffic outside the cluster. For more information, see "Exposing a gateway to traffic outside the cluster using OpenShift Routes".

15. Verify that you can access the httpbin service 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 that your cluster is running in.

    1. If the cluster runs on AWS, set the INGRESS_HOST variable by running the following command:

       $ INGRESS_HOST=$(oc get service <gateway_name> -n <gateway_namespace> -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')

    2. If the cluster runs on GCP or Azure, set the INGRESS_HOST variable by running the following command:

       $ INGRESS_HOST=$(oc get service <gateway_name> -n <gateway_namespace> -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

    3. Send a curl request to the httpbin service using the host of the gateway by running the following command:

       $ curl -s -I -H Host:httpbin.example.com http://$INGRESS_HOST/headers

16. Verify that the response has the HTTP/1.1 200 OK status, which indicates that the request was successful.

Procedure

1. Create a namespace called httpbin by running the following command:

   $ oc create namespace httpbin

2. Deploy a sample service named httpbin by running the following command:

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

3. Create a YAML file named httpbin-gw.yaml that defines a Kubernetes Gateway resource. This resource configures gateway proxies to expose port 80 (HTTP) for the host, httpbin.example.com.

   Example gateway resource file:

   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

   • spec.listeners.hostname: "httpbin.example.com" specifies the virtual hostname that clients use when attempting to access a mesh service on the associated port.

4. Apply the YAML file by running the following command:

   $ oc apply -f httpbin-gw.yaml

5. 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.

   Example HTTPRoute file:

   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: httpbin
     namespace: httpbin
   spec:
     parentRefs:
     - name: httpbin-gateway
       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 Kubernetes Gateway resource you created in the previous 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.

6. Apply the YAML file by running the following command:

   $ oc apply -f httpbin-hr.yaml

7. Ensure that the Gateway API service is ready and has an allocated address by running the following command:

   $ oc wait --for=condition=programmed gtw httpbin-gateway -n httpbin

Verification

1. Create a namespace for a curl client by running the following command:

   $ oc create namespace curl

2. Deploy a curl client by running the following command:

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

3. Set a CURL_POD variable with the name of the curl pod by running the following command:

   $ CURL_POD=$(oc get pods -n curl -l app=curl -o jsonpath='{.items[*].metadata.name}')

4. 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 Kubernetes Gateway and HTTPROUTE resources specify. Send the curl request by running the following command:

   $ oc exec $CURL_POD -n curl -- \
     curl -s -I \
       -H Host:httpbin.example.com \
       <gateway_name>-istio.<gateway_namespace>.svc.cluster.local/headers

   The response should return a 200 OK HTTP status, which indicates that the request was successful.

   Example output:

   HTTP/1.1 200 OK
   server: istio-envoy
   ...

5. 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:

   $ oc exec $CURL_POD -n curl -- \
     curl -s -I \
       -H Host:httpbin.example.com \
       <gateway_name>-istio.<gateway_namespace>.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:

   HTTP/1.1 404 Not Found
   server: istio-envoy
   ...

6. Expose the gateway proxy to traffic outside the cluster by setting the Service type to LoadBalancer. Run the following command:

   $ oc patch service <gateway_name>-istio -n <gateway_namespace> -p '{"spec": {"type": "LoadBalancer"}}'

   Note

   OpenShift Routes can also expose a gateway to traffic outside the cluster. For more information, see "Exposing a gateway to traffic outside the cluster using OpenShift Routes".

7. Verify that you can access the httpbin service 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.

   1. Set the INGRESS_HOST variable by running the following command:

      $ export INGRESS_HOST=$(oc get gtw <gateway_name> -n <gateway_namespace> -o jsonpath='{.status.addresses[0].value}')

   2. Set the INGRESS_PORT variable by running the following command:

      $ INGRESS_PORT=$(oc get gtw <gateway_name> -n <gateway_namespace> -o jsonpath='{.spec.listeners[?(@.name=="http")].port}')

   3. Using the gateway host, send a curl request to the httpbin service by running the following command:

      $ curl -s -I -H Host:httpbin.example.com http://$INGRESS_HOST:$INGRESS_PORT/headers

8. Verify that the response has the HTTP/1.1 200 OK status, which indicates that the request was successful.