Nginx Ingress

Dieser Artikel beschreibt den veralteten Nginx Ingress-Controller und wie du von ihm auf den HAProxy Ingress-Controller migrierst.

warnung

Der Nginx Ingress-Controller ist veraltet. Seit dem 1. Oktober 2026 bietet Nine für Nginx Ingress-Controller weder Support noch Monitoring an. Migriere deine Ingress-Ressourcen auf den HAProxy Ingress-Controller. Folge dazu der Migrationsanleitung.

IngressClass

Um den veralteten Nginx Ingress-Controller zu nutzen, setze das Feld ingressClassName in der Ingress Ressource auf die konfigurierte Ingress Klasse, also jene, die beim Deployen des Controllers gesetzt wurde.

Access Logs

Die Nginx Ingress Logs sind unter dem Loki Label app="ingress-nginx" verfügbar. Beispiel Query:

{app="ingress-nginx",ingress="shop-prod-frontend-80"}

Spezifische Features

Alle verfügbaren Annotations sind in der offiziellen Nginx Ingress-Controller Dokumentation zu finden.

Basic Authentifizierung

kubectl --namespace=$INGRESS_NAMESPACE annotate ingress $INGRESS nginx.ingress.kubernetes.io/auth-type=basic
kubectl --namespace=$INGRESS_NAMESPACE annotate ingress $INGRESS nginx.ingress.kubernetes.io/auth-secret=$SECRET_NAMESPACE/basic-auth-secret
kubectl --namespace=$INGRESS_NAMESPACE annotate ingress $INGRESS nginx.ingress.kubernetes.io/auth-realm='Authentication required'

Rate limiting

Alle verfügbaren Optionen findest du in der offiziellen Dokumentation.

Temporäre und permanente Weiterleitungen

# Temporäre Weiterleitung (HTTP 302)
nginx.ingress.kubernetes.io/temporal-redirect: <DEINE URL>
# Permanente Weiterleitung (HTTP 301)
nginx.ingress.kubernetes.io/permanent-redirect: <DEINE URL>

HTTPS Weiterleitung

nginx.ingress.kubernetes.io/ssl-redirect: "false"

IP whitelisting

nginx.ingress.kubernetes.io/whitelist-source-range: <DEINE CIDR BLÖCKE>

Caching

Der Nginx Ingress-Controller unterstützt eine einfache Form von Content Caching, welche nützlich sein kann, um zum Beispiel statischen Inhalt schneller auszuliefern. Du kannst das Caching pro Ingress-Ressource aktivieren, indem du folgende Annotations in deiner Ingress Definition setzen (unter metadata.annotations):

nginx.ingress.kubernetes.io/proxy-buffering: "on"
nginx.ingress.kubernetes.io/configuration-snippet: |
  proxy_cache static-cache;
  proxy_cache_valid 10m;
  proxy_cache_use_stale error timeout updating http_404 http_500 http_502 http_503 http_504;
  proxy_cache_bypass $http_x_purge;
  add_header X-Cache-Status $upstream_cache_status;

In diesem Beispiel werden die Antworten mit den Status Codes 200, 301 und 302 für 10 Minuten gecached. Falls ein anderes Verhalten gewünscht sein sollte, kann die proxy_cache_valid Option auch mit Status Code vor der Zeit gesetzt werden:

proxy_cache_valid 404 1m;

Diese Option cached 404 Antworten für eine Minute. Ausserdem hast du die Möglichkeit, den Spezialcode "any" zu nutzen, welcher alle Antworten cached. Weiterhin können mehrere proxy_cache_valid Optionen kombiniert werden, um verschiedene Cache-Zeiten für verschiedene Status Codes zu definieren.

Standardmässig ist die Cache-Grösse 100 MB. Solltest du davon abweichende Anforderungen haben, kontaktiere uns gerne.

Um zu überprüfen, ob das Caching funktioniert, kann cURL verwendet werden. Führe den folgenden Befehl zweimal aus, um im zweiten Output den Cache-Status zu kontrollieren:

