Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Gateways

Red Hat OpenShift Service Mesh 3.2

Gateways and OpenShift Service Mesh

Red Hat OpenShift Documentation Team

Abstract

This documentation provides information about using gateways with OpenShift Service Mesh.

Chapter 1. About gateways
Copy link

A gateway is a standalone Envoy proxy deployment and an associated Kubernetes service operating at the edge of a service mesh. You can configure a gateway to give fine-grained control over the traffic that enters or leaves the mesh. In Red Hat OpenShift Service Mesh, you can install gateways by using gateway injection or via the Gateway API.

Red Hat OpenShift Service Mesh supports different gateway configurations based on the deployment mode. You can deploy gateways by using gateway injection and configure them with Istio Gateway and VirtualService resources in sidecar mode or with Kubernetes Gateway API resources in both sidecar and ambient modes.

1.1. About gateway injection
Copy link

Gateway injection relies upon the same mechanism as sidecar injection to inject the Envoy proxy into gateway pods. To install a gateway using gateway injection, you create a Kubernetes Deployment object and an associated Kubernetes Service object in a namespace that is visible to the Istio control plane. When creating the Deployment object you label and annotate it so that the Istio control plane injects a proxy, and the proxy is configured as a gateway. After installing the gateway, you configure it to control ingress and egress traffic using the Istio Gateway and VirtualService resources.

This procedure explains how to install a gateway by using gateway injection.

Note

You can use this procedure to create ingress or egress gateways.

Prerequisites

  • You have installed the OpenShift Service Mesh Operator version 3.0 or later.
  • You have created an Istio control plane.
  • You have created an IstioCNI resource.

Procedure

  1. Create a namespace that you will use to install the gateway. 

    $ oc create namespace <gateway_namespace>
    Copy to Clipboard Toggle word wrap
    Note

    Install the gateway and the Istio control plane in different namespaces.

    You can install the gateway in a dedicated gateway namespace. This approach allows the gateway to be shared by many applications operating in different namespaces. Alternatively, you can install the gateway in an application namespace. In this approach, the gateway acts as a dedicated gateway for the application in that namespace.

  2. Create a YAML file named secret-reader.yml that defines the service account, role, and role binding for the gateway deployment. These settings enable the gateway to read the secrets, which is required for obtaining TLS credentials. 

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: secret-reader
  namespace: <gateway_namespace>
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: secret-reader
  namespace: <gateway_namespace>
rules:
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get", "watch", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name:  secret-reader
  namespace: <gateway_namespace>
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: secret-reader
subjects:
  - kind: ServiceAccount
    name:  secret-reader
    Copy to Clipboard Toggle word wrap

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

    $ oc apply -f secret-reader.yml
    Copy to Clipboard Toggle word wrap

  4. Create a YAML file named gateway-deployment.yml that defines the Kubernetes Deployment object for the gateway. 

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: <gateway_name>
  namespace: <gateway_namespace>
spec:
  selector:
    matchLabels:
      istio: <gateway_name>
  template:
    metadata:
      annotations:
        inject.istio.io/templates: gateway
    1 
    
      labels:
        istio: <gateway_name>
    2 
    
        sidecar.istio.io/inject: "true"
    3 
    
    spec:
      containers:
        - name: istio-proxy
          image: auto
    4 
    
          securityContext:
            capabilities:
              drop:
              - ALL
            allowPrivilegeEscalation: false
            privileged: false
            readOnlyRootFilesystem: true
            runAsNonRoot: true
          ports:
          - containerPort: 15090
            protocol: TCP
            name: http-envoy-prom
          resources:
            limits:
              cpu: 2000m
              memory: 1024Mi
            requests:
              cpu: 100m
              memory: 128Mi
      securityContext:
        sysctls:
        - name: net.ipv4.ip_unprivileged_port_start
          value: "0"
      serviceAccountName: secret-reader
    5
    Copy to Clipboard Toggle word wrap
    1
    Indicates that the Istio control plane uses the gateway injection template instead of the default sidecar template.
    2
    Ensure that a unique label is set for the gateway deployment. A unique label is required so that Istio Gateway resources can select gateway workloads.
    3
    Enables gateway injection by setting the sidecar.istio.io/inject label to true. If the name of the Istio resource is not default you must use the istio.io/rev: <istio_revision> label instead, where the revision represents the active revision of the Istio resource.
    4
    Sets the image field to auto so that the image automatically updates each time the pod starts.
    5
    Sets the serviceAccountName to the name of the ServiceAccount created previously.

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

    $ oc apply -f gateway-deployment.yml
    Copy to Clipboard Toggle word wrap

  6. Verify that the gateway Deployment rollout was successful by running the following command: 

    $ oc rollout status deployment/<gateway_name> -n <gateway_namespace>
    Copy to Clipboard Toggle word wrap

    You should see output similar to the following:

    Example output

    Waiting for deployment "<gateway_name>" rollout to finish: 0 of 1 updated replicas are available...
