Erweiterter NGINX-Ingress-Controller und Ingress-Konfigurationen mit dem Routing-Add-On für Anwendungen im Azure Kubernetes Service (AKS)

Konfigurationseigenschaften für NGINX-Eingangscontroller

Das Anwendungsrouting-Add-On verwendet eine benutzerdefinierte Ressourcendefinition (CRD) namens NginxIngressController von Kubernetes, um NGINX-Eingangsdatencontroller zu konfigurieren. Sie können weitere Eingangscontroller erstellen oder vorhandene Konfigurationen ändern.

In der folgenden Tabelle werden die Eigenschaften angezeigt, die Sie zum Konfigurieren eines NginxIngressController verwenden können:

Steuern der Standardkonfiguration des NGINX-Eingangscontrollers

Wenn Sie das Anwendungsrouting-Add-On mit NGINX aktivieren, wird ein Eingangsdatencontroller namens default im app-routing-namespace erstellt, der mit einem öffentlichen Azure-Lastenausgleich konfiguriert ist. Dieser Eingangsdatencontroller verwendet einen Eingangsklassennamen von webapprouting.kubernetes.azure.com.

Sie können auch steuern, ob der Standardwert eine öffentliche oder eine interne IP erhält oder ob sie überhaupt erstellt wird, wenn das Add-On aktiviert wird.

Mögliche Konfigurationsoptionen sind:

• None: Der Standardmäßige NGINX-Eingangscontroller wird nicht erstellt und wird nicht gelöscht, wenn er bereits vorhanden ist. Sie sollten die benutzerdefinierte Standardressource NginxIngressController bei Bedarf manuell löschen.
• Internal: Der Standardmäßige NGINX-Eingangscontroller wird mit einem internen Lastenausgleich erstellt. Alle Anmerkungsänderungen an der NginxIngressController benutzerdefinierten Ressource, damit sie extern wird, werden überschrieben.
• External: Der standardmäßige NGINX-Ingress-Controller, der mit einem externen Load-Balancer erstellt wurde. Alle Anmerkungsänderungen an der NginxIngressController benutzerdefinierten Ressource, damit sie intern wird, werden überschrieben.
• AnnotationControlled (Standardeinstellung): Der standardmäßige NGINX-Ingress-Controller wird mit einem externen Load Balancer erstellt. Sie können die benutzerdefinierte NginxIngressControllerStandardressource bearbeiten, um Anmerkungen zum Lastenausgleich zu konfigurieren.)

Steuern der Standardkonfiguration des Eingangscontrollers in einem neuen Cluster

Aktualisieren der Standardkonfiguration des Eingangsdatencontrollers auf einem vorhandenen Cluster

Erstellen eines weiteren öffentlich zugänglichen NGINX-Eingangsdatencontrollers

1. Kopieren Sie das folgende YAML-Manifest in eine neue Datei mit dem Namen nginx-public-controller.yaml , und speichern Sie die Datei auf Ihrem lokalen Computer.

   apiVersion: approuting.kubernetes.azure.com/v1alpha1
   kind: NginxIngressController
   metadata:
     name: nginx-public
   spec:
     ingressClassName: nginx-public
     controllerNamePrefix: nginx-public
   

2. Erstellen Sie die Ressourcen des NGINX-Eingangsdatencontrollers mithilfe des Befehls kubectl apply.

   kubectl apply -f nginx-public-controller.yaml
   

   In der folgenden Beispielausgabe sehen Sie die erstellten Ressourcen:

   nginxingresscontroller.approuting.kubernetes.azure.com/nginx-public created
   

Erstellen eines internen NGINX-Eingangsdatencontrollers mit einer privaten IP-Adresse

1. Kopieren Sie das folgende YAML-Manifest in eine neue Datei mit dem Namen nginx-internal-controller.yaml , und speichern Sie die Datei auf Ihrem lokalen Computer.

   apiVersion: approuting.kubernetes.azure.com/v1alpha1
   kind: NginxIngressController
   metadata:
     name: nginx-internal
   spec:
     ingressClassName: nginx-internal
     controllerNamePrefix: nginx-internal
     loadBalancerAnnotations: 
       service.beta.kubernetes.io/azure-load-balancer-internal: "true"
   

