Introduction

Ingress annotations in Kubernetes are metadata keys used by a specific ingress controller to customize routing behavior. The critical detail is that these annotations are not universal Kubernetes features: different controllers support different annotation sets, and modern Kubernetes prefers ingressClassName over the older kubernetes.io/ingress.class annotation for selecting which controller should handle an Ingress.

Understand What Is Generic and What Is Controller-Specific

The Kubernetes Ingress API defines the core routing rules: hosts, paths, backends, and TLS references. Many operational features, however, are controller-specific and are configured through annotations.

Examples include:

• URL rewrite behavior
• SSL redirect rules
• Proxy body size limits
• Load balancer integration knobs

So when someone says “Ingress annotations,” the first follow-up question should be: which controller are you using?

A Minimal Ingress Example

Here is a basic Ingress using the standard API and an NGINX-specific rewrite annotation.

1apiVersion: networking.k8s.io/v1
2kind: Ingress
3metadata:
4  name: web-ingress
5  annotations:
6    nginx.ingress.kubernetes.io/rewrite-target: /
7spec:
8  ingressClassName: nginx
9  rules:
10    - host: app.example.com
11      http:
12        paths:
13          - path: /app
14            pathType: Prefix
15            backend:
16              service:
17                name: web-service
18                port:
19                  number: 80

The annotation here is meaningful only because an NGINX ingress controller understands it.

Common Annotation Patterns

Controller-specific annotations often fall into a few categories.

Rewriting and Redirects

For NGINX-based controllers, annotations can change the upstream path or enforce HTTPS redirects.

1metadata:
2  annotations:
3    nginx.ingress.kubernetes.io/rewrite-target: /
4    nginx.ingress.kubernetes.io/ssl-redirect: "true"

Timeouts and Request Size

Reverse proxies frequently expose request size and timeout settings through annotations.

metadata:
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "20m"

Cloud-Controller Integration

Some controllers, such as cloud-provider-specific ingress controllers, use annotations for load balancer behavior, certificates, or health check settings. Those keys are completely different from the NGINX examples above.

Service Annotations Are a Different Thing

The title phrase “ingress service annotations” often causes confusion because Services also have annotations, and they solve different problems.

For example:

• Ingress annotations customize ingress-controller behavior
• Service annotations often customize cloud load balancers or service-controller behavior

A Service of type LoadBalancer may use cloud-specific annotations, while an Ingress resource uses controller-specific annotations. They are related operationally, but they are not interchangeable.

ingressClassName Versus the Old Annotation

Older Kubernetes examples often use:

metadata:
  annotations:
    kubernetes.io/ingress.class: nginx

Modern Kubernetes uses:

spec:
  ingressClassName: nginx

The old annotation was widely used, but the Ingress API now has a dedicated field and IngressClass resources for this purpose. New manifests should prefer the field unless you are maintaining an older controller setup.

Annotations should also be treated as operational contracts with a controller version, not as timeless schema. When teams upgrade controllers or switch ingress providers, old annotations may be ignored, renamed, or replaced by first-class fields and policy resources. That makes controller documentation part of the deployment surface, not just optional reading.

Common Pitfalls

A common mistake is copying annotations from an NGINX tutorial into an ALB, GCE, or Traefik environment and expecting them to work. Annotation support depends entirely on the controller.

Another mistake is treating the old kubernetes.io/ingress.class annotation as the main modern way to select a controller. In current Kubernetes, ingressClassName is the clearer and preferred mechanism.

A third mistake is mixing Service annotations and Ingress annotations as if they configure the same object. They target different controllers and different layers of the traffic path.

Summary

• Ingress annotations are controller-specific metadata, not universal Kubernetes behavior.
• Use them to customize features such as rewrites, redirects, and proxy limits when your chosen controller supports them.
• Prefer spec.ingressClassName over the older kubernetes.io/ingress.class annotation in modern manifests.
• Do not confuse Ingress annotations with Service annotations.
• Always read the documentation for the exact ingress controller running in your cluster.