Zum Hauptinhalt springen
API-Referenz

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. Auf einem vCluster steht standardmässig ein vordefinierter Ingress-Controller des zugrunde liegenden NKE-Host-Clusters zur Verfügung.

hinweis

Der Nginx Ingress-Controller ist veraltet. Seine Dokumentation und die Anleitung zur Migration auf HAProxy findest du unter Nginx Ingress.

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

Läuft in deinem Cluster mehr als ein Ingress-Controller, zum Beispiel während du von Nginx zu HAProxy migrierst, setze zusätzlich die Ingress-Klasse, über die Cert-manager die ACME-HTTP-01-Challenge lösen soll:

metadata:
  annotations:
    kubernetes.io/tls-acme: "true"
    # ACME-Challenge über den HAProxy-Ingress lösen
    acme.cert-manager.io/http01-ingress-ingressclassname: haproxy

Ohne diese Annotation erstellt Cert-manager den Challenge-Ingress auf der Standard-Ingress-Klasse des Clusters. Ist das ein anderer Controller als derjenige, der deinen Ingress bedient, wird das Zertifikat nie ausgestellt oder erneuert.

Access Logs​

Die Access Logs der Ingress Requests kannst du in Grafana in der Loki Explore-Ansicht anschauen. Die Access Logs werden von einem dedizierten Container des Ingress-Controllers geschrieben und sind unter den Labels app="haproxy-ingress" und container="access-logs" verfügbar:

{app="haproxy-ingress", container="access-logs"}

Um die Logs auf ein bestimmtes Backend einzugrenzen, kannst du einen Line Filter verwenden. Jede Access-Log-Zeile enthält das Ziel-Backend im Schema <namespace>_<service>_<port>. Hier ein Beispiel Query, um alle Logs vom Service frontend mit dem Port 80 im Namespace shop-prod anzuzeigen:

{app="haproxy-ingress", container="access-logs"} |= "shop-prod_frontend_80"

Die HTTP-Methode, der Status-Code, der Request-Pfad und die Timings sind Teil der Log-Zeile selbst und können daher mit weiteren Line Filtern gefiltert werden (zum Beispiel |= " 503 ", um Requests mit einem 503 zu finden).

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:

  1. 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>

  2. 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)

  3. 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.