Ingress

Das Ingress System von Kubernetes ist dazu gedacht, externe HTTP oder HTTPS Requests in den Cluster zu leiten. Es besteht dabei aus der Ingress-Ressource selbst und einem sogenannten Ingress-Controller, welcher die notwendige Logik implementiert. Wir bieten den HAProxy Ingress-Controller als Managed Controller an, den du im Cockpit in deinen NKE-Cluster deployen kannst. Die einzelnen Features dieses Controllers können mittels Annotations in der Ingress-Ressource gesteuert werden.

Verfügbarkeit

Der HAProxy Ingress-Controller ist als optionaler Service für NKE verfügbar. Der Controller kann über das Cockpit in einen bestehenden NKE Cluster installiert werden.

warnung

Der Nginx Ingress-Controller ist veraltet und wir stellen den Support und das Monitoring für alle Nginx-Ingresses am 1. Oktober vollständig ein.

Bitte migriere deine Ingress-Ressourcen vor diesem Datum auf den HAProxy Ingress-Controller. Folge dazu der Schritt-für-Schritt-Migrationsanleitung.

Nutzung

Die grundlegende Struktur und Nutzung einer Ingress-Ressource wird in der offiziellen Kubernetes Dokumentation erklärt.

Ingress DNS Name

Wir stellen einen DNS-Eintrag zur Verfügung, welcher immer auf die öffentliche IP deines HAProxy Ingress-Controllers zeigt. Damit kannst du die Hostnames deiner eigenen Domains an den Ingress verweisen. DNS ist bereits konfiguriert und die notwendigen Angaben findest du in der HAProxy Ingress-Ansicht im Cockpit.

Zur Nutzung erstelle einfach in deiner eigenen Domain einen Alias oder CNAME Eintrag, welcher auf den von uns bereitgestellten DNS-Eintrag zeigt.

Wildcard DNS Name

Zusätzlich stellen wir auch einen Wildcard DNS Namen *.<ingress-dns-name> zur Verfügung. Er kann für schnelle Tests einer Applikation während der Entwicklung genutzt werden. Du kannst dazu einen beliebigen Hostnamen aus dem Wildcard-Bereich nehmen und in deiner Ingress-Ressource als Hostname nutzen, um schnell etwas zum Laufen zu bringen, ohne sich um DNS-Einträge kümmern zu müssen.

IngressClass

Um unseren Ingress-Controller zu nutzen, setze das Feld ingressClassName in deiner Ingress Ressource auf die Ingress Klasse deines HAProxy Controllers, welche standardmässig haproxy lautet. Du kannst den Namen der Ingress Klasse beim Deployen des Controllers im Cockpit ändern und ausserdem konfigurieren, ob diese die Standard-Ingress-Klasse des Clusters sein soll. Hast du den Controller als Standardklasse markiert, kannst du das Feld ingressClassName weglassen.

Es ist möglich, mehrere HAProxy Ingress-Controller pro NKE-Cluster zu deployen, jeder mit seiner eigenen Ingress Klasse. Über das Feld ingressClassName wählst du aus, welcher Controller eine bestimmte Ingress-Ressource behandelt.

Der veraltete Nginx Ingress-Controller ist weiterhin verfügbar und verwendet die Ingress Klasse, die beim Deployen konfiguriert wurde. Er wird in einem zukünftigen Release entfernt.

Automatische TLS-Zertifikate

Cert-manager und Let's Encrypt gehören standardmässig vorkonfiguriert zu NKE, sodass ein Ingress mit kostenlosen TLS-Zertifikaten einfach durch das Hinzufügen einer Annotation bewerkstelligt wird.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    # this tells cert-manager to issue a certificate for
    # all hosts specified in the tls section
    kubernetes.io/tls-acme: "true"
  name: hello-ingress
spec:
  ingressClassName: haproxy
  rules:
    - host: app.example.org
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: hello-ingress
                port:
                  number: 80
  tls:
    - hosts:
        - app.example.org
      secretName: hello-ingress

Access Logs

Die Access Logs der Ingress Requests kannst du in Grafana in der Loki Explore-Ansicht anschauen. Die Ingress Logs sind unter dem Label app_kubernetes_io_name="haproxy-ingress" verfügbar. Um die Logs einer spezifischen Ingress-Instanz anzuzeigen, kannst du nach dem zusätzlichen Label ingress filtern. Das Label hat das Schema <namespace>-<ingress-name>-<backend-port>. Hier ein Beispiel Query, um alle Logs vom Ingress frontend mit dem Port 80 im Namespace shop-prod anzuzeigen:

{app_kubernetes_io_name="haproxy-ingress", ingress="shop-prod-frontend-80"}

Zusätzlich können die Ingress Logs nach diesen Labels gefiltert werden:

method die HTTP-Methode des Requests
status den HTTP-Status des Requests

Mehr Informationen zur Benutzung von Loki findest du im spezifischen Support Artikel.

HAProxy Ingress Features

Der HAProxy Ingress-Controller bringt einige Features wie bspw. Rate Limiting, IP Whitelisting, temporäre und permanente Weiterleitungen, etc mit. Alle zur Steuerung dieser Features verfügbaren Konfigurationsschlüssel sind in der offiziellen HAProxy Ingress-Controller Dokumentation zu finden. Du wendest diese Annotations direkt auf dein bereits erstelltes Ingress Objekt an.

Nachfolgend findest du die Dokumentation zu den meistverwendeten Features.

Basic Authentifizierung

Du kannst auf einfache Weise Basic Authentifizierung zu deinen Ingress-Ressourcen hinzufügen. Folge dazu einfach den folgenden Schritten:

Setze ein paar Umgebungsvariablen

USERNAME=<DEIN GEWÜNSCHTER NUTZERNAME>
SECRET_NAMESPACE=<NAMESPACE IN WELCHEM DIE ZUGANGSDATEN ABGELEGT WERDEN SOLLEN>
INGRESS_NAMESPACE=<DER NAME DES NAMESPACES IN DEM SICH DEINE INGRESS RESOURCE BEFINDET>
INGRESS=<DER NAME DEINER INGRESS RESOURCE>

Erstelle ein Kubernetes Secret, welche deine Zugangsdaten beinhaltet. Du benötigst das Tool mkpasswd, welches man bspw. im whois Paket in Debian oder Ubuntu findet. Das Secret muss dabei nicht zwingend im selben Namespace wie die Ingress-Ressource selbst angelegt werden.
```
kubectl create secret generic basic-auth-secret --namespace=$SECRET_NAMESPACE --from-literal=auth=$USERNAME:$(mkpasswd -m sha-512)
```

Konfiguriere die Ingress-Ressource so, dass dein erstelltes Secret genutzt wird

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

Rate Limiting

Es stehen einige Möglichkeiten zur Verfügung, gewisse Rate Limits auf deine Ingress-Ressource anzuwenden. Du kannst Anfragen pro Sekunde mit der haproxy-ingress.github.io/limit-rps Annotation oder gleichzeitige Verbindungen mit der haproxy-ingress.github.io/limit-connections Annotation begrenzen. Alle verfügbaren Optionen findest du in der offiziellen Dokumentation.

Temporäre und permanente Weiterleitungen

Um eine Weiterleitung in deiner Ingress-Ressource einzurichten nutze einfach die folgende Annotation:

haproxy-ingress.github.io/redirect-to: <DEINE URL>

Die Weiterleitung nutzt standardmässig den HTTP Status Code 302 (temporär). Um den Status Code zu ändern, zum Beispiel auf 301 für eine permanente Weiterleitung, verwende:

haproxy-ingress.github.io/redirect-to-code: "301"

HTTPS Weiterleitung

Sobald deine Ingress-Ressource für TLS konfiguriert ist, findet eine automatische Weiterleitung auf die HTTPS URL des Ingress Objektes statt. Möchtest du dies verhindern, so nutze die folgende Annotation:

haproxy-ingress.github.io/ssl-redirect: "false"

IP Whitelisting

Um nur bestimmte IP Bereiche zu erlauben, welche auf deine Ingress-Ressource zugreifen dürfen, kannst du mit Komma getrennte CIDR Blöcke in der folgenden Annotation verwenden:

haproxy-ingress.github.io/allowlist-source-range: <DEINE CIDR BLÖCKE>

Eigenes Standard-Backend