deployment "<gateway_name>" successfully rolled out
    Copy to Clipboard Toggle word wrap

  7. Create a YAML file named gateway-service.yml that contains the Kubernetes Service object for the gateway. 

    apiVersion: v1
kind: Service
metadata:
  name: <gateway_name>
  namespace: <gateway_namespace>
spec:
  type: ClusterIP
    1 
    
  selector:
    istio: <gateway_name>
    2 
    
  ports:
    - name: status-port
      port: 15021
      protocol: TCP
      targetPort: 15021
    - name: http2
      port: 80
      protocol: TCP
      targetPort: 80
    - name: https
      port: 443
      protocol: TCP
      targetPort: 443
    Copy to Clipboard Toggle word wrap
    1
    When you set spec.type to ClusterIP the gateway Service object can be accessed only from within the cluster. If the gateway has to handle ingress traffic from outside the cluster, set spec.type to LoadBalancer. Alternatively, you can use OpenShift Routes.
    2
    Set the selector to the unique label or set of labels specified in the pod template of the gateway deployment that you previously created.

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

    $ oc apply -f gateway-service.yml
    Copy to Clipboard Toggle word wrap

  9. Verify that the gateway service is targeting the endpoint of the gateway pods by running the following command: 

    $ oc get endpoints <gateway_name> -n <gateway_namespace>
    Copy to Clipboard Toggle word wrap

    You should see output similar to the following example:

    Example output

    NAME              ENDPOINTS                             AGE
<gateway_name>    10.131.0.181:8080,10.131.0.181:8443   1m
    Copy to Clipboard Toggle word wrap

  10. Optional: Create a YAML file named gateway-hpa.yml that defines a horizontal pod autoscaler for the gateway. The following example sets the minimum replicas to 2 and the maximum replicas to 5 and scales the replicas up when average CPU utilization exceeds 80% of the CPU resource limit. This limit is specified in the pod template of the deployment for the gateway. 

    apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: <gateway_name>
  namespace: <gateway_namespace>
spec:
  minReplicas: 2
  maxReplicas: 5
  metrics:
  - resource:
      name: cpu
      target:
        averageUtilization: 80
        type: Utilization
    type: Resource
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: <gateway_name>
    1
    Copy to Clipboard Toggle word wrap
    1
    Set spec.scaleTargetRef.name to the name of the gateway deployment previously created.

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

    $ oc apply -f gateway-hpa.yml
    Copy to Clipboard Toggle word wrap

  12. Optional: Create a YAML file named gateway-pdb.yml that defines a pod disruption budget for the gateway. The following example allows gateway pods to be evicted only when at least 1 healthy gateway pod will remain on the cluster after the eviction. 

    apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: <gateway_name>
  namespace: <gateway_namespace>
spec:
  minAvailable: 1
  selector:
    matchLabels:
      istio: <gateway_name>
    1
    Copy to Clipboard Toggle word wrap
    1
    Set the spec.selector.matchLabels to the unique label or set of labels specified in the pod template of the gateway deployment previously created.

  13. Optional: Apply the YAML file by running the following command: 

    $ oc apply -f gateway-pdb.yml
    Copy to Clipboard Toggle word wrap

Chapter 2. Getting traffic into a mesh
Copy link

Using Istio APIs, you can configure gateway proxies that were installed using gateway injection to accept traffic originating from outside the mesh, and route that traffic to the services within the mesh.

You can expose gateway proxies to traffic outside a cluster by using either a LoadBalancer type Service or OpenShift Routes.

2.1. About ingress traffic routing approaches
Copy link

Red Hat OpenShift Service Mesh offers two approaches to configure ingress traffic routing to services in the mesh. The approach depends on the service mesh deployment mode and traffic management requirements.

