How to Set Up an NGINX Ingress Controller on DigitalOcean Kubernetes

DigitalOcean’s Managed Kubernetes service simplifies provisioning and maintaining Kubernetes clusters. The platform provides a ready-to-use foundation for containerized workloads with one-click support for common addon applications.

In this article, we’ll show how to use one of these addons to set up an NGINX Ingress controller in your cluster. Ingresses provide a mechanism for routing external traffic to your services based on rules such as hostname, path, and headers. NGINX Ingress is one of the most popular Ingress controllers; it uses the NGINX web server as a reverse proxy that directs incoming traffic to the correct Kubernetes service.

Getting Started

You should create a Kubernetes cluster in your DigitalOcean account before you follow this tutorial. We’ll also assume you’re familiar with the basics of using Kubernetes, Kubectl, and DigitalOcean’s cloud control panel.

Begin by logging into to your DigitalOcean control panel, clicking the “Kubernetes” link in the left sidebar, and selecting your cluster on the page that appears. Next click the “Marketplace” tab to view the list of available 1-Click Apps.

What Are 1-Click Apps?

DigitalOcean’s Kubernetes 1-Click Apps provide pre-configured installations for popular in-cluster applications. The apps are tested by DigitalOcean so they’re guaranteed to work with each available Kubernetes version.

Available apps use the official Helm chart from their vendor. The charts are augmented by default settings supplied by DigitalOcean in an open-source GitHub repository. The DigitalOcean control panel lets you install the available charts with one click, providing an easy way to get up and running with essential utilities. You don’t have to manually install Helm and set up chart repositories.

Installing NGINX Ingress With the 1-Click App

You can now use this technique to add NGINX Ingress to your cluster. Find the app in the marketplace by scrolling down the list or using the searchbar. Click the blue “Install” button on the app’s card and acknowledge the confirmation prompt.

The installation procedure can take several minutes to complete. Progress will be displayed in the web UI. A new load balancer will be automatically added to your account during the app’s set up process. This load balancer will be billed at the standard rate and should be used as the external entrypoint for your cluster.

Your Ingress controller will be ready to use after the installation completes. As the 1-Click App is based on a Helm chart, you can check the app’s been added by listing the Helm releases in your cluster:

$ helm list --all-namespaces
NAME                    NAMESPACE               REVISION  UPDATED                                 STATUS    CHART                       APP VERSION 
ingress-nginx           ingress-nginx           1         2022-05-30 14:46:37.591626084 +0000 UTC deployed  ingress-nginx-4.1.0-beta.1  1.2.0-beta.1

The ingress-nginx release was added by DigitalOcean. It shows as deployed so you can start creating Ingress resources to route traffic to your services.

Using Your Ingress Controller

You can test your Ingress controller by creating simple Kubernetes deployment, service, and Ingress resources:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: demo-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: demo-app
  template:
    metadata:
      labels:
        app: demo-app
    spec:
      containers:
      - name: demo-container
        image: httpd:latest
        ports:
          - containerPort: 80
 
---

apiVersion: v1
kind: Service
metadata:
  name: demo-service
spec:
  selector:
    app: demo-app
  ports:
    - port: 80
 
---

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-ingress
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: demo-service
                port:
                  number: 80

Apply this manifest to your cluster using Kubectl:

$ kubectl apply -f app.yaml

The spec.ingressClassName: nginx field in the Ingress resource means it will be registered with the newly installed NGINX Ingress controller. Each controller implementation has its own class name so you can use multiple controllers in one cluster.

Next set up a DNS record for example.com that points to the external IP address of your DigitalOcean load balancer. You can find this by navigating to Networking > Load Balancers in the online control panel or by running the following Kubectl command:

$ kubectl get service ingress-nginx-controller --namespace=ingress-nginx
NAME                       TYPE           CLUSTER-IP       EXTERNAL-IP    PORT(S)                      AGE
ingress-nginx-controller   LoadBalancer   XXX.XXX.XXX.XXX  1.2.3.4        80:30547/TCP,443:32027/TCP   1d

Visiting example.com should show the default Apache webpage once the DNS change takes effect. Your Ingress controller receives the request from the load balancer. It uses your Ingress resources to select an appropriate service, causing requests to example.com to end up with your Apache containers.

Now you can follow the Kubernetes documentation to create Ingress resources that express the service routing rules needed for your real applications.

Adding HTTPS

