Kubestack

Nginx Ingress

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.

TL;DR:

  • Installing, updating or removing follows Kubestack's GitOps flow.
  • Instructions assume the default repository layout.
  • Bases can be consumed as-is or customized.
  • Step-by-step instructions are framework specific but bases can be used independently.

Install

  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.46.0-kbst.0.zip
    unzip -d manifests/bases/ nginx-v0.46.0-kbst.0.zip
    rm nginx-v0.46.0-kbst.0.zip

  2. Include resource in apps overlay

    cd manifests/overlays/apps
    kustomize edit add resource ../../bases/nginx/default-ingress

  3. Commit and push

    cd -
    git checkout -b add-nginx
    git add manifests/bases/nginx manifests/overlays/apps/kustomization.yaml
    git commit -m "Add nginx v0.46.0-kbst.0 base"
    git push origin add-nginx

  4. 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

To update the operator 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.46.0-kbst.0.zip
    unzip -d manifests/bases/ nginx-v0.46.0-kbst.0.zip
    rm nginx-v0.46.0-kbst.0.zip

  3. Commit and push

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

Remove

Operators often create resources based on custom objects. When removing an operator, follow a two-step process to ensure operator provisioned resources are purged properly.

  1. Remove all the operator's custom objects.
  2. Once the operator had time to de-provision all resources it created, follow the instructions below to remove the operator itself.

  1. Remove resource from apps overlay

    cd manifests/overlays/apps
    kustomize edit remove resource ../../bases/nginx/default-ingress

  2. Delete the vendored base from your repository

    cd -
    # Run these commands from the root of your Kubestack infra repository
    rm -r manifests/bases/nginx

  3. Commit and push

    git checkout -b remove-nginx
    git add manifests/bases/nginx
    git commit -m "Remove nginx base"
    git push origin remove-nginx

Usage

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

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 cluster's 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 above to the cluster FQDN you set up 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 definition. These additional parameters can be configured by setting annotations. Please refer to the Nginx ingress documentation for a list of available annotations.