Ingress routing with gateway injection and Istio APIs
When you install a gateway by using gateway injection, you can configure it to receive ingress traffic by using the Istio Gateway and VirtualService resources in combination.

The gateway injection approach is compatible with sidecar-based service mesh deployments where you enable sidecar injection in namespaces by using the istio-injection=enabled label or the istio.io/rev=<revision> label.

Ingress routing with Kubernetes Gateway API
The Kubernetes Gateway API provides a standardized approach for configuring ingress traffic routing using native Kubernetes resources. With this approach, you use Gateway and HTTPRoute (or GRPCRoute) resources to configure how traffic enters the mesh and routes to services.

While Istio Gateway and VirtualService resources can be used for certain ingress use cases in ambient mode, the recommended approach is to use the Kubernetes Gateway API, which provides full support and integration with ambient. You can also use the Gateway API with sidecar-based deployments.

You can use the Istio Gateway and VirtualService resources to configure a gateway that was deployed by using gateway injection. The resources expose a service in the mesh to traffic outside the mesh. You can set the gateway Service type to LoadBalancer to allow traffic from outside the cluster.

Prerequisites

  • You have installed Istio gateways using gateway injection.
  • You are using the Istio Gateway and VirtualService resources.
  • You have existing VirtualService configurations and do not plan on migrating to ambient mode.

Procedure

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

    $ oc create namespace httpbin
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap
    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
      Copy to Clipboard Toggle word wrap

      You will get an output similar to the following example: 

    NAME      TYPE    READY   STATUS    IN USE   VERSION   AGE
default   Local   True    Healthy   True    v1.24.3   3m33s
    Copy to Clipboard Toggle word wrap

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

      $ oc label namespace httpbin istio.io/rev=default
      Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  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. 

    apiVersion: networking.istio.io/v1
kind: Gateway
metadata:
  name: httpbin-gateway
  namespace: httpbin
spec:
  selector:
    istio: <gateway_name>
    1 
    
  servers:
  - port:
      number: 80
      name: http
      protocol: HTTP
    hosts:
    - httpbin.example.com
    2
    Copy to Clipboard Toggle word wrap
    1
    Set the selector to the unique label or set of labels specified 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.
    2
    Using the hosts field, specify a list of addresses that can be used by clients 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
    Copy to Clipboard Toggle word wrap

  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. 

    apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: httpbin
  namespace: httpbin
spec:
  hosts:
  - httpbin.example.com
    1 
    
  gateways:
  - httpbin-gateway
    2 
    
  http:
  - match:
    - uri:
        prefix: /status
    - uri:
        prefix: /headers
    route:
    - destination:
    3 
    
        port:
          number: 8000
        host: httpbin
    Copy to Clipboard Toggle word wrap
    1
    Specify the hosts that the routing rules of the VirtualService will be applied to. The hosts specified must be exposed by the Istio Gateway resource the VirtualService is bound to.
    2
    Bind the VirtualService to the Istio Gateway resource created in the previous step by adding the Gateway name to the list of gateways.
    3
    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
    Copy to Clipboard Toggle word wrap

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

    $ oc create namespace curl
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  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}')
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

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

    HTTP/1.1 200 OK
server: istio-envoy
...
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

    The response should return a 404 Not Found status. This is expected because the /get endpoint does not have a matching URI prefix in the httpbin VirtualService resource. 

    HTTP/1.1 404 Not Found
server: istio-envoy
...
    Copy to Clipboard Toggle word wrap

  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"}}'
    Copy to Clipboard Toggle word wrap
    Note

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

  15. Verify that httpbin service can be accessed 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}')
      Copy to Clipboard Toggle word wrap

    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}')
      Copy to Clipboard Toggle word wrap

    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
      Copy to Clipboard Toggle word wrap
  16. Verify that the response has the HTTP/1.1 200 OK status, which indicates that the request was successful.

To enable traffic from outside an OpenShift cluster to access services in a mesh, you must expose a gateway proxy by either setting its Service type to LoadBalancer or by using the OpenShift Router.

Using Kubernetes load balancing to handle incoming traffic directly through the inbound gateway can reduce latency associated with data encryption. By managing encryption at the inbound gateway, you avoid the intermediate decryption and re-encryption steps within the mesh that often add latency. This approach allows mesh traffic to be encrypted and decrypted only once, which is generally more efficient.

