Configuring Ingress Routing

This topic describes how to configure an ingress controller on VMware Tanzu Kubernetes Grid Integrated Edition (TKGI).

For information about configuring an ingress controller using NSX, see Configuring Ingress Resources and Load Balancer Services.

Overview

In Kubernetes, an ingress is an API object that manages external access to the services in a cluster. You can use ingress rules to provide HTTP or HTTPS routes to services within the cluster instead of creating a load balancer. For more information, see Ingress in the Kubernetes documentation.

The cluster must have an ingress controller running. You define ingress resource configuration in the manifest of your Kubernetes deployment, and then use wildcard DNS entries to route traffic to the exposed ingress resource.

To configure an ingress controller, you must do the following:

Deploy a Kubernetes Ingress Controller
Configure DNS
(Optional) Configure TLS
Deploy an App to the Cluster

Prerequisites

Before you configure an ingress controller, you must have the following:

A TKGI-deployed cluster with its own load balancer. See Creating Clusters.
A wildcard DNS record that points to the cluster load balancer.

Deploy a Kubernetes Ingress Controller

You can deploy an ingress controller of your choice to your Kubernetes cluster. For a list of ingress controllers that Kubernetes supports, see Ingress Controllers in the Kubernetes documentation.

Note: For information about configuring an ingress controller using NGINX on Amazon Web Services (AWS), Azure, or Google Cloud Platform (GCP), see How to set up an Ingress Controller for a TKGI cluster in the Knowledge Base.

To deploy an open source ingress controller to a TKGI cluster, do the following:

To set the kubectl context for the cluster where you want to deploy the ingress controller, run the following command:
```
tkgi get-credentials CLUSTER-NAME
```
Where CLUSTER-NAME is the name of your TKGI-deployed Kubernetes cluster.

For example:
```
$ tkgi get-credentials tkgi-example-cluster  

Fetching credentials for cluster tkgi-example-cluster.  
Context set for cluster tkgi-example-cluster.  

You can now switch between clusters by using:  
$kubectl config use-context <cluster-name>  
```
Note: If your operator has configured Tanzu Kubernetes Grid Integrated Edition to use a SAML identity provider, you must include an additional SSO flag to use the above command. For information about the SSO flags, see the section for the above command in TKGI CLI. For information about configuring SAML, see Connecting Tanzu Kubernetes Grid Integrated Edition to a SAML Identity Provider
To verify a DNS service is enabled for your Kubernetes cluster, run the following command:
```
kubectl cluster-info
```
If a DNS service is enabled, the DNS service’s URL is included in the kubectl cluster-info output.

For example:
```
$ kubectl cluster-info
Kubernetes master is running at https://104.197.5.247
elasticsearch-logging is running at https://104.197.5.247/api/v1/namespaces/kube-system/services/elasticsearch-logging/proxy
kibana-logging is running at https://104.197.5.247/api/v1/namespaces/kube-system/services/kibana-logging/proxy
CoreDNS is running at https://104.197.5.247/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
grafana is running at https://104.197.5.247/api/v1/namespaces/kube-system/services/monitoring-grafana/proxy
```
The current default Kubernetes cluster DNS service is CoreDNS. The example output above includes the URL for this DNS service, indicating it is running.

If a DNS service is not running for your cluster, enable the CoreDNS service:
1. Navigate to Ops Manager and click the BOSH Director tile.
2. Click the Director Config pane.
3. Select the Enable Post Deploy Scripts check box.
4. Click Review Pending Changes, and then Apply Changes.
5. Delete the cluster, and then re-create the cluster.
Follow the installation instructions for the Kubernetes ingress controller you choose to deploy. For example, see the installation guide in the Istio documentation.

Configure DNS

After you deploy an ingress controller to your cluster, locate the HTTP port number that the ingress rules expose. Configure DNS to point to the exposed port on your Kubernetes worker node VMs.

To configure DNS for your cluster, do the following:

Run kubectl get services in the namespace where you deployed the ingress controller. For example, if you deployed Istio, run the following command:
```
kubectl  --namespace=istio-system get services
```
In the output of this command, locate the exposed HTTP port.

For example:
```
$ kubectl --namespace=istio-system get services
NAME           TYPE            CLUSTER-IP       EXTERNAL-IP     PORT(S)
istio-ingress  LoadBalancer    10.100.200.200   <pending>       80:30822/TCP,443:31441/TCP
```
In the example above, the exposed HTTP port is 30822.
List the IP addresses for the Kubernetes worker node VMs by running the following command:
```
kubectl -o jsonpath='{.items[*].status.addresses[0].address}' get nodes
```
Configure your load balancer to point to the Kubernetes worker node VMs, using the IP addresses you located in the previous step and the exposed port number you located in the first step.

(Optional) Configure TLS

Enable Transport Layer Security (TLS) for the domain you configured for the cluster.

To configure TLS, do the following:

(Optional) Run the following command to generate a self-signed certificate:
```
openssl req -x509 \
  -nodes -newkey rsa:4096 \
  -keyout KEY-PATH.pem \
  -out CERT-PATH.pem \
  -days 365 \
  -subj "/CN=*.TKGI.EXAMPLE.COM"
```
Where:
- KEY-PATH.pem is the file path for the key you are generating.
- CERT-PATH.pem is the file path for the certificate you are generating.
- *.TKGI.EXAMPLE.COM is the wildcard domain you configured in Configure DNS.
Upload your TLS certificate and key to your ingress controller namespace by running the following command:
```
kubectl -n INGRESS-NAMESPACE create secret tls INGRESS-CERT \
--key KEY-PATH.pem --cert CERT-PATH.pem
```
Where:
- INGRESS-CERT is a name you provide for the Kubernetes secret that contains your TLS certificate and key pair.
- KEY-PATH.pem is the file path for your TLS key.
- CERT-PATH.pem is the file path for your TLS certificate.
For example:
```
$ kubectl -n istio-system create secret tls istio-ingress-certs \
--key /tmp/tls.key --cert /tmp/tls.crt
```

Deploy an App to the Cluster

When your cluster has an ingress controller running and DNS configured, you can deploy an app to the cluster that uses the ingress rules.

To deploy an app that uses ingress rules, do the following:

Deploy your app manifest by running the following command:
```
kubectl create -f YOUR-APP.yml
```
Where YOUR-APP.yml is the file path for your app manifest.
In the app manifest for your ingress controller, change the value of the host: property to match the wildcard domain you configured in Configure DNS above.
Deploy your ingress controller app manifest by running the following command:
```
kubectl create -f YOUR-APP.yml
```
Where INGRESS-CONTROLLER.yml is the file path for your ingress controller app manifest.
Navigate to the fully qualified domain name (FQDN) you defined in your app manifest and confirm that you can access your app workload.
(Optional) If you configured TLS, do the following:
1. Add the following to your ingress controller manifest to enable TLS:
```
spec:
  tls:
    - secretName: INGRESS-CERT
  rules:
  - host: INGRESS.TKGI.EXAMPLE.COM
```
  Where:
  - INGRESS-CERT is the name of the Kubernetes secret that contains your TLS certificate and key pair.
  - INGRESS.TKGI.EXAMPLE.COM is the domain you defined for your app in the app manifest.
2. Redeploy the ingress controller manifest to update the ingress service by running the following command:
```
kubectl replace -f INGRESS-CONTROLLER.yml
```
  Where INGRESS-CONTROLLER.yml is the file path for your ingress controller app manifest.
3. Navigate to the FQDN you defined in your app manifest and confirm that you can access your app workload.