Nginx Ingress logo Nginx Ingress

Nginx Ingress
for Kubernetes

by Kubernetes

The Nginx ingress controller provisions and configures Nginx based on Kubernetes ingress resources to expose services outside of the cluster. It provides load balancing, SSL termination, name-based virtual hosting and more.

Nginx is included as the default ingress controller for Kubestack, so that independently of the cloud provider applications can always rely on a common ingress setup.

Documentation

description README

Install, update and remove

description EXPOSE

Expose an application

Install the Nginx Ingress Controller

info_outline

Below instructions explain how to install Nginx as the Kubestack default ingress controller. If you followed the quickstart, Nginx ingress is already deployed and configured, you can continue with creating an ingress resource.

  1. Vendor the base

    # Run these commands from the root of your Kubestack infra repository
    wget https://storage.googleapis.com/catalog.kubestack.com/nginx-v0.24.1-kbst.1.zip
    unzip -d manifests/bases/ nginx-v0.24.1-kbst.1.zip
    rm nginx-v0.24.1-kbst.1.zip
    
info_outline

It is possible to use the Nginx ingress Kustomize base to customize the default ingress or deploy an additional ingress controller. To do so, take a look at how nginx/default-ingress uses the nginx/base which itself packages upstream.

  1. Include in bases

    cd manifests/overlays/common
    kustomize edit add base ../../bases/nginx/default-ingress
    
  2. Commit and push

    cd -
    git checkout -b add-nginx
    git add manifests/bases/nginx manifests/overlays/common/kustomization.yaml
    git commit -m "Add nginx v0.24.1-kbst.1 base"
    git push origin add-nginx
    
  3. Review PR and merge

    Finally, review and merge the PR into master. Once it's been successfully applied against the Ops-Cluster set a prod-deploy tag to also apply the change against the Apps-Cluster.


Update the Nginx Ingress Controller

info_outline

These instructions assume the Nginx ingress controller has been included as the default-ingress controller. If you made modifications, adjust accordingly.

To update the default ingress controller delete the previously vendored base and then vendor the new version.

  1. Delete the previous vendored version

    # Run these commands from the root of your Kubestack infra repository
    rm -r manifests/bases/nginx
    
  2. Vendor the new version

    # Run these commands from the root of your Kubestack infra repository
    wget https://storage.googleapis.com/catalog.kubestack.com/nginx-v0.24.1-kbst.1.zip
    unzip -d manifests/bases/ nginx-v0.24.1-kbst.1.zip
    rm nginx-v0.24.1-kbst.1.zip
    
  3. Commit and push

    git checkout -b update-nginx
    git add manifests/bases/nginx
    git commit -m "Update nginx base to v0.24.1-kbst.1"
    git push origin update-nginx
    

Remove the Nginx Ingress Controller

  1. Delete the vendored base from your repository

    # Run these commands from the root of your Kubestack infra repository
    rm -r manifests/bases/nginx
    
  2. Commit and push

    git checkout -b remove-nginx
    git add manifests/bases/nginx
    git commit -m "Remove nginx base"
    git push origin remove-nginx
    
  3. Delete the default ingress controller

    When manifests are applied using kubectl apply, resources that have been removed from the manifests, are not removed from the cluster. So, as a last step, we need to delete the ingress controller from our cluster, which we can do by simply deleting the namespace.

    # Please note, removing the default ingress controller may cause application downtime
    kubectl delete namespace ingress-kbst-default
    

Exposing an Application Using Nginx Ingress

With the Nginx ingress controller deployed to the Kubernetes cluster, you can use it to expose services outside of the cluster.

info_outline

The included DNS zone is used for host based routing in the example below. However, for user facing applications, consider using a CNAME record to point your domain to the clsuters FQDN and then do host based routing on your domain.

Kubernetes Ingress Resource

To configure how your service is exposed through Nginx ingress, use a Kubernetes' built-in ingress resource. Below is an example ingress resource that routes HTTP requests based on the host header to a specific service inside the cluster. For more details about the configuration options, please refer to the official documentation.

To get started, put the example below into a file called ingress.yaml and add it to your application's manifests.

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  # CHANGE ME
  name: example-app
  namespace: example-app
spec:
  rules:
    # CHANGE ME
  - host: appname.kbst-apps-us-east1.gcp.infra.example.com
    http:
      paths:
      - backend:
          # CHANGE ME
          serviceName: example-app
          servicePort: 80

Next, adapt the name, namespace, host and serviceName in the example below to the cluster FQDN you setup at the end of the quickstart and the name of the service of the application you want to expose.

Finally, apply the manifests including the ingress.yaml as usual.

Nginx Ingress Annotations

Nginx ingress exposes a number of Nginx configuration options and features including redirects, authentication and more that are not part of the Kubernetes ingress defintion. These additional parameters can be configured by setting annotations. Please refer to the Nginx ingress documentation for a list of available annotations.