Migrate from Ingress-NGINX Controller to NGINX Ingress Controller

This document describes how to migrate from the community-maintained Ingress-NGINX Controller to F5 NGINX Ingress Controller.

Overview

This page explains two different ways to migrate from the community-maintained Ingress-NGINX Controller project to NGINX Ingress Controller: using NGINX’s Ingress Resources or with Kubernetes’s built-in Ingress Resources. This is typically because of implementation differences, and to take advantage of features such as NGINX Plus integration.

The information in this guide is extracted from a free eBook called “Kubernetes Ingress Controller Deployment and Security with NGINX”, which can be downloaded from the NGINX Library.

Before you begin

To complete the instructions in this guide, you need the following:

• A working knowledge of Ingress Controllers.
• An NGINX Ingress Controller installation on the same host as an existing Ingress-NGINX Controller.

There are two primary paths for migrating between the community Ingress-NGINX Controller to NGINX Ingress Controller:

• Using NGINX Ingress Resources
• Using Kubernetes Ingress Resources.

Migration with NGINX Ingress resources

This path uses Kubernetes Ingress Resources to set root permissions, then NGINX Ingress Resources for configuration using custom resource definitions (CRDs):

• VirtualServer and VirtualServerRoute
• TransportServer
• GlobalConfiguration
• Policy

Configuring SSL termination and HTTP path-based routing

The following two code examples correspond to a Kubernetes Ingress Resource and an NGINX VirtualServer Resource. Although the syntax and indentation is different, they accomplish the same basic Ingress functions, used for SSL termination and Layer 7 path-based routing.

Kubernetes Ingress Resource

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx-test
spec:
  tls:
    - hosts:
      - foo.bar.com
      secretName: tls-secret
  rules:
    - host: foo.bar.com
      http:
        paths:
        - path: /login
          backend:
            serviceName: login-svc
            servicePort: 80
        - path: /billing
            serviceName: billing-svc
            servicePort: 80

NGINX VirtualServer Resource

apiVersion: networking.k8s.io/v1
kind: VirtualServer
metadata:
  name: nginx-test
spec:
  host: foo.bar.com
  tls:
    secret: tls-secret
  upstreams:
    - name: login
      service: login-svc
      port: 80
    - name: billing
      service: billing-svc
      port: 80
  routes:
  - path: /login
    action:
      pass: login
  - path: /billing
    action:
      pass: billing

Configuring TCP/UDP load balancing and TLS passthrough

NGINX Ingress Controller exposes TCP and UDP services using TransportServer and GlobalConfiguration resources. These resources provide a broad range of options for TCP/UDP and TLS Passthrough load balancing. By contrast, the community Ingress-NGINX Controller exposes TCP/UDP services by using a Kubernetes ConfigMap object.

Convert Ingress-NGINX Controller annotations to NGINX Ingress resources

Kubernetes deployments often need to extend basic Ingress rules for advanced use cases such as canary and blue-green deployments, traffic throttling, and ingress-egress traffic manipulation. The community Ingress-NGINX Controller implements many of these using Kubernetes annotations with custom Lua extensions.

These custom Lua extensions are intended for specific NGINX Ingress resource definitions and may not be as granular as required for advanced use cases. The following examples show how to convert these annotations into NGINX Ingress Controller Resources.

Canary deployments

Canary and blue-green deployments allow you to push code changes to production environments without disrupting existing users. NGINX Ingress Controller runs them on the data plane: to migrate from the community Ingress-NGINX Controller, you must map the latter’s annotations to VirtualServer and VirtualServerRoute resources.

The Ingress-NGINX Controller evaluates canary annotations in the following order:

1. nginx.ingress.kubernetes.io/canary-by-header
2. nginx.ingress.kubernetes.io/canary-by-cookie
3. nginx.ingress.kubernetes.io/canary-by-weight

For NGINX Ingress Controller to evalute them the same way, they must appear in the same order in the VirtualServer or VirtualServerRoute Manifest.

Ingress-NGINX Controller

nginx.ingress.kubernetes.io/canary: "true"
nginx.ingress.kubernetes.io/canary-by-header: "httpHeader"

NGINX Ingress Controller

matches:
- conditions:
  - header: httpHeader
      value: never
  action:
    pass: echo
  - header: httpHeader
      value: always
  action:
    pass: echo-canary
action:
  pass: echo

Ingress-NGINX Controller

nginx.ingress.kubernetes.io/canary: "true"
nginx.ingress.kubernetes.io/canary-by-header: "httpHeader"
nginx.ingress.kubernetes.io/canary-by-header-value: "my-value"

NGINX Ingress Controller