2. Erstellen Sie die Ressourcen des NGINX-Eingangsdatencontrollers mithilfe des Befehls kubectl apply.

   kubectl apply -f nginx-internal-controller.yaml
   

   In der folgenden Beispielausgabe sehen Sie die erstellten Ressourcen:

   nginxingresscontroller.approuting.kubernetes.azure.com/nginx-internal created
   

Erstellen eines NGINX-Eingangsdatencontrollers mit einer statischen IP-Adresse

1. Erstellen Sie mithilfe des Befehls az group create eine Azure-Ressourcengruppe.

   az group create --name $NETWORK_RESOURCE_GROUP --location $LOCATION
   

2. Verwenden Sie den Befehl az network public ip create, um eine statische öffentliche IP-Adresse zu erstellen.

   az network public-ip create \
     --resource-group $NETWORK_RESOURCE_GROUP \
     --name $PUBLIC_IP_NAME \
     --sku Standard \
     --allocation-method static
   

   Hinweis

   Wenn Sie einen Basic SKU-Load-Balancer in Ihrem AKS-Cluster verwenden, geben Sie Basic für den --sku-Parameter beim Definieren einer öffentlichen IP an. Nur Basic SKU-IPs funktionieren mit dem Basic SKU-Lastenausgleich und nur Standard SKU-IPs funktionieren mit den Standard SKU-Lastenausgleichern.

3. Verwenden Sie den Befehl az role assignment create, um sicherzustellen, dass die vom AKS-Cluster verwendete Clusteridentität über delegierte Berechtigungen für die öffentliche IP-Adresse der Ressourcengruppe verfügt.

   CLIENT_ID=$(az aks show --name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --query identity.principalId -o tsv)
   RG_SCOPE=$(az group show --name $NETWORK_RESOURCE_GROUP --query id -o tsv)
   az role assignment create \
     --assignee ${CLIENT_ID} \
     --role "Network Contributor" \
     --scope ${RG_SCOPE}
   

4. Kopieren Sie das folgende YAML-Manifest in eine neue Datei mit dem Namen nginx-staticip-controller.yaml , und speichern Sie die Datei auf Ihrem lokalen Computer.

   Hinweis

   Sie können entweder service.beta.kubernetes.io/azure-pip-name für eine öffentliche IP-Adresse oder service.beta.kubernetes.io/azure-load-balancer-ipv4 für eine IPv4-Adresse und service.beta.kubernetes.io/azure-load-balancer-ipv6 für eine IPv6-Adresse verwenden, wie im YAML-Beispielcode gezeigt. Das Hinzufügen der service.beta.kubernetes.io/azure-pip-name-Anmerkung gewährleistet die effizienteste Load Balancer-Erstellung und wird dringend empfohlen, um eine potenzielle Drosselung zu vermeiden.

   apiVersion: approuting.kubernetes.azure.com/v1alpha1
   kind: NginxIngressController
   metadata:
     name: nginx-static
   spec:
     ingressClassName: nginx-static
     controllerNamePrefix: nginx-static
     loadBalancerAnnotations: 
       service.beta.kubernetes.io/azure-pip-name: "$PUBLIC_IP_NAME"
       service.beta.kubernetes.io/azure-load-balancer-resource-group: "$NETWORK_RESOURCE_GROUP"
   

5. Erstellen Sie die Ressourcen des NGINX-Eingangsdatencontrollers mithilfe des Befehls kubectl apply.

   kubectl apply -f nginx-staticip-controller.yaml
   

   In der folgenden Beispielausgabe sehen Sie die erstellten Ressourcen:

   nginxingresscontroller.approuting.kubernetes.azure.com/nginx-static created
   

Überprüfen, ob der Eingangsdatencontroller erstellt wurde

• Überprüfen Sie den Status des NGINX-Eingangscontrollers mithilfe des kubectl get nginxingresscontroller Befehls.

  kubectl get nginxingresscontroller --name $INGRESS_CONTROLLER_NAME
  

  In der folgenden Beispielausgabe sehen Sie die erstellte Ressource. Es kann einige Minuten dauern, bis der Controller verfügbar ist.

  NAME           INGRESSCLASS   CONTROLLERNAMEPREFIX   AVAILABLE
  nginx-public   nginx-public   nginx                  True
  