curl --head <URL>

Dies sollte den HTTP-Header x-cache-status: HIT anzeigen.

Falls du Caching nur für einen ausgewählten Unterpfad nutzen möchtest (zum Beispiel ein Endpunkt unter /static), muss dazu eine separate Ingress Ressource erstellt werden. Das Caching kann weiter konfiguriert werden über die proxy_cache Optionen, welche innerhalb von location Blöcken gültig sind. Weitere Informationen zu verfügbaren Optionen findest du in der nginx proxy_cache Modul-Dokumentation.

Eigenes Standard-Backend

Falls der Nginx Ingress-Controller Anfragen erhält, welche nicht durch Regeln in den Ingress-Ressourcen abgedeckt sind, so beantwortet er diese mit einer HTTP 404 Fehler-Seite, die vom Standard-Backend bereitgestellt wird. Du kannst ein eigenes Standard-Backend (+ Kubernetes-Services) zur Verfügung stellen und anschliessend in der Ingress-Ressource auf das eigene Standard-Backend verweisen.

Das Standard-Backend muss lediglich 2 Bedingungen erfüllen:

• es muss eine 404 Fehler-Seite (bzw. einen 404 HTTP Fehler Code) auf dem "/" Pfad ausliefern
• es muss auf dem Pfad "/healthz" mit dem HTTP Code 200 antworten

Die Implementation des Standard-Backends, welches mit dem Nginx Ingress Controller ausgeliefert wird, findest du im ingress-gce 404-Server Quellcode. Dies kann als Beispiel für eigene Implementationen genutzt werden.

Sobald du ein eigenes Standard-Backend im gleichen Namespace wie die Ingress Ressource zur Verfügung gestellt hast, kannst du mit folgender Annotation in der Ingress-Ressource darauf verweisen:

nginx.ingress.kubernetes.io/default-backend: <SERVICE NAME OF YOUR DEFAULT BACKEND>

Zusätzliche benutzerdefinierte Fehler-Seiten

Um noch weitere benutzerdefinierte Fehler-Seiten auf dem Standard-Backend anzeigen zu lassen (bspw. eine benutzerdefinierte Seite, falls die Applikation, auf welche der Ingress zeigt, nicht verfügbar ist), kann die folgende zusätzliche Annotation verwendet werden:

nginx.ingress.kubernetes.io/custom-http-errors: <ERROR CODES> # for example: "404,415,503"

Der Nginx Ingress-Controller leitet Fehlerinformationen über HTTP Header zum Standard-Backend weiter. Die dort laufende Applikation kann anhand dieser Header spezielle Webseiten ausliefern, welche den aufgetretenen Fehler am besten darstellen. Mehr Informationen zu diesem Feature findest du in der offiziellen Dokumentation. Eine Beispielapplikation, welche die HTTP Header Informationen auswertet und benutzerdefinierte Fehler-Seiten anzeigt, findest du im ingress-nginx custom-error-pages Repository. Diese kann auch als Inspiration für eigene Implementationen dienen.

Von Nginx zu HAProxy migrieren

Du kannst den Nginx- und den HAProxy Ingress-Controller parallel betreiben. So kannst du eine Ingress-Ressource nach der anderen migrieren und jede Applikation auf HAProxy verifizieren, bevor du Produktiv-Traffic darauf leitest. Ein Wartungsfenster ist daher nicht notwendig.

Die Migration erfolgt pro Ingress: Für jede Nginx-Ingress-Ressource fügst du eine entsprechende HAProxy-Ingress hinzu, verifizierst sie, stellst das DNS um und entfernst danach die alte Ressource.

Annotations von Nginx migrieren

Falls deine Ingress-Ressourcen nginx-spezifische Annotations verwenden, musst du diese auf ihre HAProxy-Entsprechungen umstellen. Hier die häufigsten:

Nginx Annotation	HAProxy Annotation
nginx.ingress.kubernetes.io/ssl-redirect	haproxy-ingress.github.io/ssl-redirect
nginx.ingress.kubernetes.io/auth-secret	haproxy-ingress.github.io/auth-secret
nginx.ingress.kubernetes.io/auth-realm	haproxy-ingress.github.io/auth-realm
nginx.ingress.kubernetes.io/whitelist-source-range	haproxy-ingress.github.io/allowlist-source-range
nginx.ingress.kubernetes.io/temporal-redirect	haproxy-ingress.github.io/redirect-to (Standard-Statuscode 302)
nginx.ingress.kubernetes.io/permanent-redirect	haproxy-ingress.github.io/redirect-to + haproxy-ingress.github.io/redirect-to-code: "301"
nginx.ingress.kubernetes.io/limit-rps	haproxy-ingress.github.io/limit-rps

Terminiert der Ingress TLS mit einem Cert-manager-Zertifikat, füge zusätzlich acme.cert-manager.io/http01-ingress-ingressclassname: haproxy hinzu, damit die ACME-HTTP-01-Challenge über den HAProxy-Ingress und nicht über die Standard-Ingress-Klasse des Clusters gelöst wird. Siehe Automatische TLS-Zertifikate.

1. Deploye den HAProxy Ingress-Controller für deinen Cluster im Cockpit. Notiere dir den Namen seiner Ingress-Klasse (standardmässig haproxy) sowie seinen Ingress DNS-Namen, beide findest du in der HAProxy-Ingress-Ansicht. Siehe Verfügbarkeit.

2. Füge eine zweite Ingress-Ressource für deine Applikation hinzu, die die HAProxy-Ingress-Klasse und die entsprechenden HAProxy-Annotations verwendet, und lass die bestehende Nginx-Ingress vorerst bestehen. Die Zuordnung der Annotations findest du unter Annotations von Nginx migrieren.

   Um die noch zu migrierenden Ingress-Ressourcen zu finden, liste sie über alle Namespaces auf. Die Spalte CLASS zeigt, welchen Controller die jeweilige Ressource verwendet:

   kubectl get ingress --all-namespaces

   Aus diesem Nginx-Ingress:

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

   wird ein HAProxy-Gegenstück mit umgestelltem ingressClassName und umgestellten Annotations. Während des Tests kannst du es auf einen Hostnamen unter dem HAProxy-Wildcard DNS-Namen zeigen lassen, damit du dein Produktiv-DNS noch nicht anpassen musst:

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: hello-haproxy
     annotations:
       haproxy-ingress.github.io/ssl-redirect: "true"
   spec:
     ingressClassName: haproxy
     rules:
       # ein Test-Hostname unter dem HAProxy-Wildcard-DNS-Namen
       - host: hello.<haproxy-ingress-dns-name>
         http:
           paths:
             - path: /
               pathType: Prefix
               backend:
                 service:
                   name: hello
                   port:
                     number: 80

3. Verifiziere, dass deine Applikation über den HAProxy-Ingress unter dem Test-Hostnamen erreichbar ist:

   curl http://hello.<haproxy-ingress-dns-name>/

4. Stelle deine DNS-Einträge auf den HAProxy-Ingress um. Passe den CNAME- oder Alias-Eintrag deiner Domain so an, dass er auf den HAProxy Ingress DNS-Namen statt auf den von Nginx zeigt. Danach kannst du den Test-Hostnamen im HAProxy-Ingress durch deinen Produktiv-Hostnamen ersetzen. Siehe Ingress DNS Name.

5. Entferne die alte Nginx-Ingress-Ressource, sobald der gesamte Traffic über HAProxy läuft:

   kubectl --namespace=<namespace> delete ingress <nginx-ingress-name>

6. Entferne den alten Nginx Ingress-Controller im Cockpit, sobald keine Ingress-Ressourcen mehr seine Ingress-Klasse verwenden. Falls der Nginx-Controller die Standard-Ingress-Klasse deines Clusters war, setze den HAProxy-Controller im Cockpit als neuen Standard, damit Ingresses ohne explizites ingressClassName weiterhin funktionieren.