matches:
- conditions:
  - header: httpHeader
      value: my-value
  action:
    pass: echo-canary
action:
  pass: echo

Ingress-NGINX Controller

nginx.ingress.kubernetes.io/canary: "true"
nginx.ingress.kubernetes.io/canary-by-cookie: "cookieName"

NGINX Ingress Controller

matches:
- conditions:
  - cookie: cookieName
      value: never
  action:
    pass: echo
  - cookie: cookieName
      value: always
  action:
    pass: echo-canary
action:
  pass: echo

Traffic control

Environments using microservices tend to use extensive traffic-control policies to manage ephemeral applications using circuit breaking and rate and connection limiting to prevent error conditions due to unhealthy states or abnormal behavior.

The following examples map Ingress-NGINX Controller annotations to NGINX VirtualServer and VirtualServerRoute resources for rate limiting, custom HTTP errors, custom default backend and URI rewriting.

Ingress-NGINX Controller

nginx.ingress.kubernetes.io/custom-http-errors: "code"

nginx.ingress.kubernetes.io/default-backend: "default-svc"

NGINX Ingress Controller

errorPages:
- codes: [code]
    redirect:
      code: 301
      url: default-svc

Ingress-NGINX Controller

nginx.ingress.kubernetes.io/limit-connections: "number"

NGINX Ingress Controller

http-snippets: |
    limit_conn_zone $binary_remote_addr zone=zone_name:size;    
routes:
- path: /path
    location-snippets: |
      limit_conn zone_name number;      

Ingress-NGINX Controller

nginx.ingress.kubernetes.io/limit-rate: "number"
nginx.ingress.kubernetes.io/limit-rate-after: "number"

NGINX Ingress Controller

location-snippets: |
    limit_rate number;

    limit_rate_after number;    

Ingress-NGINX Controller

nginx.ingress.kubernetes.io/limit-rpm: "number"
nginx.ingress.kubernetes.io/limit-burst-multiplier: "multiplier"

NGINX Ingress Controller

rateLimit:
    rate: numberr/m

    burst: number * multiplier
    key: ${binary_remote_addr}
    zoneSize: size

Ingress-NGINX Controller

nginx.ingress.kubernetes.io/limit-rps: "number"
nginx.ingress.kubernetes.io/limit-burst-multiplier: "multiplier"

NGINX Ingress Controller

rateLimit:
    rate: numberr/s

    burst: number * multiplier
    key: ${binary_remote_addr}
    zoneSize: size

Ingress-NGINX Controller

nginx.ingress.kubernetes.io/limit-whitelist: "CIDR"

NGINX Ingress Controller

http-snippets: |
server-snippets: |

Ingress-NGINX Controller

nginx.ingress.kubernetes.io/rewrite-target: "URI"

NGINX Ingress Controller

rewritePath: "URI"

There are four Ingress-NGINX Controller annotations without NGINX Ingress resource fields yet: they must be handled using snippets.

• nginx.ingress.kubernetes.io/limit-connections
• nginx.ingress.kubernetes.io/limit-rate
• nginx.ingress.kubernetes.io/limit-rate-after
• nginx.ingress.kubernetes.io/limit-whitelist

Header manipulation

Manipulating HTTP headers is useful in many cases, as they contain information that is important and relevant to systems involved in HTTP transactions. The community Ingress-NGINX Controller supports enabling and configuring cross-origin resource sharing (CORS) headings used by AJAX applications, where front-end Javascript code interacts with backend applications or web servers.

These code blocks show how the Ingress-NGINX annotations correspond to NGINX Ingress Controller VirtualServer and VirtualServerRoute resources.

Ingress-NGINX Controller

nginx.ingress.kubernetes.io/enable-cors: "true"
nginx.ingress.kubernetes.io/cors-allow-credentials: "true"

nginx.ingress.kubernetes.io/cors-allow-headers: "X-Forwarded-For"

nginx.ingress.kubernetes.io/cors-allow-methods: "PUT, GET, POST, OPTIONS"

nginx.ingress.kubernetes.io/cors-allow-origin: "*"

nginx.ingress.kubernetes.io/cors-max-age: "seconds"

NGINX Ingress Controller

responseHeaders:
  add:
    - name: Access-Control-Allow-Credentials
      value: "true"
    - name: Access-Control-Allow-Headers
      value: "X-Forwarded-For"
    - name: Access-Control-Allow-Methods
      value: "PUT, GET, POST, OPTIONS"
    - name: Access-Control-Allow-Origin
      value: "*"
    - name: Access-Control-Max-Age
      value: "seconds"

Proxying and load balancing

