Setting Up Kubernetes Ingress

The Ingress resource serves to expose single- or multi-node deployments in Kubernetes, acting as a reverse proxy to one or more Service resources.

This guide will introduce you to some scenarios for setting up Ingress, assuming you’ve installed Document Engine with Helm into a namespace named document-engine and your Helm values file is named document-engine.values.yaml.

Ingress-nginx

Ingress-nginx is the most common ingress controller.

To expose Document Engine at http://de.example.com, set the /ingress section of document-engine.values.yaml in the following way:

---
ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    nginx.ingress.kubernetes.io/proxy-body-size: "16m"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "180"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "180"
    nginx.ingress.kubernetes.io/large-client-header-buffers: "8 16k"
    nginx.ingress.kubernetes.io/proxy-buffer-size: "128k"
  hosts:
    - host: de.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific

Note that de.example.com must be resolved by DNS to the address Ingress is responding at. On most platforms, this implies a CNAME record. To determine the hostname it has to point to, use the following command:

kubectl get ingress -n document-engine \
  document-engine \
  -o=jsonpath='{.status.loadBalancer.ingress}'

It’ll give an output similar to the following:

[{"hostname":"k8s-ingressn-ingressn-7531d67379.amazonaws.com"}]

Ingress-nginx with HTTPS

If you have a TLS certificate for de.example.com with the following code, de.example.com.key is your private key, and de.example.com.cert is the certificate file, and both should be in PEM format:

kubectl create secret -n document-engine \
  tls de-ingress-tls \
  --key de.example.com.key --cert de.example.com.cert

Incorporating the secret into the Ingress definition is done by adding the /ingress/tls section to the values file:

---
ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    nginx.ingress.kubernetes.io/proxy-body-size: "16m"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "180"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "180"
    nginx.ingress.kubernetes.io/large-client-header-buffers: "8 16k"
    nginx.ingress.kubernetes.io/proxy-buffer-size: "128k"
  hosts:
    - host: de.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific
  tls:
    - hosts:
        - de.example.com
      secretName: de-ingress-tls

Automatic TLS Certificates with Ingress-nginx and cert-manager

A more sustainable approach than that of manual secret creation is automatic TLS certificate management.

If you have cert-manager installed in the cluster with a global issuer named my-tls-issuer, secrets will be created and rotated automatically by cert-manager.

To enable this functionality, use the cert-manager.io/issuer annotation:

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: my-tls-issuer
    nginx.ingress.kubernetes.io/rewrite-target: /
    nginx.ingress.kubernetes.io/proxy-body-size: "16m"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "180"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "180"
    nginx.ingress.kubernetes.io/large-client-header-buffers: "8 16k"
    nginx.ingress.kubernetes.io/proxy-buffer-size: "128k"
  hosts:
    - host: de.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific
  tls:
    - hosts:
        - de.example.com
      secretName: de-ingress-tls