Zurück zur Startseite

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 Nginx Ingress als Managed Controller an, den Sie im
Cockpit in Ihren NKE-Cluster deployen können. Die einzelnen Features dieses
Controllers können ausserdem mittels Annotations in der Ingress Ressource
gesteuert werden.

Verfügbarkeit

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

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 Ihres Nginx Ingress Controllers zeigt. Damit können Sie die Hostnames Ihrer
eigenen Domains an den Ingress verweisen. DNS ist bereits konfiguriert und die
notwendigen Angaben finden Sie in der Ansicht Nginx Ingress im Cockpit.

Zur Nutzung erstellen Sie einfach in Ihrer 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. Sie können dazu einen beliebigen Hostnamen aus dem
Wildcard-Bereich nehmen und in Ihrer Ingress Ressource als Hostname nutzen, um
schnell etwas zum Laufen zu bringen, ohne sich um DNS-Einträge kümmern zu
müssen.

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: nginx
  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 können Sie in Grafana in der Loki
Explore-Ansicht anschauen. Die Ingress Logs sind unter dem Label
app_kubernetes_io_name="ingress-nginx" verfügbar. Um die Logs einer
spezifischen Ingress-Instanz anzuzeigen, können Sie 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="ingress-nginx",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 finden Sie im spezifischen Support Artikel.

Nginx Ingress Features

Der Nginx Ingress Controller bietet einige Features wie bspw. Rate Limiting, IP
Filtering, Custom Default Backends, temporäre und permanente Weiterleitungen,
etc. Alle zur Steuerung dieser Features verfügbaren Annotations sind in der
offiziellen Nginx Ingress Controller Dokumentation
zu finden.

Nachfolgend finden Sie die Dokumentation zu den meistverwendeten Features.

Basic Authentifizierung

Sie können Basic Authentifizierung zu Ihren Ingress Ressourcen hinzufügen, indem
Sie die Daten in einem Kubernetes Secret bereitstellen. Folgen Sie dazu einfach
den folgenden Schritten:

  1. Setzen Sie einige Umgebungsvariablen
   USERNAME=<YOUR USERNAME>
   SECRET_NAMESPACE=<THE NAMESPACE FOR THE SECRET>
   INGRESS_NAMESPACE=<THE NAMESPACE OF YOUR INGRESS RESOURCE>
   INGRESS=<THE NAME OF YOUR INGRESS RESOURCE>
  1. Erstellen Sie ein Kubernetes Secret, welches Ihre Authentifizierungsdaten beinhaltet. Sie benötigen das Tool mkpasswd, welches bspw. im whois Paket in Debian oder Ubuntu zu finden ist. Das Secret muss dabei nicht zwingend in demselben 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)
  1. Konfigurieren Sie die Ingress Ressource so, dass Ihr erstelltes Secret genutzt wird
   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

Es stehen einige Möglichkeiten zur Verfügung, gewisse Rate Limits auf ihre
Ingress Ressource anzuwenden. Alle verfügbaren Optionen finden Sie in der
offiziellen Dokumentation.

Temporäre und permanente Weiterleitungen

Um eine temporäre Weiterleitung in Ihrer Ingress Ressource einzurichten, nutzen
Sie einfach die folgende Annotation:

nginx.ingress.kubernetes.io/temporal-redirect: <YOUR URL>

Temporäre Weiterleitungen nutzen den HTTP Status Code 302.

Möchten Sie dauerhaft auf eine andere URL weiterleiten, so nutzen Sie:

nginx.ingress.kubernetes.io/permanent-redirect: <YOUR URL>

HTTPS Weiterleitung

Sobald Ihre Ingress Ressource für TLS konfiguriert ist, findet eine automatische
Weiterleitung auf die HTTPS URL des Ingress Objektes statt. Möchten Sie dies
verhindern, so nutzen Sie die folgende Annotation:

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

IP Filtering

Um nur bestimmte IP Bereiche zu erlauben, welche auf Ihre Ingress Ressource
zugreifen dürfen, können Sie mit Komma getrennte CIDR Blöcke in der folgenden
Annotation verwenden:

nginx.ingress.kubernetes.io/whitelist-source-range: <YOUR CIDR RANGE>

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. Sie können das Caching pro Ingress Ressource aktivieren, indem Sie
folgende Annotations in Ihrer 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 haben Sie 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. Sollten Sie davon abweichende
Anforderungen haben, kontaktieren Sie uns gerne.

Um zu überprüfen, ob das Caching funktioniert, kann cURL verwendet werden.
Führen Sie 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 Sie Caching nur für einen ausgewählten Unterpfad nutzen wollen (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.
Diese Optionen finden Sie
hier.

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. Sie können 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, finden Sie
hier.
Dies kann als Beispiel für eigene Implementationen genutzt werden.

Sobald Sie ein eigenes Standard-Backend im gleichen Namespace wie die Ingress
Ressource zur Verfügung gestellt haben, können Sie 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 finden Sie in der
offiziellen Dokumentation.
Eine Beispielapplikation, welche die HTTP Header Informationen auswertet und
benutzerdefinierte Fehler-Seiten anzeigt, ist
hier
zu finden. Diese kann auch als Inspiration für eigene Implementationen dienen.

Haben Sie die gewünschten Informationen nicht gefunden?

Kontaktieren Sie unseren Support:

+41 44 637 40 40 Support Portal support@nine.ch