Falls der HAProxy Ingress-Controller Anfragen erhält, welche nicht durch Regeln in den Ingress-Ressourcen abgedeckt sind, so beantwortet er diese mit einer HTTP 404 Fehlerseite, welche vom Standard-Backend bereitgestellt wird. Diese Seite kann den eigenen Bedürfnissen angepasst werden, indem ein eigenes Standard-Backend zur Verfügung gestellt wird. Anschliessend wird in der Ingress-Ressource auf das eigene Standard-Backend verwiesen.

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

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

Sobald man sein eigenes Standard-Backend im selben Namespace wie die Ingress-Ressource zur Verfügung gestellt hat, kann man mit folgender Annotation in der Ingress-Ressource darauf verweisen:

haproxy-ingress.github.io/default-backend: <SERVICE NAME DES STANDARD BACKENDS>

Statische IPs für Ingress und Egress

Die IP eines jeden Ingress-Controllers ist statisch. Alle Ingress-Ressourcen die diesen Controller verwenden, teilen sich diese statische IP. Jedoch ist es möglich, mehrere Ingress-Controller pro NKE-Cluster zu erstellen. Du kannst den Controller über das Feld ingressClassName in der Ingress-Ressource auswählen.

Während die Ingress-IPs statisch bleiben, ist es wichtig zu wissen, dass die Egress-IPs aufgrund betrieblicher Erwägungen dynamisch sind. Insbesondere beim Austausch von Nodes, z. B. bei Upgrades der unterliegenden Betriebssystemversion, initiiert NKE die Erstellung eines neuen Nodes. Die vorhandenen Workloads werden nahtlos auf den neuen Node verschoben, der dann eine neue IP-Adresse erhält. Solltest du statische Egress IPs für deine Cluster Workloads benötigen, so kannst du unser static-egress feature nutzen.

IP Ranges für Egress

Sieh Subnetze an jedem Standort für die aktuellen Egress IP Ranges.

Veraltet: Nginx Ingress-Controller

warnung

Der Nginx Ingress-Controller ist veraltet und wird in einem zukünftigen Release entfernt. Bitte migriere deine Ingress-Ressourcen auf den oben dokumentierten HAProxy Ingress-Controller.

Veraltete Nginx Ingress Dokumentation anzeigen

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`

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.

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

Verifiziere, dass deine Applikation über den HAProxy-Ingress unter dem Test-Hostnamen erreichbar ist:
```
curl http://hello.<haproxy-ingress-dns-name>/
```
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.
Entferne die alte Nginx-Ingress-Ressource, sobald der gesamte Traffic über HAProxy läuft:
```
kubectl --namespace=<namespace> delete ingress <nginx-ingress-name>
```
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.

Verfügbarkeit​

Nutzung​

Ingress DNS Name​

Wildcard DNS Name​

IngressClass​

Automatische TLS-Zertifikate​

Access Logs​

HAProxy Ingress Features​

Basic Authentifizierung​

Rate Limiting​

Temporäre und permanente Weiterleitungen​

HTTPS Weiterleitung​

IP Whitelisting​

Eigenes Standard-Backend​

Statische IPs für Ingress und Egress​

IP Ranges für Egress​

Veraltet: Nginx Ingress-Controller​

IngressClass​

Access Logs​

Spezifische Features​

Basic Authentifizierung​

Rate limiting​

Temporäre und permanente Weiterleitungen​

HTTPS Weiterleitung​

IP whitelisting​

Caching​

Eigenes Standard-Backend​

Zusätzliche benutzerdefinierte Fehler-Seiten​

Von Nginx zu HAProxy migrieren​

Annotations von Nginx migrieren​

Dokumentation und Links​

Verfügbarkeit

Nutzung

Ingress DNS Name

Wildcard DNS Name

IngressClass

Automatische TLS-Zertifikate

Access Logs

HAProxy Ingress Features

Basic Authentifizierung

Rate Limiting

Temporäre und permanente Weiterleitungen

HTTPS Weiterleitung

IP Whitelisting

Eigenes Standard-Backend

Statische IPs für Ingress und Egress

IP Ranges für Egress

Veraltet: Nginx Ingress-Controller

IngressClass

Access Logs

Spezifische Features

Basic Authentifizierung

Rate limiting

Temporäre und permanente Weiterleitungen

HTTPS Weiterleitung

IP whitelisting

Caching

Eigenes Standard-Backend

Zusätzliche benutzerdefinierte Fehler-Seiten

Von Nginx zu HAProxy migrieren

Annotations von Nginx migrieren

Dokumentation und Links