higress/.claude/skills/nginx-to-higress-migration/references/annotation-mapping.md

Nginx to Higress Annotation Compatibility

⚠️ Important: Do NOT Modify Your Ingress Resources!

Higress natively supports nginx.ingress.kubernetes.io/* annotations - no conversion or modification needed!

The Higress controller uses ParseStringASAP() which first tries nginx.ingress.kubernetes.io/* prefix, then falls back to higress.io/*. Your existing Ingress resources work as-is with Higress.

Fully Compatible Annotations (Work As-Is)

These nginx annotations work directly with Higress without any changes:

nginx annotation (keep as-is)	Higress also accepts	Notes
nginx.ingress.kubernetes.io/rewrite-target	higress.io/rewrite-target	Supports capture groups
nginx.ingress.kubernetes.io/use-regex	higress.io/use-regex	Enable regex path matching
nginx.ingress.kubernetes.io/ssl-redirect	higress.io/ssl-redirect	Force HTTPS
nginx.ingress.kubernetes.io/force-ssl-redirect	higress.io/force-ssl-redirect	Same behavior
nginx.ingress.kubernetes.io/backend-protocol	higress.io/backend-protocol	HTTP/HTTPS/GRPC
nginx.ingress.kubernetes.io/proxy-body-size	higress.io/proxy-body-size	Max body size

CORS

nginx annotation	Higress annotation
nginx.ingress.kubernetes.io/enable-cors	higress.io/enable-cors
nginx.ingress.kubernetes.io/cors-allow-origin	higress.io/cors-allow-origin
nginx.ingress.kubernetes.io/cors-allow-methods	higress.io/cors-allow-methods
nginx.ingress.kubernetes.io/cors-allow-headers	higress.io/cors-allow-headers
nginx.ingress.kubernetes.io/cors-expose-headers	higress.io/cors-expose-headers
nginx.ingress.kubernetes.io/cors-allow-credentials	higress.io/cors-allow-credentials
nginx.ingress.kubernetes.io/cors-max-age	higress.io/cors-max-age

Timeout & Retry

nginx annotation	Higress annotation
nginx.ingress.kubernetes.io/proxy-connect-timeout	higress.io/proxy-connect-timeout
nginx.ingress.kubernetes.io/proxy-send-timeout	higress.io/proxy-send-timeout
nginx.ingress.kubernetes.io/proxy-read-timeout	higress.io/proxy-read-timeout
nginx.ingress.kubernetes.io/proxy-next-upstream-tries	higress.io/proxy-next-upstream-tries

Canary (Grayscale)

nginx annotation	Higress annotation
nginx.ingress.kubernetes.io/canary	higress.io/canary
nginx.ingress.kubernetes.io/canary-weight	higress.io/canary-weight
nginx.ingress.kubernetes.io/canary-header	higress.io/canary-header
nginx.ingress.kubernetes.io/canary-header-value	higress.io/canary-header-value
nginx.ingress.kubernetes.io/canary-header-pattern	higress.io/canary-header-pattern
nginx.ingress.kubernetes.io/canary-by-cookie	higress.io/canary-by-cookie

Authentication

nginx annotation	Higress annotation
nginx.ingress.kubernetes.io/auth-type	higress.io/auth-type
nginx.ingress.kubernetes.io/auth-secret	higress.io/auth-secret
nginx.ingress.kubernetes.io/auth-realm	higress.io/auth-realm

Load Balancing

nginx annotation	Higress annotation
nginx.ingress.kubernetes.io/load-balance	higress.io/load-balance
nginx.ingress.kubernetes.io/upstream-hash-by	higress.io/upstream-hash-by

IP Access Control

nginx annotation	Higress annotation
nginx.ingress.kubernetes.io/whitelist-source-range	higress.io/whitelist-source-range
nginx.ingress.kubernetes.io/denylist-source-range	higress.io/denylist-source-range

Redirect

nginx annotation	Higress annotation
nginx.ingress.kubernetes.io/permanent-redirect	higress.io/permanent-redirect
nginx.ingress.kubernetes.io/temporal-redirect	higress.io/temporal-redirect
nginx.ingress.kubernetes.io/permanent-redirect-code	higress.io/permanent-redirect-code

Header Control

nginx annotation	Higress annotation
nginx.ingress.kubernetes.io/proxy-set-headers	higress.io/proxy-set-headers
nginx.ingress.kubernetes.io/proxy-hide-headers	higress.io/proxy-hide-headers
nginx.ingress.kubernetes.io/proxy-pass-headers	higress.io/proxy-pass-headers

Upstream TLS

nginx annotation	Higress annotation
nginx.ingress.kubernetes.io/proxy-ssl-secret	higress.io/proxy-ssl-secret
nginx.ingress.kubernetes.io/proxy-ssl-verify	higress.io/proxy-ssl-verify

TLS Protocol & Cipher Control

Higress provides fine-grained TLS control via dedicated annotations:

nginx annotation	Higress annotation	Notes
nginx.ingress.kubernetes.io/ssl-protocols	(see below)	Use Higress-specific annotations

Higress TLS annotations (no nginx equivalent - use these directly):

Higress annotation	Description	Example value
higress.io/tls-min-protocol-version	Minimum TLS version	TLSv1.2
higress.io/tls-max-protocol-version	Maximum TLS version	TLSv1.3
higress.io/ssl-cipher	Allowed cipher suites	ECDHE-RSA-AES128-GCM-SHA256

Example: Restrict to TLS 1.2+

# nginx (using ssl-protocols)
annotations:
  nginx.ingress.kubernetes.io/ssl-protocols: "TLSv1.2 TLSv1.3"

# Higress (use dedicated annotations)
annotations:
  higress.io/tls-min-protocol-version: "TLSv1.2"
  higress.io/tls-max-protocol-version: "TLSv1.3"

Example: Custom cipher suites

annotations:
  higress.io/ssl-cipher: "ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384"

Unsupported Annotations (Require WASM Plugin)

These annotations have no direct Higress equivalent and require custom WASM plugins:

Configuration Snippets

# NOT supported - requires WASM plugin
nginx.ingress.kubernetes.io/server-snippet: |
  location /custom { ... }
nginx.ingress.kubernetes.io/configuration-snippet: |
  more_set_headers "X-Custom: value";
nginx.ingress.kubernetes.io/stream-snippet: |
  # TCP/UDP snippets

Lua Scripting

# NOT supported - convert to WASM plugin
nginx.ingress.kubernetes.io/lua-resty-waf: "active"
nginx.ingress.kubernetes.io/lua-resty-waf-score-threshold: "10"

ModSecurity

# NOT supported - use Higress WAF plugin or custom WASM
nginx.ingress.kubernetes.io/enable-modsecurity: "true"
nginx.ingress.kubernetes.io/modsecurity-snippet: |
  SecRule ...

Rate Limiting (Complex)

# Basic rate limiting supported via plugin
# Complex Lua-based rate limiting requires WASM
nginx.ingress.kubernetes.io/limit-rps: "10"
nginx.ingress.kubernetes.io/limit-connections: "5"

Other Unsupported

# NOT directly supported
nginx.ingress.kubernetes.io/client-body-buffer-size
nginx.ingress.kubernetes.io/proxy-buffering
nginx.ingress.kubernetes.io/proxy-buffers-number
nginx.ingress.kubernetes.io/proxy-buffer-size
nginx.ingress.kubernetes.io/mirror-uri
nginx.ingress.kubernetes.io/mirror-request-body
nginx.ingress.kubernetes.io/grpc-backend
nginx.ingress.kubernetes.io/custom-http-errors
nginx.ingress.kubernetes.io/default-backend

Migration Script

Use this script to analyze Ingress annotations:

# scripts/analyze-ingress.sh in this skill
./scripts/analyze-ingress.sh <namespace>