Chapter 3. Directing outbound traffic through a gateway

Procedure

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

   $ oc create namespace curl

2. Depending on the update strategy you are using, enable sidecar injection in the namespace by running the appropriate commands:

   1. If you are using the InPlace update strategy, run the following command:

      $ oc label namespace curl istio-injection=enabled

   2. If you are using the RevisionBased update strategy, run the following commands:

      1. Display the revision name by running 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 by running the following command:

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

3. Deploy a curl application 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

4. Export a CURL_POD environment variable and initialize it with the name of the curl pod by running the following command:

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

5. Create a YAML file named http-se.yaml that directs traffic from the mesh to an external service. The following example defines a ServiceEntry for a URL:

   apiVersion: networking.istio.io/v1
   kind: ServiceEntry
   metadata:
     name: egress-se
     namespace: curl
   spec:
     hosts:
       - docs.redhat.com
     ports:
       - number: 80
         name: http-port
         protocol: HTTP
     location: MESH_EXTERNAL
     resolution: DNS

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

   $ oc apply -f http-se.yaml

7. Ensure that you applied the ServiceEntry configuration correctly. Send an HTTP request to the host that you specified in the previous step by running the following command:

   $ oc exec "$CURL_POD" -n curl -c curl -- curl -sSL -o /dev/null -D - http://docs.redhat.com

   This command should return HTTP status codes, such as 301 (redirect) or 200 (success), indicating that the connection works.

8. Create a YAML file named http-gtw.yaml that creates an egress Gateway and routes traffic from the mesh to the host specified for the external service, similar to the following example:

   apiVersion: networking.istio.io/v1alpha3
   kind: Gateway
   metadata:
     name: egress-gw
     namespace: <gateway_namespace> # Namespace where the egress gateway is deployed
   spec:
     selector:
       istio: <gateway_name> # Selects the egress-gateway instance to handle this traffic
     servers:
       - port:
           number: 80
           name: http
           protocol: HTTP
         hosts:
           - docs.redhat.com # External service host, not a full URL.
   ---
   apiVersion: networking.istio.io/v1alpha3
   kind: DestinationRule
   metadata:
     name: egress-dr
     namespace: <gateway_namespace> # Namespace where the egress gateway is deployed
   spec:
     host: <gateway_name>.<gateway_namespace>.svc.cluster.local
     subsets:
       - name: rh-docs

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

   $ oc apply -f http-gtw.yaml

10. Create a YAML file named http-vs.yaml that sets up a VirtualService to manage the flow of traffic from the application sidecars through the egress gateway to the external host, similar to the following example:

    apiVersion: networking.istio.io/v1alpha3
    kind: VirtualService
    metadata:
      name: egress-vs
      namespace: curl # Namespace where the curl pod is running
    spec:
      hosts:
        - docs.redhat.com # External service host, not a full URL.
      gateways:
        - mesh
        - <gateway_namespace>/egress-gw # Egress gateway name defined in the file that you used in the previous step.
      http:
        - match:
            - gateways:
                - mesh
              port: 80
          route:
            - destination:
                host: <gateway_name>.<gateway_namespace>.svc.cluster.local
                subset: rh-docs
                port:
                  number: 80
              weight: 100
        - match:
            - gateways:
                - <gateway_namespace>/egress-gw # Egress gateway name defined in the file that you used in the previous step.
              port: 80
          route:
            - destination:
                host: docs.redhat.com
                port:
                  number: 80
              weight: 100

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

    $ oc apply -f http-vs.yaml

12. Resend the HTTP request to the URL:

    $ oc exec "$CURL_POD" -n curl -c curl -- curl -sSL -o /dev/null -D - http://docs.redhat.com

    The terminal should display information similar to the following output:

    ...
    HTTP/1.1 301 Moved Permanently
    ...
    location: <example_url>
    ...
    
    HTTP/2 200
    Content-Type: text/html; charset=utf-8