NGINX Ingress Controller has multiple proxy and load balancing functionalities you may want to configure based on the use case, such as configuring the load balancing algorithm and the timeout and buffering settings for proxied connections.

This table shows how Ingress-NGINX Controller annotations map to statements in the upstream field for VirtualServer and VirtualServerRoute resources, covering load balancing, proxy timeout, proxy buffering and connection routing for a services’ ClusterIP address and port.

mTLS authentication

mTLS authentication is a way of enforcing mutual authentication on traffic entering and exiting a cluster (north-sourth traffic). This secure form of communication is common within a service mesh, commonly used in strict zero-trust environments.

NGINX Ingress Controller layer can handle mTLS authentication for end systems through the presentation of valid certificates for external connections. It accomplishes this through Policy resources, which correspond to Ingress-NGINX Controller annotations for client certificate authentication and backend certificate authentication.

Ingress-NGINX Controller

nginx.ingress.kubernetes.io/auth-tls-secret: secretName
nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"

NGINX Ingress Controller

ingressMTLS:
   clientCertSecret: secretName
   verifyClient: "on"

   verifyDepth: 1

Ingress-NGINX Controller

nginx.ingress.kubernetes.io/proxy-ssl-secret: "secretName"
nginx.ingress.kubernetes.io/proxy-ssl-verify: "on|off"
nginx.ingress.kubernetes.io/proxy-ssl-verify-depth: "1"
nginx.ingress.kubernetes.io/proxy-ssl-protocols: "TLSv1.2"
nginx.ingress.kubernetes.io/proxy-ssl-ciphers: "DEFAULT"
nginx.ingress.kubernetes.io/proxy-ssl-name: "server-name"
nginx.ingress.kubernetes.io/proxy-ssl-server-name: "on|off"

NGINX Ingress Controller

egressMTLS:
   tlsSecret: secretName

   verifyServer: true|false

   verifyDepth: 1

   protocols: TLSv1.2

   ciphers: DEFAULT

   sslName: server-name

   serverName: true|false

Session persistence with NGINX Plus

With NGINX Plus, you can use Policy resources for session persistence, which have corresponding annotations for the community Ingress-NGINX Controller.

Ingress-NGINX Controller

nginx.ingress.kubernetes.io/affinity: "cookie"
nginx.ingress.kubernetes.io/session-cookie-name: "cookieName"
nginx.ingress.kubernetes.io/session-cookie-expires: "x"
nginx.ingress.kubernetes.io/session-cookie-path: "/route"
nginx.ingress.kubernetes.io/session-cookie-secure: "true"

NGINX Ingress Controller

sessionCookie:
  enable: true

  name: cookieName

  expires: xh

  path: /route

  secure: true

Migration with Kubernetes Ingress resources

The other option for migrating from the community Ingress-NGINX Controller to NGINX Ingress Controller is using only annotations and ConfigMaps from standard Kubernetes resources, potentially relying on mergeable Ingress types.

This ensures that all configuration is kept in the Ingress object.

Warning:
You should avoid altering the spec field of the Ingress resource when taking this option. Ingress-NGINX Controller and NGINX Ingress Controller differ slightly in their implementations: changing the Kubernetes Ingress can create incompatibility issues.

Advanced configuration with annotations

This table maps the Ingress-NGINX Controller annotations to NGINX Ingress Controller’s equivalent annotations, and the respective NGINX Directive.

1. Ingress-NGINX Controller implements some of its load balancing algorithms with Lua, which may not have an equivalent in NGINX Ingress Controller.
2. To redirect HTTP (80) traffic to HTTPS (443), NGINX Ingress Controller uses built-in NGINX if conditions while Ingress-NGINX Controller uses Lua.

The following two snippets outline Ingress-NGINX Controller annotations that correspond to annotations for NGINX Ingress Controller with NGINX Plus.

Ingress-NGINX Controller

nginx.ingress.kubernetes.io/affinity: "cookie"
nginx.ingress.kubernetes.io/session-cookie-name: "cookie_name"
nginx.ingress.kubernetes.io/session-cookie-expires: "seconds"
nginx.ingress.kubernetes.io/session-cookie-path: "/route"

NGINX Ingress Controller (with NGINX Plus)

nginx.com/sticky-cookie-services: "serviceName=example-svc cookie_name expires=time path=/route"

Note:
NGINX Ingress Controller has additional annotations for features using NGINX Plus that have no Ingress-NGINX Controller equivalent, such as active health checks and authentication using JSON Web Tokens (JWTs).

Global configuration with ConfigMaps

This table maps the Ingress-NGINX Controller ConfigMap keys to NGINX Ingress Controller’s equivalent ConfigMap keys.