Create ingress gateway
Overview
Ingress gateways define an entry point into your Istio mesh for incoming traffic.
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-v115x. 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.
-
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
-
Create a new ingress gateway using the IstioMeshGateway resource.
-
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-v115x 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
-
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
-
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-v115x","namespace":"istio-system"}
-
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
-
-
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-v115x
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