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.
Create ingress gateway
To create a new ingress gateway and expose a service from the command line, complete the following steps. Alternatively, you can create an ingress gateway using the dashboard.
-
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:
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.For details on the IstioMeshGateway resource, see the IstioMeshGateway CR reference.
-
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.)
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 ...
Create ingress gateway using dashboard
-
To create an ingress gateway from Calisti dashboard, navigate to MENU > GATEWAYS page. Click CREATE NEW. An interface to select the
Ingress
gateway resource template opens. -
Select Ingress in the Template dropdown.
-
Here, you can edit the ingress gateway resource. To validate the correctness of the YAML resource, click Validate
. For details on the IstioMeshGateway resource, see the IstioMeshGateway CR reference.
-
Once the YAML file is validated and there are no errors, to create the ingress gateway, click Create.
Edit ingress gateway using dashboard
-
To edit a particular ingress gateway in your service mesh, click the Edit
icon at the end of the row.
-
Edit the selected gateway YAML, and validate the YAML. For details on the IstioMeshGateway resource, see the IstioMeshGateway CR reference.
-
To apply the changes to the YAML, click Apply.
Delete ingress gateway using dashboard
-
To delete a particular ingress gateway in your service mesh, click the Delete
icon at the end of the row.
-
If you are absolutely sure that you want to delete the selected ingress gateway, click Delete on the pop-up.
CAUTION:
Deleting the resource is irreversible and cannot be undone, as Calisti doesn’t store the old resource files.
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.
Example for Google Cloud Engine (GKE):
This example shows how to create an internal load balancer with a static ip address. The first step is to reserve a static ip address that can then be used by the load balancer.
More info about how to reserve a static internal ip address can be found at: Reserving a static internal IP address
More annotations and their description are available here: LoadBalancer Service parameters
IstioMeshGateway modifications:
service:
ports:
- name: tcp-status-port
port: 15021
protocol: TCP
targetPort: 15021
- name: http
port: 80
protocol: TCP
targetPort: 8080
type: LoadBalancer
loadBalancerIP: "10.100.100.100"
metadata:
annotations:
networking.gke.io/load-balancer-type: "Internal"
Gateway modifications:
spec:
selector:
gateway-name: demo-gw
gateway-type: ingress
servers:
- port:
number: 80
name: http
protocol: HTTP
hosts:
- "*"
VirtualService modifications:
spec:
hosts:
- "*"
gateways:
- echo
http:
- route:
- destination:
port:
number: 80
host: echo.default.svc.cluster.local
Example for Azure Kubernetes Service (AKS): This example shows how to modify the TCP idle timeout for a loadbalancer.
By default, it’s set to 4 minutes. If a period of inactivity is longer than the timeout value, there’s no guarantee that the TCP or HTTP session is maintained between the client and your cloud service.
More annotations and their description are available here: Azure LoadBalancer annotations
IstioMeshGateway modifications:
service:
ports:
- name: tcp-status-port
port: 15021
protocol: TCP
targetPort: 15021
- name: http
port: 80
protocol: TCP
targetPort: 8080
type: LoadBalancer
metadata:
annotations:
service.beta.kubernetes.io/azure-load-balancer-tcp-idle-timeout: "10"
Example for Amazon Web Services (AWS): This example shows how to create a load balancer to specify which nodes to include in the target group registration for instance target type.
More annotations and their description are available here: AWS Load Balancer Controller Annotations
IstioMeshGateway modifications:
service:
ports:
- name: tcp-status-port
port: 15021
protocol: TCP
targetPort: 15021
- name: http
port: 80
protocol: TCP
targetPort: 8080
type: LoadBalancer
metadata:
annotations:
service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: instance
service.beta.kubernetes.io/aws-load-balancer-target-node-labels: k8s-app=echo
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