ingress-nginx Reference

Contents

• Resources
• Components
  • Deployment
  • ConfigMap
  • Ingress Object(s)
• krew plugin
• Configuration
  • Inspecting
  • Modifying the Deployment Object
  • ConfigMap
  • Kubernetes Annotations
  • Custom nginx Configuration Template
• Reloads
• Commands

Resources

• ingress-nginx User Guide
• ingress-nginx GitHub Repository
• ingress-nginx upgrade guide

Components

Deployment

This is the IngressController itself. Any runtime configuration arguments go here.

ConfigMap

Key-value store of nginx properties. Configuration information below.

Ingress Object(s)

The access point(s) for your cluster that the IngressController will fulfill.

krew plugin

kubectl may be configured through krew with a plugin specific to ingress-nginx. Installation information available here.

Once installed, access is via:

kubectl ingress-nginx --help

Configuration

Inspecting

View the section of the generated nginx.conf for a host example.com:

kubectl ingress-nginx conf --host example.com -n ingress-nginx

View the entire generated nginx.conf:

kubectl ingress-nginx conf -n ingress-nginx

Modifying the Deployment Object

The Deployment object for ingress-nginx on the last line of the manifest and provides an args list for configuration:

---
apiVersion: apps/v1
kind: Deployment
metadata:
  ...
spec:
  ...
  template:
    ...
    spec:
      serviceAccountName: nginx-ingress-serviceaccount
      containers:
        - name: nginx-ingress-controller
          image: quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.25.0
          args:
            - /nginx-ingress-controller
            - --configmap=$(POD_NAMESPACE)/nginx-configuration
            - --tcp-services-configmap=$(POD_NAMESPACE)/tcp-services
            - --udp-services-configmap=$(POD_NAMESPACE)/udp-services
            - --publish-service=$(POD_NAMESPACE)/ingress-nginx
            - --annotations-prefix=nginx.ingress.kubernetes.io

For example, to change log level to 5 one would add:

- --v=5

ConfigMap

The default ConfigMap name is nginx-configuration in the ingress-nginx namespace. This key-value store directly replaces properties that would otherwise be set by nginx value directives, and can only contain strings.

A full list of supported keys are available here.

Kubernetes Annotations

Individual Ingress objects may be configured through annotations. Of particular use:

# applies snippet to the location "/" block
nginx.ingress.kubernetes.io/configuration-snippet: |
    # I am a configuration-snippet!
# returns 308 if ingress terminates TLS
nginx.ingress.kubernetes.io/ssl-redirect: "true"
# applies snippet to the server configuration block
nginx.ingress.kubernetes.io/server-snippet: |
  # I am a server-snippet!

Full list available here.

Custom nginx Configuration Template

More information available in the official documentation.

Reloads

Generally, ingress-nginx does not to be manually reloaded (e.g. sending a HUP signal to the nginx PID). If you have confirmed your kubernetes objects are configured properly and ingress-nginx is still not reflecting the state you expect, investigate and if warranted, file an issue.

Commands

List backends:

kubectl ingress-nginx -n ingress-nginx backends --list

Get logs over the last hour:

kubectl ingress-nginx logs --since 1h -n ingress-nginx