13. Ensure that the gateway routed the request by running the following command:

    $ oc logs deployment/<gateway_name> -n <gateway_namespace> | tail -1

    Note

    You must enable access logging for this verification step to work. You can enable access logging to the standard output by setting the spec.values.meshConfig.accessLogFile field to /dev/stdout in the Istio resource.

    The terminal should display information similar to the following output:

    [2024-11-07T14:35:52.428Z] "GET / HTTP/2" 301 - via_upstream - "-" 0 0 24 24 "10.128.2.30" "curl/8.11.0" "79551af2-341b-456d-b414-9220b487a03b" "docs.redhat.com" "23.55.176.201:80" outbound|80||docs.redhat.com 10.128.2.29:49766 10.128.2.29:80 10.128.2.30:38296 -

Procedure

1. Optional: Enable the Kubernetes Gateway API custom resource definitions (CRDs).

   Note

   As of Kubernetes 1.28 and OpenShift Container Platform 4.18 or earlier version of Red Hat OpenShift Service Mesh, the Kubernetes Gateway API CRDs are not available by default and you must install the CRDs before you can use them. OpenShift Container Platform 4.19 and later versions install the CRDs by default.

   1. Create a YAML file named gateway-cr.yaml that enables the Kubernetes Gateway API CRDs, similar to the following example:

      apiVersion: gateway.networking.k8s.io/v1
      kind: Gateway
      metadata:
        name: bookinfo-gateway
      spec:
        gatewayClassName: istio
        listeners:
        - name: http
          port: 80
          protocol: HTTP
          allowedRoutes:
            namespaces:
              from: Same
      ---
      apiVersion: gateway.networking.k8s.io/v1
      kind: HTTPRoute
      metadata:
        name: bookinfo
      spec:
        parentRefs:
        - name: bookinfo-gateway
        rules:
        - matches:
          - path:
              type: Exact
              value: /productpage
          - path:
              type: PathPrefix
              value: /static
          - path:
              type: Exact
              value: /login
          - path:
              type: Exact
              value: /logout
          - path:
              type: PathPrefix
              value: /api/v1/products
          backendRefs:
          - name: productpage
            port: 9080

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

      $ oc apply -f gateway-cr.yaml

2. Create a namespace called egress-gateway by running the following command:

   $ oc create namespace egress-gateway

3. Apply the istio-injection label to the namespace by running the following command:

   $ oc label namespace egress-gateway istio-injection=enabled

4. Create a YAML file named egress-gateway-cr.yaml that defines the egress gateway, similar to the following example:

   # ServiceEntry to allow traffic to httpbin.org
   apiVersion: networking.istio.io/v1
   kind: ServiceEntry
   metadata:
     name: httpbin-ext
   spec:
     hosts:
     - httpbin.org
     ports:
     - number: 80
       name: http
       protocol: HTTP
     location: MESH_EXTERNAL
     resolution: DNS
   ---
   # Gateway API Gateway for egress
   apiVersion: gateway.networking.k8s.io/v1
   kind: Gateway
   metadata:
     name: httpbin-egress-gateway
     annotations:
       networking.istio.io/service-type: ClusterIP
   spec:
     gatewayClassName: istio
     listeners:
     - name: http
       hostname: httpbin.org
       port: 80
       protocol: HTTP
       allowedRoutes:
         namespaces:
           from: Same
   ---
   # HTTPRoute to direct traffic from sidecars to the egress gateway
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: direct-httpbin-to-egress-gateway
   spec:
     parentRefs:
     - kind: ServiceEntry
       group: networking.istio.io
       name: httpbin-ext
     rules:
     - backendRefs:
       - name: httpbin-egress-gateway-istio
         port: 80
   ---
   # HTTPRoute to forward traffic from the egress gateway to httpbin.org
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: forward-httpbin-from-egress-gateway
   spec:
     parentRefs:
     - name: httpbin-egress-gateway
     hostnames:
     - httpbin.org
     rules:
     - backendRefs:
       - kind: Hostname
         group: networking.istio.io
         name: httpbin.org
         port: 80

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

      $ oc apply -f egress-gateway-cr.yaml

Verification

