How to Use Annotations in Kubernetes Ingress for Configuration

In Kubernetes, you add annotations to an Ingress resource under the metadata.annotations field to customize its behavior. These annotations control features like SSL, rewrite rules, and load balancing specific to the Ingress controller you use.

Syntax

An annotation in an Ingress resource is a key-value pair placed under metadata.annotations. The key is usually a domain-style string that identifies the feature, and the value configures that feature.

Example parts:

• metadata.annotations: The section where annotations are defined.
• nginx.ingress.kubernetes.io/rewrite-target: An example annotation key for NGINX Ingress controller.
• /: The value for the annotation, here specifying the rewrite target path.

yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: "/"
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /testpath
        pathType: Prefix
        backend:
          service:
            name: test-service
            port:
              number: 80

Example

This example shows how to use annotations to enable SSL redirect and rewrite the URL path using the NGINX Ingress controller.

yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/rewrite-target: "/"
spec:
  tls:
  - hosts:
    - example.com
    secretName: example-tls
  rules:
  - host: example.com
    http:
      paths:
      - path: /app
        pathType: Prefix
        backend:
          service:
            name: app-service
            port:
              number: 80

Output

Ingress resource created with SSL redirect enabled and URL path rewritten to root for requests to /app.

Common Pitfalls

Common mistakes when using annotations in Ingress include:

• Using annotations not supported by your Ingress controller.
• Incorrect syntax such as missing quotes around boolean values.
• Forgetting to create required TLS secrets when enabling SSL.
• Confusing annotation keys between different Ingress controllers.

Always check your Ingress controller documentation for supported annotations.

yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: bad-ingress
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"  # Corrected to have quotes
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /app
        pathType: Prefix
        backend:
          service:
            name: app-service
            port:
              number: 80

# Corrected version:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: good-ingress
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /app
        pathType: Prefix
        backend:
          service:
            name: app-service
            port:
              number: 80

Quick Reference

Annotation	Purpose	Example Value
nginx.ingress.kubernetes.io/rewrite-target	Rewrite URL path	"/"
nginx.ingress.kubernetes.io/ssl-redirect	Enable SSL redirect	"true"
nginx.ingress.kubernetes.io/proxy-body-size	Set max body size	"8m"
nginx.ingress.kubernetes.io/whitelist-source-range	Allow IP ranges	"192.168.1.0/24"
kubernetes.io/ingress.class	Specify Ingress controller	"nginx"

Key Takeaways

Annotations in Ingress are key-value pairs under metadata.annotations that customize behavior.

Always use quotes around boolean annotation values like "true" or "false".

Check your Ingress controller docs for supported annotations and syntax.

Annotations control features like SSL redirect, URL rewrites, and load balancing.

Incorrect or unsupported annotations can cause Ingress to not work as expected.