Upgrade to NGINX Ingress Controller 4.0.0

This document explains how to upgrade F5 NGINX Ingress Controller to 4.0.0.

There are two necessary steps required: updating the apiVersion value of custom resources and configuring structured logging.

For NGINX Plus users, there is a third step to create a Secret for your license.

Update custom resource apiVersion

If the Helm chart you have been using is v2.x, before upgrading to NGINX Ingress Controller 4.0.0 you must update your GlobalConfiguration, Policy and TransportServer resources from apiVersion: k8s.nginx.org/v1alpha1 to apiVersion: k8s.nginx.org/v1.

If the Helm chart you have been using is v1.0.2 or earlier (NGINX Ingress Controller v3.2.2), upgrade to Helm chart v1.4.2 (NGINX Ingress Controller v3.7.2) before updating your GlobalConfiguration, Policy and TransportServer resources.

The example below shows the change for a Policy resource: you must do the same for all GlobalConfiguration and TransportServer resources.

• Before
• After

apiVersion: k8s.nginx.org/v1alpha1
kind: Policy
metadata:
  name: rate-limit-policy
spec:
  rateLimit:
    rate: 1r/s
    key: ${binary_remote_addr}
    zoneSize: 10M

apiVersion: k8s.nginx.org/v1
kind: Policy
metadata:
  name: rate-limit-policy
spec:
  rateLimit:
    rate: 1r/s
    key: ${binary_remote_addr}
    zoneSize: 10M

Warning:
If a GlobalConfiguration, Policy or TransportServer resource is deployed with apiVersion: k8s.nginx.org/v1alpha1, it will be deleted during the upgrade process.

Configure structured logging

To configure structured logging, you must update your log deployment arguments from an integer to a string. The logs themselves can also be rendered in different formats.

Note:
These options apply to NGINX Ingress Controller logs, and do not affect NGINX logs.

• Helm
• Manifests

controller:
    logLevel: info
    logFormat: json 

args:
    - -log-level=info
    - -log-format=json

Create License secret

If you’re using NGINX Plus with NGINX Ingress Controller, you should read the Create License Secret topic to set up your NGINX Plus license.

The topic also contains guidance for sending reports to NGINX Instance Manager, which is necessary for air-gapped environments.

In prior versions, usage reporting with the cluster connector was required: it is no longer necessary, as it is built into NGINX Plus.