The OpenShift Router provides a standard approach for managing ingress traffic, and you can use the router to manage certificates for all cluster ingress traffic using the same methods. However, the OpenShift Router introduces an additional hop between the inbound traffic and the mesh applications. Typically, you route the traffic by decrypting it at the router and then re-encrypting it at the service mesh ingress gateway, which introduces latency.

You can expose a gateway to traffic outside the cluster by using OpenShift Routes. This approach provides an alternative to using Kubernetes load balancer service when you have to expose gateways to traffic outside the cluster.

Prerequisites

  • You have completed the procedure, Exposing a Service by using the Istio Gateway and VirtualService resources.

Procedure

  1. Ensure that the Service type is set to ClusterIP by running the following command: 

    $ oc patch service <gateway_name> -n <gateway_namespace> -p '{"spec": {"type": "ClusterIP"}}'
    Copy to Clipboard Toggle word wrap

  2. Create a YAML file named httpbin-route.yaml that defines a Route for the httpbin service. 

    apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: httpbin
  namespace: <gateway_namespace>
spec:
  host: httpbin.example.com
  port:
    targetPort: http2
  to:
    kind: Service
    name: <gateway_name>
    weight: 100
  wildcardPolicy: None
    Copy to Clipboard Toggle word wrap

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

    $ oc apply -f httpbin-route.yaml
    Copy to Clipboard Toggle word wrap

  4. Verify that httpbin service can be accessed from outside the cluster through the ingress router. 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 router-default -n openshift-ingress -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
      Copy to Clipboard Toggle word wrap

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

      $ INGRESS_HOST=$(oc get service router-default -n openshift-ingress -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
      Copy to Clipboard Toggle word wrap

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

      $ curl -s -I -H Host:httpbin.example.com http://$INGRESS_HOST/headers
      Copy to Clipboard Toggle word wrap
  5. Verify that the response has the HTTP/1.1 200 OK status, which indicates that the request was successful.

You can use the Kubernetes Gateway API to create Gateway and HTTPRoute resources and deploy a gateway. The resources configure the gateway to expose a service in the mesh to traffic outside the mesh.

Prerequisites

  • You are logged in to the OpenShift Container Platform web console as a user with the cluster-admin role.
  • You installed the Red Hat OpenShift Service Mesh Operator.
  • You have deployed the Istio resource.

Procedure

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

    $ oc create namespace httpbin
    Copy to Clipboard Toggle word wrap

  2. When using sidecar injection instead of ambient mode, you must enable the sidecar injection in the namespace:

    1. For the InPlace upgrade strategy, run the following command: 

      $ oc label namespace httpbin istio-injection=enabled
      Copy to Clipboard Toggle word wrap

    2. For the RevisionBased upgrade strategy, run the following command: 

      $ oc label namespace httpbin istio.io/rev=<revision-name>
      Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  4. Create a YAML file named httpbin-gw.yaml that defines a Kubernetes Gateway resource, similar to the following example: 

    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
    Copy to Clipboard Toggle word wrap
    "httpbin.example.com"
    Specifies the virtual hostname that clients use when attempting to access a mesh service on the associated port.

    The HTTPRoute resource specifies the rules that route traffic from the gateway proxy to the httpbin service.

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

    $ oc apply -f httpbin-gw.yaml
    Copy to Clipboard Toggle word wrap

  6. Create a YAML file named httpbin-ingress-hr.yaml that defines an HTTPRoute resource for the ingress gateway, similar to the following example: 

    apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin-ingress
  namespace: httpbin
spec:
  parentRefs:
  - name: httpbin-gateway
    namespace: httpbin
  hostnames:
  - "httpbin.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /status
    - path:
        type: PathPrefix
        value: /headers
  - backendRefs:
    - name: httpbin
      port: 8000
    Copy to Clipboard Toggle word wrap
    • spec.parentRefs binds the HTTPROUTE resource to the Kubernetes Gateway resource that was created in the earlier 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.

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

    $ oc apply -f httpbin-ingress-hr.yaml
    Copy to Clipboard Toggle word wrap

  8. Ensure that the Gateway API service is ready, and that an address is allocated to the service, by running the following command: 

    $ oc wait --for=condition=programmed gtw httpbin-gateway -n httpbin
    Copy to Clipboard Toggle word wrap

Verification

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

    $ oc create namespace curl
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  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}')
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

    The response should return a 200 OK HTTP status, which indicates that the request was successful, similar to the following example: 

    HTTP/1.1 200 OK