Anzeigen der Bedingungen des Eingangscontrollers

• Zeigen Sie die Bedingungen des Eingangscontrollers an, um Probleme mit dem kubectl get nginxingresscontroller Befehl zu beheben.

  kubectl get nginxingresscontroller --name $INGRESS_CONTROLLER_NAME -o jsonpath='{range .items[*].status.conditions[*]}{.lastTransitionTime}{"\t"}{.status}{"\t"}{.type}{"\t"}{.message}{"\n"}{end}'
  

  Die folgende Beispielausgabe zeigt die Bedingungen eines fehlerfreien Eingangscontrollers:

  2023-11-29T19:59:24Z    True    IngressClassReady       Ingress Class is up-to-date
  2023-11-29T19:59:50Z    True    Available               Controller Deployment has minimum availability and IngressClass is up-to-date
  2023-11-29T19:59:50Z    True    ControllerAvailable     Controller Deployment is available
  2023-11-29T19:59:25Z    True    Progressing             Controller Deployment has successfully progressed
  

Verwenden des Eingangsdatencontrollers in einem Eingang

1. Kopieren Sie das folgende YAML-Manifest in eine neue Datei mit dem Namen ingress.yaml , und speichern Sie die Datei auf Ihrem lokalen Computer.

   Hinweis

   Aktualisieren Sie <HostName> mit Ihrem DNS-Hostnamen. Der <IngressClassName> ist der, den Sie beim Erstellen des NginxIngressController definiert haben.

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: aks-helloworld
     namespace: hello-web-app-routing
   spec:
     ingressClassName: <IngressClassName>
     rules:
     - host: <HostName>
       http:
         paths:
         - backend:
             service:
               name: aks-helloworld
               port:
                 number: 80
           path: /
           pathType: Prefix
   

2. Erstellen Sie die Clusterressourcen mithilfe des Befehls kubectl apply.

   kubectl apply -f ingress.yaml --namespace hello-web-app-routing
   

   In der folgenden Beispielausgabe sehen Sie die erstellten Ressourcen:

   ingress.networking.k8s.io/aks-helloworld created
   

Überprüfen, ob der verwaltete Eingang erstellt wurde

• Überprüfen Sie, ob der verwaltete Eingangseingang mithilfe des kubectl get ingress Befehls erstellt wurde.

  kubectl get ingress --namespace hello-web-app-routing
  

  Ihre Ausgabe sollte in etwa wie die folgende Beispielausgabe aussehen:

  NAME             CLASS                                HOSTS               ADDRESS       PORTS     AGE
  aks-helloworld   webapprouting.kubernetes.azure.com   myapp.contoso.com   20.51.92.19   80, 443   4m
  

Entfernen von Eingangscontrollern

• Entfernen Sie den NGINX-Eingangscontroller mithilfe des kubectl delete nginxingresscontroller Befehls.

  kubectl delete nginxingresscontroller --name $INGRESS_CONTROLLER_NAME
  

Konfiguration pro Eingangsressource über Anmerkungen

Der NGINX-Eingangscontroller unterstützt das Hinzufügen von Anmerkungen zu bestimmten Eingangsobjekten , um ihr Verhalten anzupassen.

Sie können Anmerkungen an das Eingangsobjekt anzufügen, indem Sie die entsprechende Anmerkung im Feld metadata.annotations hinzufügen.

In den folgenden Abschnitten finden Sie Beispiele für allgemeine Konfigurationen. Eine vollständige Liste finden Sie in der Dokumentation zu NGINX-Eingangsanmerkungen.

Benutzerdefinierte max. Textkörpergröße

Bei NGINX wird ein 413-Fehler an den Client zurückgegeben, wenn die Größe in einer Anforderung die maximal zulässige Größe des Clientanforderungstexts überschreitet. Verwenden Sie zum Überschreiben des Standardwerts die Anmerkung:

nginx.ingress.kubernetes.io/proxy-body-size: 4m

Hier ist ein Beispiel für die Eingangskonfiguration mit dieser Anmerkung:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: 4m
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Benutzerdefiniertes Verbindungstimeout

