Installieren von AGIC mithilfe einer vorhandenen Application Gateway-Bereitstellung

Artikel
10/20/2024

Der Application Gateway-Eingangscontroller (Application Gateway Ingress Controller, AGIC) ist ein Pod innerhalb Ihres Azure Kubernetes Service (AKS) Clusters. AGIC überwacht die Kubernetes-Eingangsressourcen. Er erstellt und wendet eine Azure Application Gateway-Konfiguration basierend auf dem Status des Kubernetes-Clusters an.

Tipp

Ziehen Sie Application Gateway für Container für Ihre Kubernetes-Eingangslösung in Betracht. Weitere Informationen finden Sie unter Schnellstart: Bereitstellen des ALB-Controllers von Application Gateway für Container.

Voraussetzungen

In diesem Artikel wird davon ausgegangen, dass Sie bereits folgende Tools und Infrastruktur installiert haben:

Ein AKS-Cluster mit Azure Container Networking Interface (CNI)
Application Gateway v2 im gleichen virtuellen Netzwerk wie der AKS-Cluster
Microsoft Entra Workload ID, welche für Ihren AKS-Cluster konfiguriert ist
Azure Cloud Shell als Azure-Shellumgebung, in der az (Azure CLI), kubectl und helm installiert sind. Diese Tools sind für Befehle erforderlich, die das Konfigurieren dieser Bereitstellung unterstützen.

Fügen Sie das Helm-Repository hinzu.

Helm ist ein Paket-Manager für Kubernetes. Sie verwenden sie, um das application-gateway-kubernetes-ingress-Paket zu installieren.

Wenn Sie Cloud Shell verwenden, müssen Sie Helm nicht installieren. Cloud Shell ist in Helm Version 3 enthalten. Führen Sie die folgenden Befehle aus, um das AGIC Helm-Repository für einen AKS-Cluster hinzuzufügen, der mit Kubernetes rollenbasierter Zugriffssteuerung (RBAC) aktiviert ist:

kubectl create serviceaccount --namespace kube-system tiller-sa
kubectl create clusterrolebinding tiller-cluster-rule --clusterrole=cluster-admin --serviceaccount=kube-system:tiller-sa
helm init --tiller-namespace kube-system --service-account tiller-sa

Sichern der Application Gateway-Bereitstellung

Sichern Sie vor der Installation von AGIC die Konfiguration Ihrer Application Gateway-Bereitstellung:

Wechseln Sie im Azure-Portal zu Ihrer Application Gateway-Bereitstellung.
Wählen Sie im Abschnitt Automatisierung die Option Vorlage exportieren und anschließend Herunterladen aus.

Die heruntergeladene ZIP-Datei enthält JSON-Vorlagen, Bash-Skripts und PowerShell-Skripts, die Sie zum Wiederherstellen von Application Gateway verwenden können, wenn eine Wiederherstellung erforderlich wird.

Einrichten einer Identität für die Ressource Manager-Authentifizierung

AGIC kommuniziert mit dem Kubernetes-API-Server und Azure Resource Manager. Für den Zugriff auf diese APIs ist eine Identität erforderlich. Sie können entweder Microsoft Entra Workload ID oder einen Dienstprinzipal verwenden.

Einrichten einer Microsoft Entra Workload-ID

Microsoft Entra Workload ID ist eine Identität, die Sie einer Softwareworkload zuweisen. Diese Identität ermöglicht es Ihrem AKS-Pod, sich bei anderen Azure-Ressourcen zu authentifizieren.

Für diese Konfiguration benötigen Sie eine Autorisierung für den AGIC-Pod zum Senden von HTTP-Anforderungen an Azure Resource Manager.

Verwenden Sie den Azure CLI-Befehl az account set zum Festlegen eines bestimmten Abonnements als aktuelles aktives Abonnement:
```
az account set --subscription "subscriptionID"
```
Verwenden Sie dann den Befehl az identity create, um eine verwaltete Identität zu erstellen. Sie müssen die Identität in der Knotenressourcengruppe erstellen. Der Knotenressourcengruppe wird standardmäßig ein Name zugewiesen, z. B. MC_myResourceGroup_myAKSCluster_eastus.
```
az identity create --name "userAssignedIdentityName" --resource-group "resourceGroupName" --location "location" --subscription "subscriptionID"
```

Führen Sie für die Rollenzuweisung den folgenden Befehl aus, um den principalId-Wert für die neu erstellte Identität zu identifizieren:

$resourceGroup="resource-group-name"
$identityName="identity-name"
az identity list -g $resourceGroup --query "[?name == '$identityName'].principalId | [0]" -o tsv

Gewähren Sie der Identität Zugriff als Mitwirkender auf Ihre Application Gateway-Bereitstellung. Sie benötigen die ID der Application Gateway-Bereitstellung, die wie folgt aussieht: /subscriptions/A/resourceGroups/B/providers/Microsoft.Network/applicationGateways/C.

Rufen Sie zunächst die Liste der Application Gateway-IDs in Ihrem Abonnement mit dem folgenden Befehl ab:

az network application-gateway list --query '[].id'

Führen Sie den folgenden Befehl aus, um der Identität Mitwirkender Zugriff zuzuweisen:

$resourceGroup="resource-group-name"
$identityName="identity-Name"
# Get the Application Gateway ID
$AppGatewayID=$(az network application-gateway list --query '[].id' -o tsv)
$role="contributor"
# Get the principal ID for the user-assigned identity
$principalId=$(az identity list -g $resourceGroup --query "[?name == '$identityName'].principalId | [0]" -o tsv)
az role assignment create --assignee $principalId --role $role --scope $AppGatewayID

Gewähren Sie der Identität Leser Zugriff auf die Application Gateway-Ressourcengruppe. Die Ressourcengruppen-ID sieht wie folgt aus: /subscriptions/A/resourceGroups/B. Sie können alle Ressourcengruppen durch Ausführen von az group list --query '[].id' abrufen.

$resourceGroup="resource-group-name"
$identityName="identity-Name"
# Get the Application Gateway resource group
$AppGatewayResourceGroup=$(az network application-gateway list --query '[].resourceGroup' -o tsv)
# Get the Application Gateway resource group ID
$AppGatewayResourceGroupID=$(az group show --name $AppGatewayResourceGroup --query id -o tsv)
$role="Reader"
# Get the principal ID for the user-assigned identity
$principalId=$(az identity list -g $resourceGroup --query "[?name == '$identityName'].principalId | [0]" -o tsv)
# Assign the Reader role to the user-assigned identity at the resource group scope
az role assignment create --role $role --assignee $principalId  --scope $AppGatewayResourceGroupID

Hinweis

Stellen Sie sicher, dass die von AGIC verwendete Identität über die Berechtigung Microsoft.Network/virtualNetworks/subnets/join/action verfügt, die an das Subnetz, in dem Application Gateway bereitgestellt ist, delegiert ist. Wenn Sie keine benutzerdefinierte Rolle definiert haben, die über diese Berechtigung verfügt, können Sie die integrierte Rolle Netzwerkmitwirkender verwenden.

Einrichten eines Dienstprinzipals

Es ist auch möglich, AGIC mithilfe eines Kubernetes-Schlüssels Zugriff auf Azure Resource Manager zu gewähren:

Erstellen Sie einen Active Directory-Dienstprinzipal, und codieren Sie ihn als Base64. Die Base64-Codierung ist erforderlich, damit das JSON-Blob in Kubernetes gespeichert wird.
```
az ad sp create-for-rbac --role Contributor --sdk-auth | base64 -w0
```
Fügen Sie der Datei helm-config.yaml das Base64-codierte JSON-Blob hinzu. Mit der Datei helm-config.yaml wird AGIC konfiguriert.
```
armAuth:
    type: servicePrincipal
    secretJSON: <Base64-Encoded-Credentials>
```

Bereitstellen des AGIC-Add-Ons

Erstellen eines Bereitstellungsmanifests für den Eingangsdatencontroller

---
# file: pet-supplies-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: pet-supplies-ingress
spec:
  ingressClassName: azure-application-gateway
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: store-front
            port:
              number: 80
      - path: /order-service
        pathType: Prefix
        backend:
          service:
            name: order-service
            port:
              number: 3000
      - path: /product-service
        pathType: Prefix
        backend:
          service:
            name: product-service
            port:
              number: 3002

Bereitstellen des Eingangsdatencontrollers

$namespace="namespace"
$file="pet-supplies-ingress.yaml"
kubectl apply -f $file -n $namespace

Installieren des Eingangsdatencontrollers als Helm-Diagramm

Verwenden Sie Cloud Shell, um das AGIC Helm-Paket zu installieren:

Führen Sie ein Helm-Update durch:
```
helm repo update
```

Laden Sie helm-config.yaml herunter:

wget https://raw.githubusercontent.com/Azure/application-gateway-kubernetes-ingress/master/docs/examples/sample-helm-config.yaml -O helm-config.yaml

Oder kopieren Sie die folgende YAML-Datei:

# This file contains the essential configs for the ingress controller helm chart

# Verbosity level of the App Gateway Ingress Controller
verbosityLevel: 3

################################################################################
# Specify which application gateway the ingress controller must manage
#
appgw:
    subscriptionId: <subscriptionId>
    resourceGroup: <resourceGroupName>
    name: <applicationGatewayName>

    # Setting appgw.shared to "true" creates an AzureIngressProhibitedTarget CRD.
    # This prohibits AGIC from applying config for any host/path.
    # Use "kubectl get AzureIngressProhibitedTargets" to view and change this.
    shared: false

################################################################################
# Specify which kubernetes namespace the ingress controller must watch
# Default value is "default"
# Leaving this variable out or setting it to blank or empty string would
# result in Ingress Controller observing all accessible namespaces.
#
# kubernetes:
#   watchNamespace: <namespace>

################################################################################
# Specify the authentication with Azure Resource Manager
#
# Two authentication methods are available:
# - Option 1: Azure-AD-workload-identity
armAuth:
    type: workloadIdentity
    identityClientID:  <identityClientId>

## Alternatively you can use Service Principal credentials
# armAuth:
#    type: servicePrincipal
#    secretJSON: <<Generate this value with: "az ad sp create-for-rbac --role Contributor --sdk-auth | base64 -w0" >>

################################################################################
# Specify if the cluster is Kubernetes RBAC enabled or not
rbac:
    enabled: false # true/false

# Specify aks cluster related information. THIS IS BEING DEPRECATED.
aksClusterConfiguration:
    apiServerAddress: <aks-api-server-address>

Bearbeiten Sie helm-config.yaml, und füllen Sie die Werte für appgw und armAuth aus.

Hinweis

<identity-client-id> ist eine Eigenschaft des Microsoft Entra Workload ID-Werts, den Sie im vorherigen Abschnitt eingerichtet haben. Sie können diese Informationen mit dem folgenden Befehl abrufen: az identity show -g <resourcegroup> -n <identity-name>. In diesem Befehl steht<resourcegroup> für die Ressourcengruppe, die die Infrastrukturressourcen im Zusammenhang mit dem AKS-Cluster, Application Gateway und der verwalteten Identität hostet.

Installieren Sie das Helm-Diagramm mit der helm-config.yaml-Konfiguration aus dem vorherigen Schritt:

helm install agic-controller oci://mcr.microsoft.com/azure-application-gateway/charts/ingress-azure --version 1.7.5 -f helm-config.yaml

Alternativ dazu können Sie helm-config.yaml und den Helm-Befehl in einem einzigen Schritt kombinieren:

helm install oci://mcr.microsoft.com/azure-application-gateway/charts/ingress-azure \
     --name agic-controller \
     --version 1.7.5 \
     --namespace default \
     --debug \
     --set appgw.name=applicationgatewayABCD \
     --set appgw.resourceGroup=your-resource-group \
     --set appgw.subscriptionId=subscription-uuid \
     --set appgw.shared=false \
     --set armAuth.type=servicePrincipal \
     --set armAuth.secretJSON=$(az ad sp create-for-rbac --role Contributor --sdk-auth | base64 -w0) \
     --set rbac.enabled=true \
     --set verbosityLevel=3 \
     --set kubernetes.watchNamespace=default \
     --set aksClusterConfiguration.apiServerAddress=aks-abcdefg.hcp.westus2.azmk8s.io

Überprüfen Sie das Protokoll des neu erstellten Pods, um sich zu vergewissern, dass er ordnungsgemäß gestartet wurde.

Lesen Sie diese Schrittanleitung, um zu verstehen, wie Sie einen AKS-Dienst über HTTP oder HTTPS über eine Azure Application Gateway-Bereitstellung im Internet verfügbar machen können.

Einrichten einer freigegebenen Application Gateway-Bereitstellung

Standardmäßig übernimmt AGIC die volle Verantwortung für die Application Gateway-Bereitstellung, mit der er verbunden ist. AGIC Version 0.8.0 und höher kann eine einzelne Application Gateway-Bereitstellung für andere Azure-Komponenten freigeben. Sie können z. B. dieselbe Application Gateway-Bereitstellung für eine App verwenden, die in einer Azure-VM-Skalierungsgruppe und einem AKS-Cluster gehostet wird.