server: istio-envoy
...
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

    The response returns a 404 Not Found status, as expected, because the /get endpoint does not have a matching URI prefix in the httpbin HTTPROUTE resource, similar to the following example: 

    HTTP/1.1 404 Not Found
server: istio-envoy
...
    Copy to Clipboard Toggle word wrap

  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"}}'
    Copy to Clipboard Toggle word wrap
    Note

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

  7. Verify that the httpbin service can be accessed 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}')
      Copy to Clipboard Toggle word wrap

    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}')
      Copy to Clipboard Toggle word wrap

    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
      Copy to Clipboard Toggle word wrap
  8. Verify that the response has the HTTP/1.1 200 OK status, which indicates that the request was successful.

When using the Istio ambient mode, you can use the Kubernetes Gateway API to configure ingress traffic routing.

Waypoint proxies for Layer 7 routing
You can deploy a waypoint proxy in the namespace that has your service to apply Layer 7 (L7) routing policies, such as path-based routing or header matching. In ambient mode, waypoint proxies process L7 traffic and enforce HTTPRoute and GRPCRoute rules.
Important

VirtualService resources are considered technology preview in ambient mode and should not be mixed with Gateway API configuration. The recommended approach in ambient mode is to use Kubernetes Gateway API resources.

You can use the Kubernetes Gateway API to create Gateway and HTTPRoute resources and deploy a gateway in ambient mode. The resources configure the gateway to expose a service in the mesh to traffic outside the mesh.

Prerequisites

  • You are logged in to the OpenShift Container Platform web console as a user with the cluster-admin role.
  • You have installed the Red Hat OpenShift Service Mesh Operator.
  • You have deployed the Istio resource.
  • You use the Kubernetes-native Gateway API resources.
  • You are either using the Istio ambient mode or planning on migrating to the ambient mode.
Note

When using ambient mode (istio.io/dataplane-mode=ambient), it is recommended to use the Kubernetes Gateway API for ingress configuration, as Istio Gateway and VirtualService resources are not fully compatible with ambient mode.

Procedure

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

    $ oc create namespace httpbin
    Copy to Clipboard Toggle word wrap

  2. Apply the label for ambient mode by running the following command: 

    $ oc label namespace httpbin istio.io/dataplane-mode=ambient
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  4. Deploy a waypoint proxy by creating a YAML file named httpbin-waypoint.yaml, similar to the following example: 

    apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: httpbin-waypoint
  namespace: httpbin
  labels:
    istio.io/waypoint-for: service
spec:
  gatewayClassName: istio-waypoint
  listeners:
  - name: mesh
    port: 15008
    protocol: HBONE
    Copy to Clipboard Toggle word wrap

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

    $ oc apply -f httpbin-waypoint.yaml
    Copy to Clipboard Toggle word wrap

  6. Enable ingress waypoint routing on the httpbin service by running the following command: 

    $ oc label service httpbin -n httpbin istio.io/ingress-use-waypoint=true
    Copy to Clipboard Toggle word wrap

    The label ensures that traffic from the ingress gateway routes through the waypoint proxy and the Layer 7 (L7) policies configured on the waypoint proxy are applied to the ingress traffic, before it reaches the httpbin service.

  7. Apply the waypoint label to the namespace so that all the services inside the namespace routes through the waypoint, by running the following command: 

    $ oc label ns httpbin istio.io/use-waypoint=httpbin-waypoint
    Copy to Clipboard Toggle word wrap

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

    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
    Copy to Clipboard Toggle word wrap
    "httpbin.example.com"
    Specifies the virtual hostname that clients use when attempting to access a mesh service on the associated port.

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

    $ oc apply -f httpbin-gw.yaml
    Copy to Clipboard Toggle word wrap

  10. Create a YAML file named httpbin-ingress-hr.yaml that defines an HTTPRoute resource for the ingress gateway, similar to the following example: 

    apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin-ingress
  namespace: httpbin
