Ingress Configuration

Configure NGINX basic routing with TLS on HPCC

6 min readAug 13, 2021

Basic Overview

This page provides steps on how to set up basic routing for ECLWatch with the NGINX Ingress controller and configure certificates using Cert-Manager, which provides automatic certificate generation and management functionality. Then, the Ingress controller External IP is mapped to a Fully Qualified Domain Name, used to access the service ECLWatch. TLS certificates are necessary because they are an important part of deploying a service to the Internet, and indicate to users if the website is secure. Cert-manager is used in this configuration to help with issuing certificates from the source. It will ensure certificates are valid and up to date, and attempt to renew certificates at a configured time before expiration.

What is Ingress?

Ingress defines traffic routing rules to manage external user access to services within a Kubernetes cluster. With Ingress, you can easily set up rules for routing traffic. It does this by mapping URLs to the services.

What is an Ingress Controller?

The Ingress Controller is responsible for routing requests to the appropriate services within the Kubernetes cluster, by reading and processing the rules in the Ingress resource.

How is Ingress-Nginx used with basic routing?

The Service (ECLWatch) will receive an External IP, which the NGINX controller will be made externally accessible. Requests to this IP will be handled by the NGINX controller and forwarded to the actual service(s) according to the Ingress resources. After configuring an Ingress resource, all requests will be handled by the IP and the Ingress Controller will perform the routing.

Prerequisites

Before beginning, have the following prerequisites deployed and running,

Basic Routing with Nginx

This section provides steps on how to configure rules in the Ingress resource that tells the NGINX controller to route traffic to the service ECLWatch, then test the resource is tested by visiting the controller’s External IP through a web browser.

Create the Ingress resource for creating rules that route HTTP traffic to ECLWatch

eclwatch.yaml

Breaking down the Ingress Resource file:

Lines 1–4: This is the common header for Ingress resources. An Ingress needs apiVersion, kind, and metadata fields.

Lines 5–6: Specify the annotation kubernetes.io/ingress.class: "nginx" in the Ingress for the Ingress-Nginx controller to read and process.

Lines 7–8: The Ingress spec has all the information needed to configure a load balancer or proxy server. Most importantly, it contains a list of rules matched against all incoming requests. Ingress resource only supports rules for directing HTTP(S) traffic. This section defines how incoming requests are mapped. Since there is no targeted hostname, all requests will be mapped to the same backend.

Lines 9–17: The path mapping specifies how requested paths are mapped to the backends. Backends are Services, deployed in the cluster, identified by a name and port number. All traffic will be configured for the service with the name ECLWatch, which is identified by port 8010.

2. Save the file, and configure the ingress resource:

kubectl apply -f eclwatch.yaml

Test the Ingress Configuration

Now that Ingress rules are configured, test them.

3. To test the rules, get the external IP of the Ingress controller:

Result of kubectl get svc

The External IP for the Ingress-Nginx controller is 52.188.72.200

4. Visit the external IP address of the Ingress controller, for example,

HTTP://<external_ip>

ECLWatch service shown through a web browser

The service for which the rules were configured, ECLWatch, is now accessible externally, through the external IP address of the controller.

This is basic HTTP routing, which means that the service is not secured. In order to secure the service, configure Transport Layer Security (TLS).

Enabling TLS

This section provides steps on using Cert-manager to retrieve and configure certificates for HTTPS. First, Configure a Fully Qualified Domain Name (FQDN) to map to the Nginx controller IP address. Then, a cluster issuer resource is configured in order to issue certificates. Afterward, the previously created Ingress resource for service ECLWatch is updated to support the FQDN and certificate generation. The Ingress Configuration is tested by visiting the FQDN in a web browser, in which the ECLWatch service is shown, along with a valid certificate and padlock, representing secure HTTP (HTTPS) will be shown.

5. Using the External IP address of the Ingress controller, set it equal to a variable named “IP”

IP="MY_EXTERNAL_IP"

6. Assign a name of your choice to a variable named “DNSNAME”, such as hpcc-ingress. This domain name system (DNS) name is the name that will be associated with the External IP address.

DNSNAME="hpcc-ingress"

7. Get the resource-ID of the External IP

Replace the Ingress controller External IP with the bolded placeholder shown below.

PUBLICIPID=$(az network public-ip list --query "[?ipAddress!=null]|[?contains(ipAddress, '<external_ip>')].[id]" --output tsv)

8. Update the External IP address with the DNS name

az network public-ip update --ids $PUBLICIPID --dns-name $DNSNAME

9. Display the FQDN

This command gets the newly created Fully Qualified Domain name that is mapped to the External IP address of the Ingress controller.

az network public-ip show --ids $PUBLICIPID --query "[dnsSettings.fqdn]" --output tsv

Create a CA Cluster Issuer

ClusterIssuers are Kubernetes resources that represent certificate authorities (CAs) that are able to generate signed certificates by honoring certificate signing requests.

10. Create a cluster issuer using the following example file. Update the email address with a valid address from your organization.

cluster-issuer.yaml

11. Configure the cluster issuer

kubectl apply -f cluster-issuer.yaml

Now, a certificate management solution has been configured.

Update the Ingress route

12. Update the previously configured Ingress route (eclwatch.yaml)

The hostnames are added, with the FQDN name previously created. The cluster issuer is also specified, which is Let’s Encrypt. A secret name, tls-secret, is created.

eclwatch.yaml (updated)

13. Configure the new Ingress resource

kubectl apply -f eclwatch.yaml

14. Verify that the certificate object is created

kubectl get certificate

Verifying that READY is True

NAME         READY   SECRET       AGE 
tls-secret   True    tls-secret   11m

Test the Ingress Configuration with TLS

15. To test the updated Ingress rules, use the previously created FQDN, and copy it into a web browser. In this example, the FQDN is:

hpcc-ingress.eastus2.cloudapp.azure.com

After entering the FQDN into the web browser, notice that you are redirected to use HTTPS and the certificate is trusted, and the service is shown in the web browser.

Clean Up resources

Delete the resources individually.

Delete the cluster issuer resource

kubectl delete -f cluster-issuer.yaml

2. Delete the ingress resource

kubectl delete -f eclwatch.yaml

Uninstall all releases, specifying the namespace if any.

3. Delete the HPCC Helm chart

helm delete hpcc

4. Delete the Ingress Nginx Controller

helm delete ingress-nginx

5. Delete the cert-manager

helm delete cert-manager

Conclusion

You just set up basic routing for ECLWatch with the NGINX Ingress controller and configured certificates using Cert-Manager. Then, the Ingress controller IP was mapped to a Fully Qualified Domain Name, which the service ECLWatch was accessible through.