Kubestack

Nginx Ingress
Terraform module for 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.

This Terraform module provisions Nginx Ingress on Kubernetes. It fully integrates the Kubernetes resources into the Terraform workflow and allows configuring Nginx Ingress using native Terraform syntax.

The Nginx Ingress module is continuously updated and tested when new upstream versions are released.

TL;DR:

  • Call the module once per desired target cluster.
  • The provider alias you pass into the module determines the cluster.
  • Customize the Kubernetes resources per environment using Terraform syntax.

Use the module

To provision the Nginx Ingress Terraform module on a Kubernetes cluster, call the module, set source and version, and pass an aliased kustomization provider into the module. The provider configuration determines what cluster the Kuberneters resources are provisioned on. Framework documentation includes a complete example of how the kubeconfig output of a cluster module can be used to configure a kustomization provider alias.

module "eks_zero_nginx" {
  providers = {
    kustomization = kustomization.eks_zero
  }


  source  = "kbst.xyz/catalog/nginx/kustomization"
  version = "1.2.1-kbst.0"
}


module "aks_zero_nginx" {
  providers = {
    kustomization = kustomization.aks_zero
  }


  source  = "kbst.xyz/catalog/nginx/kustomization"
  version = "1.2.1-kbst.0"
}


module "gke_zero_nginx" {
  providers = {
    kustomization = kustomization.gke_zero
  }


  source  = "kbst.xyz/catalog/nginx/kustomization"
  version = "1.2.1-kbst.0"
}

Customize resources

All Kubestack cluster service modules support the same module attributes and per environment configuration. The module configuration is a Kustomization set in the per environment configuration map following Kubestack's inheritance model.

This example overwrites the metadata.namespace of all Kubernetes resources provisioned by the Nginx Ingress module using a Terraform variable.

module "example_nginx" {
  providers = {
    kustomization = kustomization.example
  }


  source  = "kbst.xyz/catalog/nginx/kustomization"
  version = "1.2.1-kbst.0"


  configuration = {
    apps = {
      namespace = var.example_nginx_namespace
    }


    ops = {}


    loc = {}
  }
}

Full documentation how to customize a module's Kubernetes resources is available in the cluster service module configuration section of the framework documentation.

Expose a service

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.