Skip to content

Migrating ingress annotations

Most annotations used on Ingress resources are specific to the Ingress controller being used. During the migration from ingress-nginx to the HAProxy ingress controller, you will need to review the annotations used in your Ingress resources. This page documents the annotations found across our Kubernetes clusters and possible migration paths.

Annotations you have to check are prefixed with nginx.ingress.kubernetes.io/.

affinity

Session affinity (sticky sessions) is used to bind a user to a specific backend.

HAProxy supports cookie based session affinity using haproxy.org/cookie-persistence.
Note: This should be defined on the Service resource instead of the Ingress resource.

affinity-mode

The affinity-mode annotation specifies whether sticky sessions remain if a backend goes down.

If you used to configure nginx.ingress.kubernetes.io/affinity-mode: persistent, you should use haproxy.org/cookie-persistence-no-dynamic instead of the haproxy.org/cookie-persistence shown above.
Note: This should be defined on the Service resource instead of the Ingress resource.

app-root

The app-root annotation was used for applications that expected to be served on a subpath like /app instead of /.

There is no drop-in replacement: use the generic haproxy.org/path-rewrite instead.

auth-realm

Replace with haproxy.org/auth-realm.

Also see auth-type.

auth-secret

Replace with haproxy.org/auth-secret.

Note that HAProxy ingress controller only supports .htaccess style credentials. If you also used nginx.ingress.kubernetes.io/auth-secret-type, you will need to convert your credentials to the supported format.

auth-tls-secret

Not supported in HAProxy ingress.

auth-tls-verify-client

Not supported in HAProxy ingress.

auth-type

Replace with haproxy.org/auth-type: basic-auth.

Note that HAProxy only supports Basic Authentication.

auth-url

External authentication is not supported in HAProxy ingress. Move this functionality to your application or deploy an intermediary NGINX proxy.

backend-protocol

If this was set to HTTPS, you should use haproxy.org/server-ssl instead.

client-body-buffer-size

The body buffer size is configured globally. If you need to increase it, contact support.

configuration-snippet

Global configuration snippets are not supported in HAProxy ingress.

You may be able to replace some configs using haproxy.org/backend-config-snippet.

connection-proxy-header

The Connection: header in proxied requests can't be modified in HAProxy ingress.

cors-allow-credentials

Switch to haproxy.org/cors-allow-credentials.

cors-allow-methods

Switch to haproxy.org/cors-allow-methods.

default-backend

HAProxy doesn't support per-ingress default backends.

denylist-source-range

Switch to haproxy.org/deny-list.

enable-cors

Switch to haproxy.org/cors-enable.

force-ssl-redirect

HAProxy redirects to HTTPS by default when a TLS certificate is configured.

You can drop this annotation unless you want to explicitly disable SSL redirection with haproxy.org/ssl-redirect: "false".

from-to-www-redirect

If you want to handle specific subdomains differently (including www), create a separate Ingress resource for them.

See also haproxy.org/request-redirect.

limit-rps

Migrate to haproxy.org/rate-limit-requests and haproxy.org/rate-limit-period.

permanent-redirect

Migrate to haproxy.org/request-redirect and haproxy.org/request-redirect-code.

proxy-body-size

HAProxy does not limit body size for proxied requests.

proxy-buffer-size

It's not possible to configure buffer sizes using annotations. Contact support if this causes issues.

proxy-buffers-number

It's not possible to configure buffer sizes using annotations. Contact support if this causes issues.

proxy-busy-buffers-size

It's not possible to configure buffer sizes using annotations. Contact support if this causes issues.

proxy-connect-timeout

Switch to haproxy.org/timeout-server.

proxy-http-version

Switch to haproxy.org/server-proto.

proxy-max-temp-file-size

HAProxy doesn't use temporary files, this setting is not needed anymore.

proxy-next-upstream-timeout

This setting can't be modified using annotations.

proxy-read-timeout

All timeouts are configured using haproxy.org/timeout-server.

proxy-send-timeout

All timeouts are configured using haproxy.org/timeout-server.

proxy-ssl-verify

Client certificate verification can be configured using the haproxy.org/server-ca annotation.

rewrite-target

Migrate to haproxy.org/path-rewrite.

satisfy

Not supported in HAProxy ingress.

server-alias

HAProxy doesn't support server aliases. Create separate rules for each hostname instead.

server-snippet

Migrate to haproxy.org/backend-config-snippet.

Note that HAProxy does not support NGINX configuration, you will need to rewrite your snippets in HAProxy syntax.

HAProxy doesn't use a separate annotation for the session cookie name.

Provide the cookie name to the haproxy.org/cookie-persistence annotation instead.
Note: This should be defined on the Service resource instead of the Ingress resource.

ssl-passthrough

Switch to haproxy.org/ssl-passthrough.

ssl-redirect

Switch to haproxy.org/ssl-redirect.

use-regex

HAProxy path rewrites use regex by default, this annotation is no longer needed.

whitelist-source-range

Switch to haproxy.org/allow-list.