Sie können die Zeitspanne (das Timeout) ändern, die der NGINX-Eingangsdatencontroller wartet, um eine Verbindung mit Ihrer Arbeitslast zu schließen. Alle Timeoutwerte sind einheitslos und in Sekunden. Verwenden Sie zum Überschreiben des Standardtimeouts die folgende Anmerkung, um ein gültiges 120-Sekunden-Proxy-Lesetimeout festzulegen:

nginx.ingress.kubernetes.io/proxy-read-timeout: "120"

Überprüfen Sie benutzerdefinierte Timeouts für andere Konfigurationsoptionen.

Hier ist ein Beispiel für die Eingangskonfiguration mit dieser Anmerkung:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Back-End-Protokoll

Der NGINX-Eingangscontroller verwendet HTTP , um die Dienste standardmäßig zu erreichen. Verwenden Sie eine der folgenden Anmerkungen, um alternative Back-End-Protokolle wie HTTPS oder GRPCzu konfigurieren:

# HTTPS annotation
nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"

# GRPC annotation
nginx.ingress.kubernetes.io/backend-protocol: "GRPC"

Sehen Sie sich Back-End-Protokolle für andere Konfigurationsoptionen an.

Hier ist ein Beispiel für die Eingangskonfiguration mit dieser Anmerkung:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Ressourcenfreigabe zwischen verschiedenen Ursprüngen (CORS)

Verwenden Sie zum Aktivieren der Cross-Origin Resource Sharing (CORS) in einer Ingress-Regel die folgende Anmerkung:

nginx.ingress.kubernetes.io/enable-cors: "true"

Sehen Sie sich Aktivieren von CORS für andere Konfigurationsoptionen an.

Hier ist ein Beispiel für die Eingangskonfiguration mit dieser Anmerkung:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/enable-cors: "true"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

SSL-Umleitung deaktivieren

Der Controller leitet (308) an HTTPS um, wenn TLS standardmäßig für einen Ingress aktiviert ist. Um dieses Feature für bestimmte Eingangsressourcen zu deaktivieren, verwenden Sie die folgende Anmerkung:

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

Sehen Sie sich serverseitige HTTPS-Erzwingung durch Umleitung für weitere Konfigurationsoptionen an.

Hier ist ein Beispiel für die Eingangskonfiguration mit dieser Anmerkung:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "false"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

URL-Umschreibung

In einigen Szenarien unterscheidet sich die verfügbar gemachte URL im Back-End-Dienst vom angegebenen Pfad in der Eingangsregel. Ohne erneutes Schreiben einer Anforderung wird 404 zurückgegeben. Diese Konfiguration ist hilfreich bei pfadbasiertem Routing , bei dem Sie zwei verschiedene Webanwendungen unter derselben Domäne bedienen können. Sie können den vom Dienst erwarteten Pfad mit der folgenden Anmerkung festlegen:

nginx.ingress.kubernetes.io/rewrite-target: /$2

Hier ist ein Beispiel für die Eingangskonfiguration mit dieser Anmerkung:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <HostName>
    http:
      paths:
      - path: /app-one(/|$)(.*)
        pathType: Prefix 
        backend:
          service:
            name: app-one
            port:
              number: 80
      - path: /app-two(/|$)(.*)
        pathType: Prefix 
        backend:
          service:
            name: app-two
            port:
              number: 80

Aktualisierung des NGINX-Gesundheitsprüfungspfads

Der Standard-Health-Probe-Pfad für den Azure Load Balancer, der dem NGINX-Eingangscontroller zugeordnet ist, muss auf "/healthz" gesetzt werden. Um die korrekten Gesundheitsprüfungen sicherzustellen, vergewissern Sie sich, dass der Ingress-Controller-Dienst die folgende Annotation hat.

metadata:
  annotations:
    service.beta.kubernetes.io/azure-load-balancer-health-probe-request-path: "/healthz"

Wenn Sie Helm zum Verwalten Ihres Ingress-Controllers von NGINX verwenden, können Sie die Azure Load Balancer-Integritätsprüfung-Anmerkung in einer Werte-Datei definieren und während eines Upgrades anwenden.

controller:
  service:
    annotations:
      service.beta.kubernetes.io/azure-load-balancer-health-probe-request-path: "/healthz"

Diese Konfiguration trägt dazu bei, die Dienstverfügbarkeit aufrechtzuerhalten und unerwartete Datenverkehrsunterbrechungen während Upgrades zu vermeiden.