Endpoints on production clusters should be protected with TLS. You can set up automated HTTPS certificates by adding Cert-Manager to your cluster, alongside the NGINX Ingress Controller.

Cert-Manager is available as an additional 1-Click App from the DigitalOcean Marketplace. You can repeat the procedure used earlier: head to your cluster’s overview page in the control panel, click the “Marketplace” tab, and find and install the application.

After the installation completes, create a certificate issuer that will be used to request Let’s Encrypt certificates:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    email: example@example.com
    privateKeySecretRef:
      name: letsencrypt-staging
    solvers:
      - http01:
          ingress:
            class: nginx

Change the spec.acme.email field to your own email address so Let’s Encrypt can reach you with notifications about your certificates. Then apply the manifest to your cluster:

$ kubectl apply -f issuer.yml

Now you can update your Ingress resource with HTTPS support:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-ingress
  annotations:
    kubernetes.io/ingress.class: ingress
    cert-manager.io/cluster-issuer: letsencrypt-staging
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: demo-service
                port:
                  number: 80
  tls:
    - hosts:
       - example.com

The new spec.tls field specifies that a certificate should be acquired for the example.com domain. The letsencrypt-staging certificate issuer will be used, as defined by the cert-manager.io/cluster-issuer annotation.

The example shown above uses Let’s Encrypt’s staging endpoint which is recommended while you’re testing your deployment. You can switch to using real certificates by creating a second issuer that targets the production endpoints. Copy the Issuer manifest above, replace letsencrypt-staging with letsencrypt-production, and change the spec.acme.server URL to https://acme-v02.api.letsencrypt.org/directory. Afterwards you can update your Ingress resource’s cert-manager.io/cluster-issuer annotation to reference your new letsencrypt-production issuer.

Managing Your NGINX Ingress Installation

Unfortunately DigitalOcean’s 1-Click Apps only simplify the installation experience. You’re on your own when it comes to managing and updating your applications. As apps are simply pre-configured Helm charts, this isn’t as onerous as it sounds.

You can use your local Helm CLI installation to upgrade to new NGINX Ingress releases:

$ helm upgrade ingress-nginx ingress-nginx/ingress-nginx 
  --namespace ingress-nginx
  --values values.yml

You should download the values.yml file from DigitalOcean’s Marketplace repository first. This will ensure the new release is configured with your existing settings. You can also use this procedure to customize your Ingress controller with your own settings after initial installation. Modify the values.yml file and then run the helm upgrade command.

Removing NGINX Ingress From Your Cluster

You can completely remove NGINX Ingress from your cluster by uninstalling the app’s Helm release and deleting the namespace that was created:

$ helm uninstall ingress-nginx --namespace ingress-nginx
$ kubectl delete namespace ingress-nginx

The load balancer should be cleaned up automatically. You can manually delete it from the Networking > Load Balancers page in the DigitalOcean control panel if you need to. Click the “More” button next to the load balancer, then choose “Destroy” from the dropdown menu. You won’t be able to recover the IP address that was allocated.

Installing NGINX Ingress With Doctl

You can install 1-Click Apps using DigitalOcean’s Doctl command-line client. Begin by retrieving the list of your Kubernetes clusters:

$ doctl kubernetes cluster list
ID                                      Name        Region    Version        Auto Upgrade    Status     Node Pools
946407f3-abcd-123a-456b-6a0ec60f93bf    demo-k8s    lon1      1.22.8-do.1    false           running    demo-k8s-1

Next run the following command to add NGINX Ingress to your cluster. Replace <cluster-id> with the ID that was displayed above.

$ doctl kubernetes 1-click install <cluster-id> 
  --1-clicks ingress-nginx

Use this alternative if you want to install Cert-Manager too:

$ doctl kubernetes 1-click install <cluster-id> 
  --1-clicks ingress-nginx,cert-manager

Besides using Doctl, you can also interact with the DigitalOcean API directly to programmatically add new applications to your cluster.

Summary

You can quickly add the NGINX Ingress controller to a DigitalOcean Kubernetes cluster by using the 1-Click App available in the Marketplace. This deploys a pre-configured release of the NGINX Ingress Helm chart with ready-to-use configuration.

Although this accelerates initial provisioning, you must still manually run Helm commands to manage and upgrade your installation. The 1-Click App aims to strike a balance between ease of use and customization, ensuring you’re not locked-in to a specific set of parameters.