Ingress annotations for customization in Kubernetes - Commands & Configuration

Introduction

Ingress annotations let you add extra settings to control how your Kubernetes Ingress works. They help customize behavior like SSL, timeouts, or redirects without changing the main Ingress rules.

When you want to enable HTTPS with automatic redirects on your web app.

When you need to set a timeout for backend requests to avoid hanging connections.

When you want to add custom headers to requests or responses for security or tracking.

When you want to control load balancing behavior like session affinity.

When you want to enable or disable features like WebSocket support or client IP forwarding.

Config File - ingress.yaml

ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "30"
    nginx.ingress.kubernetes.io/configuration-snippet: |
      more_set_headers "X-Custom-Header: myvalue";
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 80
  tls:
  - hosts:
    - example.com
    secretName: example-tls-secret

The annotations section adds extra settings to customize the Ingress controller behavior:

• nginx.ingress.kubernetes.io/ssl-redirect: "true" forces HTTP requests to redirect to HTTPS.
• nginx.ingress.kubernetes.io/proxy-read-timeout: "30" sets the timeout for reading a response from the backend to 30 seconds.
• nginx.ingress.kubernetes.io/configuration-snippet lets you add custom NGINX configuration, here adding a custom header to responses.

The spec defines the routing rules and TLS settings.

Commands

This command creates or updates the Ingress resource with the custom annotations to control SSL redirect, timeout, and add a custom header.

Terminal

kubectl apply -f ingress.yaml

Expected Output

ingress.networking.k8s.io/example-ingress created

This command checks that the Ingress resource is created and shows its basic details like hosts and addresses.

Terminal

kubectl get ingress example-ingress

Expected Output

NAME              CLASS    HOSTS         ADDRESS        PORTS   AGE

example-ingress   <none>   example.com   192.168.1.100  80,443  10s

This command shows detailed information about the Ingress, including the annotations that customize its behavior.

Terminal

kubectl describe ingress example-ingress

Expected Output

Name:             example-ingress

Namespace:        default

Address:          192.168.1.100

Default backend:  <none>

Rules:

  Host        Path  Backends

  ----        ----  --------

  example.com

              /   example-service:80 (10.1.1.5:80)

Annotations:

  nginx.ingress.kubernetes.io/ssl-redirect:        true

  nginx.ingress.kubernetes.io/proxy-read-timeout:  30

  nginx.ingress.kubernetes.io/configuration-snippet:

    more_set_headers "X-Custom-Header: myvalue";

Events:  <none>

Key Concept

If you remember nothing else from this pattern, remember: Ingress annotations let you easily add or change features like SSL redirects and timeouts without changing your main routing rules.

Common Mistakes

Using incorrect annotation keys or typos in annotation names

The Ingress controller ignores unknown annotations, so your customization won't apply.

Always check the official Ingress controller documentation for exact annotation names and spelling.

Not quoting numeric annotation values like timeouts

Annotations are strings; missing quotes can cause parsing errors or ignored settings.

Always put numeric values in quotes, e.g., "30" for timeouts.

Adding annotations that are not supported by your Ingress controller

Different Ingress controllers support different annotations; unsupported ones have no effect.

Verify your Ingress controller type (e.g., NGINX, Traefik) and use only supported annotations.

Summary

Create an Ingress resource with annotations to customize behavior like SSL redirect and timeouts.

Apply the Ingress YAML file using kubectl to create or update the resource.

Verify the Ingress and its annotations with kubectl get and kubectl describe commands.