Beispielszenario

Sehen wir uns eine imaginäre Application Gateway-Bereitstellung an, die den Datenverkehr für zwei Websites verwaltet:

dev.contoso.com: Wird in einem neuen AKS-Cluster mithilfe von Application Gateway und AGIC gehostet
prod.contoso.com: Wird in einer VM-Skalierungsgruppe gehostet

Mit den Standardeinstellungen übernimmt AGIC zu 100 % die Verantwortung für die Application Gateway-Bereitstellung, auf die er verweist. AGIC überschreibt die gesamte App Gateway-Konfiguration. Sollten Sie manuell einen Listener für prod.contoso.com auf dem Application Gateway erstellen, ohne ihn im eingehenden Kubernetes-Datenverkehr zu definieren, löscht AGIC die prod.contoso.com-Konfiguration innerhalb von Sekunden.

Um AGIC zu installieren und auch prod.contoso.com von den Computern zu bedienen, die die VM-Skalierungsgruppe verwenden, müssen Sie AGIC darauf beschränken, nur dev.contoso.com zu konfigurieren. Sie erleichtern diese Einschränkung, indem Sie die folgende benutzerdefinierte Ressourcendefinition (CRD) instanziieren:

cat <<EOF | kubectl apply -f -
apiVersion: "appgw.ingress.k8s.io/v1"
kind: AzureIngressProhibitedTarget
metadata:
  name: prod-contoso-com
spec:
  hostname: prod.contoso.com
EOF

Mit dem vorherigen Befehl wird ein AzureIngressProhibitedTarget-Objekt erstellt. Dieses Objekt informiert AGIC (Version 0.8.0 und höher) über das Vorhandensein der Application Gateway-Konfiguration für prod.contoso.com. Dieses Objekt weist AGIC außerdem ausdrücklich an, Änderungen an der Konfiguration im Zusammenhang mit diesem Hostnamen zu vermeiden.

Aktivieren einer freigegebenen Application Gateway-Bereitstellung mithilfe einer neuen AGIC-Installation

Um AGIC (Version 0.8.0 und höher) auf eine Teilmenge der Application Gateway-Konfiguration zu beschränken, ändern Sie die helm-config.yaml-Vorlage. Fügen Sie im Abschnitt appgw: den Schlüssel shared hinzu, und legen Sie ihn auf true fest:

appgw:
    subscriptionId: <subscriptionId>    # existing field
    resourceGroup: <resourceGroupName>  # existing field
    name: <applicationGatewayName>      # existing field
    shared: true                        # Add this field to enable shared Application Gateway

Anwenden der Helm-Änderungen:

Stellen Sie sicher, dass die AzureIngressProhibitedTarget-CRD installiert ist:

kubectl apply -f https://raw.githubusercontent.com/Azure/application-gateway-kubernetes-ingress/7b55ad194e7582c47589eb9e78615042e00babf3/crds/AzureIngressProhibitedTarget-v1-CRD-v1.yaml

Aktualisieren Sie Helm:

helm upgrade \
    --recreate-pods \
    -f helm-config.yaml \
    agic-controller
    oci://mcr.microsoft.com/azure-application-gateway/charts/ingress-azure

Ihr AKS-Cluster weist als Ergebnis eine neue Instanz von AzureIngressProhibitedTarget namens prohibit-all-targets auf:

kubectl get AzureIngressProhibitedTargets prohibit-all-targets -o yaml

Das prohibit-all-targets-Objekt verhindert, dass AGIC die Konfiguration für irgendeinen Host und Pfad ändert. Die Helm-Installation mit appgw.shared=true stellt AGIC bereit, nimmt jedoch keine Änderungen an Application Gateway vor.

Ausweiten der Berechtigungen

Da Helm mit appgw.shared=true und der Standardeinstellung prohibit-all-targets AGIC daran hindert, eine Konfiguration anzuwenden, müssen Sie die AGIC-Berechtigungen erweitern:

Erstellen Sie mit dem folgendem Codeschnipsel eine neue YAML-Datei namens AzureIngressProhibitedTarget, die Ihr spezifisches Setup enthält:

cat <<EOF | kubectl apply -f -
apiVersion: "appgw.ingress.k8s.io/v1"
kind: AzureIngressProhibitedTarget
metadata:
  name: your-custom-prohibitions
spec:
  hostname: your.own-hostname.com
EOF