1. Verify the status of the gateway configuration by running the following command:

   $ oc describe gateway -n egress-gateway

   The Status column displays Programmed to indicate the required output.

2. Create a curl pod in the egress-gateway namespace by running the following command:

   $ oc run test-pod --image=curlimages/curl:latest -n egress-gateway --rm -it --restart=Never -- sh

3. By using the curl client, verify that you can access httpbin.org through the egress gateway by entering following command:

   $ curl -v http://httpbin.org/get

   The required output shows a response from httpbin.org that indicates egress traffic routes through the configured gateway.

Procedure

1. Optional: Enable the {k8} Gateway API custom resource definitions (CRDs).

   Note

   As of Kubernetes 1.28 and OpenShift Container Platform 4.18 or earlier version of Red Hat OpenShift Service Mesh, the Kubernetes Gateway API CRDs are not available by default and you must install the CRDs before you can use them. OpenShift Container Platform 4.19 and later versions install the CRDs by default.

2. Create a namespace called egress-gateway by running the following command:

   $ oc create namespace egress-gateway

3. Apply the ambient mode label to the namespace by running the following command:

   $ oc label namespace egress-gateway istio.io/dataplane-mode=ambient

4. Create a YAML file named egress-se.yaml that defines the ServiceEntry, similar to the following example:

   apiVersion: networking.istio.io/v1
   kind: ServiceEntry
   metadata:
     name: httpbin-ext
     namespace: egress-gateway
     labels:
       istio.io/use-waypoint: waypoint
   spec:
     hosts:
     - httpbin.org
     ports:
     - number: 80
       name: http
       protocol: HTTP
     resolution: DNS

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

      $ oc apply -f egress-se.yaml

   2. Create a YAML file named waypoint.yaml that creates a waypoint proxy in egress-gateway namespace similar to the following example:

      apiVersion: gateway.networking.k8s.io/v1
      kind: Gateway
      metadata:
        name: waypoint
        namespace: egress-gateway
        labels:
          istio.io/gateway-for: service
      spec:
        gatewayClassName: istio-waypoint
        listeners:
        - name: mesh
          port: 15008
          protocol: HBONE

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

      $ oc apply -f waypoint.yaml

      Note

      As an alternate to creating the waypoint.yaml YAML file, you can also set up waypoint proxy by running the following command:

      $ istioctl waypoint apply --enroll-namespace --name waypoint --namespace egress-gateway

      When you use the --enroll-namespace option, all services in the egress-gateway namespace (including ServiceEntries), will route their traffic through the waypoint.

Verification

1. Verify the status of the gateway configuration by running the following command:

   $ oc get gateways.gateway.networking.k8s.io waypoint -n egress-gateway

   The PROGRAMMED column shows True when the configuration succeeds, similar to the following example:

   NAME       CLASS            ADDRESS          PROGRAMMED   AGE
   waypoint   istio-waypoint   172.30.227.148   True         9s

2. Create a curl pod in the egress-gateway namespace by running the following command:

   $ oc run test-pod --image=curlimages/curl:latest -n egress-gateway --rm -it --restart=Never -- sh

3. By using the curl client, verify that you can access httpbin.org through the egress gateway by running the following command:

   $ curl -v http://httpbin.org/get

   The output shows a response from httpbin.org service that indicates egress traffic routes through the configured gateway. The ztunnel logs should show traffic routed through the waypoint. The terminal should display information similar to the following output:

   2025-10-24T08:08:35.242159Z info access connection complete src.addr=[fd01:0:0:5::b0]:56288 src.workload="test-pod" src.namespace="egress-gateway" src.identity="spiffe://cluster.local/ns/egress-gateway/sa/default" dst.addr=[fd01:0:0:5::af]:15008 dst.hbone_addr=[2001:2::2]:80 dst.service="httpbin.org" dst.workload="waypoint-5b668759d5-vrnx8" dst.namespace="egress-gateway" dst.identity="spiffe://cluster.local/ns/egress-gateway/sa/waypoint" direction="outbound" bytes_sent=78 bytes_recv=540 duration="957ms"