Gateways

Procedure

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

   $ oc create namespace <gateway_namespace>

   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

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

   $ oc apply -f secret-reader.yml

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

   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

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

   $ oc rollout status deployment/<gateway_name> -n <gateway_namespace>

   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

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

   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

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>

   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

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

    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

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

    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

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

      Sample output:

      NAME              TYPE    READY   STATUS    IN USE   VERSION   AGE
      default-v1-23-0   Local   True    Healthy   True    v1.23.0   3m33s

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

      $ oc label namespace httpbin istio.io/rev=default-v1-23-0

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.

   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

   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

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

   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

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. This is expected because the /get endpoint does not have a matching URI prefix in the httpbin VirtualService resource.

    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

    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}')

    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. Ensure that the Service type is set to ClusterIP by running the following command:

   $ oc patch service  -n  -p '{"spec": {"type": "ClusterIP"}}'

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

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

   $ oc apply -f httpbin-route.yaml

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}')

   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}')

   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

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