Nachdem Sie nun Ihr eigenes benutzerdefiniertes Verbot erstellt haben, können Sie das standardmäßige Verbot löschen, das zu umfangreich ist:
```
kubectl delete AzureIngressProhibitedTarget prohibit-all-targets
```

Aktivieren einer freigegebenen Application Gateway-Bereitstellung für eine vorhandene AGIC-Installation

Gehen Sie davon aus, dass Sie bereits über einen funktionierenden AKS-Cluster und eine Application Gateway-Bereitstellung verfügen und AGIC in Ihrem Cluster konfiguriert haben. Sie verfügen über eingehenden Datenverkehr für prod.contoso.com und bedienen den Datenverkehr dafür erfolgreich aus dem Cluster.

Sie möchten Ihrer vorhandenen Application Gateway-Bereitstellung staging.contoso.com hinzufügen, müssen sie jedoch auf einem virtuellen Computer hosten. Sie werden die vorhandene Application Gateway-Bereitstellung erneut verwenden und manuell einen Listener und Back-End-Pools für staging.contoso.com konfigurieren. Die manuelle Anpassung der Application Gateway-Konfiguration (mithilfe des Azure-Portals, der Ressource Manager-APIs oder Terraform) würde jedoch im Widerspruch zu den Annahmen des AGIC über die vollständige Eigentümerschaft stehen. Kurz nachdem Sie Änderungen vorgenommen haben, überschreibt oder löscht AGIC diese.

Sie können AGIC verbieten, Änderungen an einem Teil der Konfiguration vorzunehmen:

Erstellen Sie unter Verwendung des folgenden Codeschnipsels eine neue YAML-Datei namens AzureIngressProhibitedTarget:

cat <<EOF | kubectl apply -f -
apiVersion: "appgw.ingress.k8s.io/v1"
kind: AzureIngressProhibitedTarget
metadata:
  name: manually-configured-staging-environment
spec:
  hostname: staging.contoso.com
EOF

Anzeigen des neu erstellten Objekts:

kubectl get AzureIngressProhibitedTargets

Ändern Sie die Application Gateway-Konfiguration über das Azure-Portal. Fügen Sie beispielsweise Listener, Routingregeln und Back-Ends hinzu. Das neue Objekt, das Sie erstellt haben (manually-configured-staging-environment), verhindert, dass AGIC die Application Gateway-Konfiguration für staging.contoso.comüberschreibt.

Application Gateway für Container

Freigeben über

Installieren von AGIC mithilfe einer vorhandenen Application Gateway-Bereitstellung

Voraussetzungen

Fügen Sie das Helm-Repository hinzu.

Sichern der Application Gateway-Bereitstellung

Einrichten einer Identität für die Ressource Manager-Authentifizierung

Einrichten einer Microsoft Entra Workload-ID

Einrichten eines Dienstprinzipals

Bereitstellen des AGIC-Add-Ons

Erstellen eines Bereitstellungsmanifests für den Eingangsdatencontroller

Bereitstellen des Eingangsdatencontrollers

Installieren des Eingangsdatencontrollers als Helm-Diagramm

Einrichten einer freigegebenen Application Gateway-Bereitstellung

Beispielszenario

Aktivieren einer freigegebenen Application Gateway-Bereitstellung mithilfe einer neuen AGIC-Installation

Ausweiten der Berechtigungen

Aktivieren einer freigegebenen Application Gateway-Bereitstellung für eine vorhandene AGIC-Installation

Feedback

Zusätzliche Ressourcen

Freigeben über

Installieren von AGIC mithilfe einer vorhandenen Application Gateway-Bereitstellung

Voraussetzungen

Fügen Sie das Helm-Repository hinzu.

Sichern der Application Gateway-Bereitstellung

Einrichten einer Identität für die Ressource Manager-Authentifizierung

Einrichten einer Microsoft Entra Workload-ID

Einrichten eines Dienstprinzipals

Bereitstellen des AGIC-Add-Ons

Erstellen eines Bereitstellungsmanifests für den Eingangsdatencontroller

Bereitstellen des Eingangsdatencontrollers

Installieren des Eingangsdatencontrollers als Helm-Diagramm

Einrichten einer freigegebenen Application Gateway-Bereitstellung

Beispielszenario

Aktivieren einer freigegebenen Application Gateway-Bereitstellung mithilfe einer neuen AGIC-Installation

Ausweiten der Berechtigungen

Aktivieren einer freigegebenen Application Gateway-Bereitstellung für eine vorhandene AGIC-Installation

Zugehöriger Inhalt

Feedback

Zusätzliche Ressourcen