spec:
  parentRefs:
  - name: httpbin-gateway
    namespace: httpbin
  hostnames:
  - "httpbin.example.com"
  rules:
  - backendRefs:
    - name: httpbin
      port: 8000
    Copy to Clipboard Toggle word wrap
    • spec.parentRefs binds the HTTPROUTE resource to the Kubernetes Gateway resource that was created in the earlier 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.

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

    $ oc apply -f httpbin-ingress-hr.yaml
    Copy to Clipboard Toggle word wrap

  12. Create a YAML file named httpbin-waypoint-hr.yaml that defines an HTTPRoute resource for the waypoint proxy. 

    apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin-waypoint-route
  namespace: httpbin
spec:
  parentRefs:
  - group: ""
    kind: service
    name: httpbin
    namespace: httpbin
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /status
    - path:
        type: PathPrefix
        value: /headers
    backendRefs:
    - name: httpbin
      port: 8000
    Copy to Clipboard Toggle word wrap
    • spec.parentRefs binds the HTTPRoute resource to the httpbin service. When combined with the istio.io/ingress-use-waypoint=true label on the service, the HTTPRoute configures the L7 routing rules that the waypoint proxy will enforce for traffic destined to that service.
    • 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.

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

    $ oc apply -f httpbin-waypoint-hr.yaml
    Copy to Clipboard Toggle word wrap
    Note

    In this example use case, traffic from the ingress gateway flows through the waypoint proxy because of the istio.io/ingress-use-waypoint=true label. The HTTPRoute resource then applies path-based routing policies before the traffic reaches the httpbin service.

  14. Ensure that the waypoint proxy is ready by running the following command: 

    $ oc wait --for=condition=programmed gtw httpbin-waypoint -n httpbin
    Copy to Clipboard Toggle word wrap

Verification

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

    $ oc create namespace curl
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

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

    $ oc label namespace curl istio.io/dataplane-mode=ambient
    Copy to Clipboard Toggle word wrap

  4. 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}')
    Copy to Clipboard Toggle word wrap

  5. 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 \
    httpbin-gateway-istio.httpbin.svc.cluster.local/headers
    Copy to Clipboard Toggle word wrap

    The response should return a 200 OK HTTP status, which indicates that the request was successful, similar to the following example: 

    HTTP/1.1 200 OK
server: istio-envoy
...
    Copy to Clipboard Toggle word wrap

  6. 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 \
    httpbin-gateway-istio.httpbin.svc.cluster.local/get
    Copy to Clipboard Toggle word wrap

    The response returns a 404 Not Found status, as expected, because the /get endpoint does not have a matching URI prefix in the httpbin HTTPROUTE resource, similar to the following example: 

    HTTP/1.1 404 Not Found
server: istio-envoy
...
    Copy to Clipboard Toggle word wrap

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

    $ oc patch service httpbin-gateway-istio -n httpbin -p '{"spec": {"type": "LoadBalancer"}}'
    Copy to Clipboard Toggle word wrap
    Note

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

  8. Verify that the httpbin service can be accessed 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 httpbin-gateway -n httpbin -o jsonpath='{.status.addresses[0].value}')
      Copy to Clipboard Toggle word wrap

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

      $ INGRESS_PORT=$(oc get gtw httpbin-gateway -n httpbin -o jsonpath='{.spec.listeners[?(@.name=="http")].port}')
      Copy to Clipboard Toggle word wrap

    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
      Copy to Clipboard Toggle word wrap
  9. Verify that the response has the HTTP/1.1 200 OK status, which indicates that the request was successful.

Using Istio APIs, you can configure gateway proxies that were installed using gateway injection to direct traffic that is bound for an external service.

You can configure a gateway installed through gateway injection as an exit point for traffic leaving the service mesh. It acts as a forward proxy for requests sent to services external to the mesh.

Egress gateway

An egress gateway is configured as an exit point for traffic leaving the service mesh, acting as a forward proxy for requests sent to external services. You can configure an egress gateway to fulfill security requirements:

  • Traffic Restrictions: In environments with strict traffic restrictions, an egress gateway ensures all outbound traffic flows through a dedicated set of nodes.
  • Network Policy Enforcement: When network policies prevent application nodes from directly accessing external services, the egress gateway handles the external access.

In these scenarios, gateway proxies are deployed on dedicated egress nodes capable of accessing external services. These nodes can then be subjected to strict network policy enforcement or additional monitoring to enhance security.

Configure egress traffic

