Moving from Ingress-NGINX to Traefik on IBM Cloud
IBM Cloud Kubernetes Service is moving away from Ingress-NGINX because the upstream project is retired. Traefik is the Ingress controller that IBM supports going forward.
During the transition period, both Ingress controllers are available, giving you the flexibility to test Traefik and migrate at your own pace.
This topic compares key configuration differences between Ingress-NGINX and Traefik and provides guidance for your transition.
Comparing Ingress-NGINX to Traefik on IBM Cloud
The following table compares high-level differences between Ingress-NGINX and Traefik.
| Ingress-NGINX | Traefik | |
|---|---|---|
| IBM-provided default Ingress classes | public-iks-k8s-nginx for public and private-iks-k8s-nginx for private. |
public-iks-traefik for public and private-iks-traefik for private. |
| Version scheme | 0.X.X_XXXX_iks and 1.X.X_XXXX_iks |
Starting with Traefik version 3: 3.X.X_XXXX_iks |
| Processed resources | Ingress only | Ingress with optional Ingress-NGINX compatibility and Traefik CRDs |
| IBM-deployed service account name | ibm-k8s-ingress |
ibm-traefik-ingress |
The following table compares how you configure common features in Ingress-NGINX and Traefik.
| Configuration | Ingress-NGINX | Traefik |
|---|---|---|
| App ID authentication | Add nginx.ingress.kubernetes.io/auth-url and related snippet annotations to the Ingress resource. See Ingress-NGINX docs. |
Create a Traefik ForwardAuth Middleware CRD and apply it via the traefik.ingress.kubernetes.io/router.middlewares annotation. See Traefik docs. |
| Maximum client request body size | Use the nginx.ingress.kubernetes.io/proxy-body-size annotation. See Ingress-NGINX docs. |
Create a Traefik Buffering Middleware CRD and apply it to the Ingress resource. See Traefik docs. |
| Client response data buffering | Use the nginx.ingress.kubernetes.io/proxy-buffering annotation. See Ingress-NGINX docs. |
Create a Traefik Buffering Middleware CRD and apply it to the Ingress resource. See Traefik docs. |
| Connect and read timeouts | Use nginx.ingress.kubernetes.io/proxy-connect-timeout and proxy-read-timeout annotations. See Ingress-NGINX docs. |
Configure read/write/idle timeouts in the ibm-ingress-deploy-config ConfigMap, and use a ServersTransport CRD for backend forwarding timeouts. See Traefik docs. |
| Custom error actions | Set the custom-http-errors field in the ibm-k8s-controller-config ConfigMap. See Ingress-NGINX docs. |
Create a Traefik Errors Middleware CRD and apply it to the Ingress resource. See Traefik docs. |
| Customizing request headers | Set the proxy-set-headers field in the ibm-k8s-controller-config ConfigMap. See Ingress-NGINX docs. |
Create a Traefik Headers Middleware CRD and apply it to the Ingress resource. See Traefik docs. |
| Customizing response headers | Use the nginx.ingress.kubernetes.io/configuration-snippet annotation. See Ingress-NGINX docs. |
Create a Traefik Headers Middleware CRD and apply it to the Ingress resource. See Traefik docs. |
| HTTP to HTTPS redirect | Set ssl-redirect in the ibm-k8s-controller-config ConfigMap or use the nginx.ingress.kubernetes.io/ssl-redirect annotation. See Ingress-NGINX docs. |
Set the httpsRedirect field in the ibm-ingress-deploy-config ConfigMap. See Traefik docs. |
| HTTP Strict Transport Security (HSTS) | Set the hsts field in the ibm-k8s-controller-config ConfigMap. See Ingress-NGINX docs. |
Create a Traefik Headers Middleware CRD with the stsSeconds and related fields and apply it to the Ingress resource. See Traefik docs. |
| URI path matching (regex) | Use the nginx.ingress.kubernetes.io/use-regex annotation. See Ingress-NGINX docs. |
Use the traefik.ingress.kubernetes.io/router.pathmatcher annotation. See Traefik docs. |
| Mutual TLS authentication | Use nginx.ingress.kubernetes.io/auth-tls-* annotations on the Ingress resource. See Ingress-NGINX docs. |
Create a Traefik TLSOption CRD and apply it via the traefik.ingress.kubernetes.io/router.tls.options annotation. See Traefik docs. |
| Retry / next upstream | Use nginx.ingress.kubernetes.io/proxy-next-upstream and related annotations. See Ingress-NGINX docs. |
Create a Traefik Retry Middleware CRD and apply it to the Ingress resource. See Traefik docs. |
| Rate limiting | Use nginx.ingress.kubernetes.io/limit-* annotations on the Ingress resource. See Ingress-NGINX docs. |
Create a Traefik RateLimit Middleware CRD and apply it to the Ingress resource. See Traefik docs. |
| Path rewriting | Use the nginx.ingress.kubernetes.io/rewrite-target annotation. See Ingress-NGINX docs. |
Create a Traefik ReplacePath or ReplacePathRegex Middleware CRD and apply it to the Ingress resource. See Traefik docs. |
| Session affinity (sticky cookies) | Use nginx.ingress.kubernetes.io/affinity and related annotations. See Ingress-NGINX docs. |
Use Traefik Service sticky cookie annotations directly on the Ingress resource. See Traefik docs. |
| Upstream TLS (SSL services) | Use nginx.ingress.kubernetes.io/backend-protocol and proxy-ssl-* annotations. See Ingress-NGINX docs. |
Create a Traefik ServersTransport CRD with the rootCAs field and apply it to the backend Service. See Traefik docs. |
| SSL protocols and ciphers | Set ssl-protocols and ssl-ciphers fields in the ibm-k8s-controller-config ConfigMap. See Ingress-NGINX docs. |
Create a Traefik TLSOption CRD with minVersion, maxVersion, and cipherSuites fields. See Traefik docs. |
If a feature depends on Traefik CRDs, such as Middleware, TLSOption, or ServersTransport, ensure that CRD processing is enabled. CRD processing is enabled by default. To configure CRD processing, see the
processTraefikCRDs field in the ibm-ingress-deploy-config ConfigMap in Creating custom settings in the Ingress ConfigMap.
The following table lists the customizable deployment parameters that Ingress-NGINX and Traefik support.
| Ingress-NGINX | Traefik | |
|---|---|---|
replicas |
Supported | Supported |
ingressClass |
Supported | Supported |
httpPort, httpsPort |
Supported | Supported |
tcpServicesConfig |
Supported | Not applicable. Use the IngressRouteTCP CRD. |
enableSslPassthrough |
Supported | Not applicable. You do not need to enable this setting explicitly. |
defaultCertificate |
Supported | Not applicable. Use the TLSStore CRD with defaultCertificate. |
defaultBackendService |
Supported | Not applicable. Use Global Default Backend Ingress. |
deepInspect |
Supported | Not applicable |
defaultConfig |
Supported | Not applicable |
enableAnnotationValidation |
Supported | Not applicable. Traefik is not prone to configuration injection from annotations. |
enableIngressValidation |
Supported | Not applicable |
logLevel |
Supported as a number from 0 - 5 for verbosity. | Supported as a string with the following values: TRACE, DEBUG, INFO, WARN, ERROR, FATAL, PANIC. |
ingressProvider |
Not applicable | Supported |
processTraefikCRDs |
Not applicable | Supported |
traefikIngressNginxAllowExternalNameServices |
Not applicable | Supported |
traefikCRDAllowCrossNamespace |
Not applicable | Supported |
traefikCRDAllowExternalNameServices |
Not applicable | Supported |
httpReadTimeout, httpsReadTimeout |
Not applicable. Configure through the ibm-k8s-controller-config ConfigMap. |
Supported |
httpWriteTimeout, httpsWriteTimeout |
Not applicable. Configure through the ibm-k8s-controller-config ConfigMap. |
Supported |
httpIdleTimeout, httpsIdleTimeout |
Not applicable. Configure through the ibm-k8s-controller-config ConfigMap. |
Supported |
httpsRedirect |
Not applicable. Configure through the ibm-k8s-controller-config ConfigMap or annotation. |
Supported |
tolerations |
Supported | Supported |
Behaviors to consider during migration
The following IBM Cloud mechanisms help prevent service disruption in certain scenarios.
DNS handling on classic clusters
On classic clusters, enabling or disabling public ALB instances automatically adds the IP addresses for these ALBs to the cluster's default domain.
When you enable different types of ALBs (mixing Traefik with Ingress-NGINX), DNS records are not added. This prevents the undesired situation where different ALB types are mixed behind a single domain, which could cause hard-to-debug issues. No new IP addresses are registered while this mixed state persists. IP address removal still functions as before.
When the last instance of the different type is disabled (either Traefik or Ingress-NGINX), the remaining ALBs are automatically re-registered to restore the desired state, where all public ALB instances are registered behind the cluster's default subdomain.
Default Ingress Class handling
The default Ingress Class is reconciled on each ALB enable or disable event. If the default Ingress Class is left on the IBM default setting and is not configured, it is automatically updated.
If the cluster has only Traefik-based ALBs enabled, public-iks-traefik or private-iks-traefik is made the default, depending on whether public-iks-k8s-nginx or private-iks-k8s-nginx was the
previous default. Similarly, if only Ingress-NGINX-based ALBs are enabled on the cluster, the default Ingress Class is changed back to the Ingress-NGINX one.
Custom Ingress Classes are never made the default automatically.
For more information about configuring and customizing Traefik, see About Ingress with Traefik.