Chapter 1. About 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 many applications in different namespaces to share the same gateway. Or, 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, similar to the following example:

   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

   These settings enable the gateway to read secrets so that it can obtain TLS credentials.

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, similar to the following example:

   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
         labels:
           istio: <gateway_name>
           sidecar.istio.io/inject: "true"
       spec:
         containers:
           - name: istio-proxy
             image: auto
             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

   • spec.template.annotations.inject.istio.io/templates indicates that the Istio control plane uses the gateway injection template instead of the default sidecar template.
   • spec.template.labels.istio ensures that you set a unique label for the gateway deployment. Istio Gateway resources require a unique label to select gateway workloads.
   • spec.template.labels.sidecar.istio.io/inject enables gateway injection by setting this 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.
   • spec.template.spec.containers.image sets the image field to auto so that the image automatically updates each time the pod starts.
   • spec.template.spec.serviceAccountName 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:

   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 has 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

   • spec.type sets the type of the gateway Service object. Setting spec.type to ClusterIP restricts gateway Service access to the internal cluster network. If the gateway has to handle ingress traffic from outside the cluster, set spec.type to LoadBalancer. Or, you can use OpenShift Routes.
   • spec.selector sets the selector to the unique label or set of labels specified in the pod template of the gateway deployment that you created previously.

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 usage exceeds 80% of the CPU resource limit. The gateway deployment’s pod template specifies this limit.

    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>

    • spec.scaleTargetRef.name specifies the name of the gateway deployment created previously.

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 eviction 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>

    • spec.selector.matchLabels specifies the unique label or set of labels specified in the pod template of the gateway deployment created previously.

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

    $ oc apply -f gateway-pdb.yml