You can configure a gateway installed through gateway injection to direct the egress traffic by combining the following Istio resources:

  • Use the ServiceEntry resource to define the properties of an external service. The external service is added to the Istio service registry for the mesh, which enables you to apply Istio features, such as monitoring and routing rules, to the traffic exiting the mesh that is destined for an external service.
  • Use the Gateway, VirtualService, and DestinationRule resources to set up rules that route traffic from the mesh to the external service using the gateway proxy.
Egress routing in ambient mode

If your deployment uses ambient mode, you must configure egress routing using the Kubernetes Gateway API instead of Istio Gateway and VirtualService resources. The Kubernetes Gateway API provides a standardized, Kubernetes-native method for defining how traffic exits the mesh and reaches external services.

You can use Gateway and HTTPRoute (or GRPCRoute) resources to control how mesh traffic is routed to destinations outside the cluster. The Gateway API is fully supported in ambient mode and can also be used with sidecar-based deployments, providing a consistent configuration model for both ingress and egress routing.

Use Istio APIs to direct outbound HTTP traffic through a gateway that was installed using gateway injection.

Prerequisites

  • You have installed a gateway using gateway injection.

Procedure

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

    $ oc create namespace curl
    Copy to Clipboard Toggle word wrap

  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
      Copy to Clipboard Toggle word wrap

    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
        Copy to Clipboard Toggle word wrap

        Example output

        NAME     TYPE    READY   STATUS    IN USE   VERSION   AGE
default  Local   True    Healthy   True     v1.24.3   3m33s
        Copy to Clipboard Toggle word wrap

      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
        Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  4. Export a CURL_POD environment variable that has been initialized with the name of the curl pod: 

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

  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
    Copy to Clipboard Toggle word wrap

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

    $ oc apply -f http-se.yaml
    Copy to Clipboard Toggle word wrap

  7. Ensure the ServiceEntry configuration was applied 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
    Copy to Clipboard Toggle word wrap

    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. 

    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
    Copy to Clipboard Toggle word wrap

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

    $ oc apply -f http-gtw.yaml
    Copy to Clipboard Toggle word wrap

  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. 

    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
    Copy to Clipboard Toggle word wrap

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

    $ oc apply -f http-vs.yaml
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

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

    $ oc logs deployment/<gateway_name> -n <gateway_namespace> | tail -1
    Copy to Clipboard Toggle word wrap
    Note

    Access logging must be enabled 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 -
    Copy to Clipboard Toggle word wrap

Use the Kubernetes Gateway API to direct outbound HTTP traffic through an egress gateway.

Prerequisites

  • You installed an Istio control plane.
  • You configured the Istio and IstioCNI resources.

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. 

      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
      Copy to Clipboard Toggle word wrap

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

      $ oc apply -f gateway-cr.yaml
      Copy to Clipboard Toggle word wrap

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

    $ oc create namespace egress-gateway
    Copy to Clipboard Toggle word wrap

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

    $ oc label namespace egress-gateway istio-injection=enabled
    Copy to Clipboard Toggle word wrap

  4. Create a YAML file named egress-gateway-cr.yaml that defines the egress gateway. 

    # 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
    Copy to Clipboard Toggle word wrap

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

      $ oc apply -f egress-gateway-cr.yaml
      Copy to Clipboard Toggle word wrap

Verification

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

    $ oc describe gateway -n egress-gateway
    Copy to Clipboard Toggle word wrap

    Desired output is indicated by Programmed showing in the Status column.

  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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

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

Use the Kubernetes Gateway API and waypoint proxy to direct outbound HTTP traffic through an egress gateway.

Prerequisites

  • You have installed the OpenShift Service Mesh Operator version 3.2 or later.
  • You configured the Istio and IstioCNI resources with ambient profile.
  • You have created a Ztunnel resource.

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
    Copy to Clipboard Toggle word wrap

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

    $ oc label namespace egress-gateway istio.io/dataplane-mode=ambient
    Copy to Clipboard Toggle word wrap

  4. Create a YAML file named egress-se.yaml that defines the ServiceEntry. 

    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
    Copy to Clipboard Toggle word wrap

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

      $ oc apply -f egress-se.yaml
      Copy to Clipboard Toggle word wrap

    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
      Copy to Clipboard Toggle word wrap

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

      $ oc apply -f waypoint.yaml
      Copy to Clipboard Toggle word wrap
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
Copy to Clipboard Toggle word wrap

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
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

    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"
    Copy to Clipboard Toggle word wrap

Legal Notice
Copy link

Copyright © 2025 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat