Create ingress gateway

Overview

Ingress gateways define an entry point into your Istio mesh for incoming traffic.

Multiple ingress gateways in Istio

You can configure gateways using the Gateway and VirtualService custom resources of Istio, and the IstioMeshGateway CR of Service Mesh Manager.

  • The Gateway resource describes the port configuration of the gateway deployment that operates at the edge of the mesh and receives incoming or outgoing HTTP/TCP connections. The specification describes a set of ports that should be exposed, the type of protocol to use, TLS configuration – if any – of the exposed ports, and so on. For more information about the gateway resource, see the Istio documentation.
  • The VirtualService resource defines a set of traffic routing rules to apply when a host is addressed. Each routing rule defines matching criteria for the traffic of a specific protocol. If the traffic matches a routing rule, then it is sent to a named destination service defined in the registry. For example, it can route requests to different versions of a service or to a completely different service than was requested. Requests can be routed based on the request source and destination, HTTP paths and header fields, and weights associated with individual service versions. For more information about VirtualServices, see the Istio documentation.
  • Service Mesh Manager provides a custom resource called IstioMeshGateway and uses a separate controller to reconcile gateways, allowing you to use multiple gateways in multiple namespaces. That way you can also control who can manage gateways, without having permissions to modify other parts of the Istio mesh configuration.

Using IstioMeshGateway, you can add Istio ingress or egress gateways in the mesh and configure them. When you create a new IstioMeshGateway CR, Service Mesh Manager takes care of configuring and reconciling the necessary resources, including the Envoy deployment and its related Kubernetes service.

Note: Service Mesh Manager automatically creates an ingress gateway called smm-ingressgateway and an istio-meshexpansion-cp-v113x. The smm-ingressgateway serves as the main entry point for the services of Service Mesh Manager, for example, the dashboard and the API, while the meshexpansion gateway is used in multi-cluster setups to ensure communication between clusters for the Istio control plane and the user services.

Do not use this gateway for user workloads, because it is managed by Service Mesh Manager, and any change to its port configuration will be overwritten. Instead, create a new mesh gateway using the IstioMeshGateway custom resource.

Prerequisites

Auto sidecar injection must be enabled for the namespace of the service you want to make accessible.

Steps

To create a new ingress gateway and expose a service, complete the following steps.

  1. If you haven’t already done so, create and expose the service you want to make accessible through the gateway.

    For testing, you can download and apply the following echo service:

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: echo
      labels:
        k8s-app: echo
      namespace: default
    spec:
      replicas: 1
      selector:
        matchLabels:
          k8s-app: echo
      template:
        metadata:
          labels:
            k8s-app: echo
        spec:
          terminationGracePeriodSeconds: 2
          containers:
          - name: echo-service
            image: k8s.gcr.io/echoserver:1.10
            ports:
            - containerPort: 8080
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: echo
      labels:
        k8s-app: echo
      namespace: default
    spec:
      ports:
      - name: http
        port: 80
        targetPort: 8080
      selector:
        k8s-app: echo
    
    kubectl apply -f echo.yaml
    

    Expected output:

    deployment.apps/echo created
    service/echo created
    
  2. Create a new ingress gateway using the IstioMeshGateway resource.

    1. Download the following resource and adjust it as needed for your environment:

      CAUTION:

      By the default, the IstioMeshGateway pod is running without root privileges, therefore it cannot use ports under 1024. Either use ports above 1024 as targetports (for example, 8080 instead of 80) or run the gateway pod with root privileges by setting spec.runAsRoot: true in the IstioMeshGateway custom resource.
      apiVersion: servicemesh.cisco.com/v1alpha1
      kind: IstioMeshGateway
      metadata:
        name: demo-gw
      spec:
        istioControlPlane:
          name: cp-v113x
          namespace: istio-system
        runAsRoot: false
        service:
          ports:
            - name: tcp-status-port
              port: 15021
              protocol: TCP
              targetPort: 15021
            - name: http
              port: 80
              protocol: TCP
              targetPort: 8080
          type: LoadBalancer
        type: ingress 
      
    2. Apply the IstioMeshGateway resource. Service Mesh Manager creates a new ingress gateway deployment and a corresponding service, and automatically labels them with the gateway-name and gateway-type labels and their corresponding values.

      kubectl apply -f meshgw.yaml
      

      Expected output:

      istiomeshgateway.servicemesh.cisco.com/demo-gw created
      
    3. Get the IP address of the gateway. (Adjust the name and namespace of the IstioMeshGateway as needed for your environment.)

      kubectl -n default get istiomeshgateways demo-gw
      

      The output should be similar to:

      NAME      TYPE      SERVICE TYPE   STATUS      INGRESS IPS       ERROR   AGE    CONTROL PLANE
      demo-gw   ingress   LoadBalancer   Available   ["3.10.16.232"]           107s   {"name":"cp-v113x","namespace":"istio-system"}
      
    4. Create the Gateway and VirtualService resources to configure listening ports on the matching gateway deployment. Make sure to adjust the hosts fields to the external hostname of the service. (You should manually set an external hostname that points to these addresses, but for testing purposes you can use for example nip.io, which is a domain name that provides wildcard DNS for any IP address.)

      apiVersion: networking.istio.io/v1alpha3
      kind: Gateway
      metadata:
        name: echo
        namespace: default
      spec:
        selector:
          gateway-name: demo-gw
          gateway-type: ingress
        servers:
        - port:
            number: 80
            name: http
            protocol: HTTP
          hosts:
          - "echo.3.10.16.232.nip.io"
      ---
      apiVersion: networking.istio.io/v1alpha3
      kind: VirtualService
      metadata:
        name: echo
        namespace: default
      spec:
        hosts:
        - "echo.3.10.16.232.nip.io"
        gateways:
        - echo 
        http:
        - route:
          - destination:
              port:
                number: 80
              host: echo.default.svc.cluster.local
      
      kubectl apply -f gwvs.yaml
      

      Expected output:

      gateway.networking.istio.io/echo created
      virtualservice.networking.istio.io/echo created
      
  3. Access the service on the external address.

    curl -i echo.3.10.16.232.nip.io
    

    The output should be similar to:

    HTTP/1.1 200 OK
    date: Mon, 07 Mar 2022 19:22:15 GMT
    content-type: text/plain
    server: istio-envoy
    x-envoy-upstream-service-time: 1
    
    Hostname: echo-68578cf9d9-874rz
    ...
    

IstioMeshGateway CR reference

This section describes the fields of the IstioMeshGateway custom resource.

apiVersion (string)

Must be servicemesh.cisco.com/v1alpha1

kind (string)

Must be IstioMeshGateway

spec (object)

The configuration and parameters of the IstioMeshGateway.

spec.type (string, required)

Type of the mesh gateway. Ingress gateways define an entry point into your Istio mesh for incoming traffic, while egress gateways define an exit point from your Istio mesh for outgoing traffic. Possible values:

  • ingress
  • egress

spec.istioControlPlane (object, required)

Specifies the istiocontrolplane cr the istio-proxy connects to by a namespaced name. When upgrading to a new Istio version (thus to a new control plane), this should be upgraded.

For example:

spec:
  istioControlPlane:
    name: cp-v113x
    namespace: istio-system

spec.deployment (object)

Configuration options for the Kubernetes istio-proxy deployment. Metadata like labels and annotations can be set here for the deployment or pods as well, in spec.deployment.metadata.annotations or spec.deployment.podMetadata.annotations.

spec.service (object, required)

Configuration options for the Kubernetes service. Annotations can be set here as well as in spec.service.metadata.annotations, they are often useful in cloud loadbalancer cases, for example to specify some configuration for AWS.

For example:

  service:
    ports:
      - name: tcp-status-port
        port: 15021
        protocol: TCP
        targetPort: 15021
      - name: http
        port: 80
        protocol: TCP
        targetPort: 8080
    type: LoadBalancer

spec.runAsRoot (true | false)

Whether to run the gateway in a privileged container. If not running as root, only ports higher than 1024 can be opened on the container. Default value: false