Konfigurieren Sie Azure DNS und TLS mit der Gateway API-Implementierung für Application Routing

Mit der Application Routing Gateway API können Nutzer HTTPS-Anwendungen auf AKS problemlos mit eigenen Azure Key Vault-Zertifikaten bereitstellen, einschließlich der automatischen Veröffentlichung von Domänennamen. Der Application Routing Operator integriert sich in Azure DNS und Azure Key Vault und gleicht SecretProviderClass, ein Kubernetes-Secret für TLS-Zertifikate, das Listenerfeld certificateRefs und das separate external-dns Deployment ab, sodass Sie diese Ressourcen nicht manuell verwalten müssen.

Dieser Artikel zeigt Ihnen, wie das geht:

• Bereitstellen der erforderlichen Azure Ressourcen (Azure DNS Zone, Azure Key Vault, vom Benutzer zugewiesene verwaltete Identität, Rollenzuweisungen und Anmeldeinformationen für Verbundidentitäten).
• Konfigurieren Sie einen Gateway-Listener so, dass TLS mithilfe eines in Azure Key Vault gespeicherten Zertifikats über die Listener-TLS-Optionen kubernetes.azure.com/tls-cert-keyvault-uri und kubernetes.azure.com/tls-cert-service-account beendet wird.
• Verwenden Sie die ClusterExternalDNS und ExternalDNS benutzerdefinierten Ressourcen, um DNS-Einträge basierend auf den Hostnamen Ihrer Gateway, , HTTPRouteund GRPCRoute Ressourcen auf Azure DNS zu veröffentlichen.

Funktionsweise der Integration

Der Anwendungsrouting-Operator macht zwei Integrationen verfügbar, um die Ressourcen zu automatisieren, die Sie sonst manuell erstellen würden, um eine Gateway Ressource online mit einer benutzerdefinierten Domäne und TLS-Beendigung zu bringen.

TLS-Integration

Wenn eine Gateway-Ressource eine verwaltete GatewayClass verwendet – entweder approuting-istio (aus der Application Routing Gateway API-Implementierung) oder istio (aus dem Istio-Service-Mesh-Add-on) – und ein Listener die folgenden beiden TLS-Optionen enthält, gleicht der Application-Routing-Operator die Ressourcen ab, die für die TLS-Terminierung erforderlich sind, indem ein in Azure Key Vault gespeichertes Zertifikat verwendet wird:

Für jeden Listener, der beide TLS-Optionen verwendet, geht der Operator wie folgt vor:

1. Stellt ein SecretProviderClass namens kv-gw-cert-<gateway-name>-<listener-name> im Namespace von Gateway bereit, das so konfiguriert ist, dass das Zertifikat mithilfe der Workload-Identitätsauthentifizierung aus Azure Key Vault bezogen wird.
2. Löst den Azure Key Vault-Anbieter für den Secrets Store CSI-Treiber aus, um das Zertifikat als kubernetes.io/tls Kubernetes-Secret mit demselben Namen im Namespace von Gateway zu synchronisieren.
3. Patcht das Feld tls.certificateRefs des Listeners so, dass es auf das synchronisierte Kubernetes Secret verweist.

DNS-Integration

Der Anwendungsrouting-Operator verwaltet eine external-dns Instanz für Sie über zwei benutzerdefinierte Ressourcen:

Beide benutzerdefinierten Ressourcen akzeptieren optionale filters Selektoren, um weiter einzugrenzen, welche Ressourcen die verwaltete external-dns Instanz innerhalb ihres Gültigkeitsbereichs beobachtet:

Für jede benutzerdefinierte Ressource führt der Application Routing Operator Folgendes aus:

1. Stellt eine verwaltete external-dns-Instanz bereit, die so konfiguriert ist, dass sie Datensätze aus den Ressourcen HTTPRoute und GRPCRoute bezieht, und die die angegebenen Azure-DNS-Zonen als Ziel verwendet.
2. Die Authentifizierung bei Azure DNS erfolgt mithilfe von Microsoft Entra Workload Identity über das ServiceAccount, auf das im Feld identity der benutzerdefinierten Ressource verwiesen wird.
3. Veröffentlicht A-Einträge für jede der aufgelisteten Azure DNS Zonen für jeden HTTPRoute oder GRPCRoute Hostnamen, der an eine verwaltete Gateway Ressource im Bereich gebunden ist.

Voraussetzungen

• Ein AKS-Cluster, bei dem beide der folgenden Funktionen aktiviert sind:

  • Das Add-on für Anwendungsrouting (--enable-app-routing). Dieses Add-On stellt den Anwendungsroutingoperator im Cluster bereit, bei dem es sich um die Komponente handelt, die die in diesem Artikel dokumentierten DNS- und TLS-Integrationen abgleicht. Auf einem vorhandenen Cluster können Sie diese Funktion auch mithilfe von az aks approuting enable aktivieren.
  • Eine verwaltete Gateway-API-Implementierung, mit der sich der Operator integrieren kann. Wählen Sie eine der folgenden Optionen aus (die beiden Optionen schließen sich gegenseitig aus und können nicht gleichzeitig aktiviert werden):
    • Die API-Implementierung der App-Routing-Gateway-API auf Istio (--enable-app-routing-istio), die die GatewayClass approuting-istio bereitstellt. Auf einem vorhandenen Cluster können Sie es auch mit az aks approuting gateway istio enable aktivieren. Verwenden Sie gatewayClassName: approuting-istio für Ihre Gateway Ressourcen.
    • Das Istio-Dienst-Gitter-Add-On, das die istio GatewayClass bereitstellt. Verwenden Sie diese Option, wenn die DNS- und TLS-Integrationen auf Gateway-Ressourcen vom Istio-Service-Mesh-Add-on verwaltet werden sollen und Sie auf diesen Ressourcen gatewayClassName: istio festlegen möchten.

  Um diese Integrationen zu verwenden, aktivieren Sie sowohl das Add-on für Anwendungsrouting (mit az aks approuting enable) als auch eine der zuvor aufgeführten verwalteten Gateway-API-Implementierungen.

• Die Installation der Managed Gateway API, die auf dem Cluster aktiviert ist.

• Die Funktion Microsoft Entra Workload Identity ist auf dem Cluster aktiviert, ebenso wie der OIDC-Aussteller. Sie können beide Funktionen aktivieren, indem Sie die Flags --enable-oidc-issuer und --enable-workload-identity für az aks create oder az aks update verwenden.

• Das Add-on „Azure Key Vault-Anbieter für Secrets Store CSI-Treiber“ ist im Cluster aktiviert. Sie können es mit dem Befehl az aks enable-addons mit --addons azure-keyvault-secrets-provider oder durch Übergabe von --enable-kv an az aks approuting enable oder az aks approuting update aktivieren.

• Azure CLI, Version 2.86.0 oder höher. Führen Sie az --version aus, um Ihre azure-cli-Version zu finden, und führen Sie az upgrade zum Aktualisieren aus.

• Ausreichende rollenbasierte Azure-Zugriffssteuerung (RBAC) für Ihre eigene Identität, um Rollenzuweisungen und Verbundidentitätsanmeldeinformationen zu erstellen. Die Owner Rolle oder eine Kombination von Role Based Access Control Administrator und Managed Identity Contributor ist ausreichend.

Legen Sie die folgenden Umgebungsvariablen fest. Die Schritt-für-Schritt-Anleitung verwendet sie in jedem folgenden Befehl erneut:

export RESOURCE_GROUP=<resource-group-name>
export CLUSTER=<cluster-name>
export LOCATION=<azure-region>

Cluster-Anmeldeinformationen für kubectl abrufen:

az aks get-credentials --resource-group $RESOURCE_GROUP --name $CLUSTER

Erstellen der Azure-Infrastruktur

Erstellen der Azure DNS Zone

Wenn Sie bereits über eine Azure DNS Zone verfügen, in der der Anwendungsroutingoperator Datensätze verwalten soll, können Sie diesen Schritt überspringen und dem vorhandenen Zonennamen den Wert ZONE_NAME zuweisen.

export ZONE_NAME=<dns-zone-name>
az network dns zone create --resource-group $RESOURCE_GROUP --name $ZONE_NAME
export ZONE_ID=$(az network dns zone show --resource-group $RESOURCE_GROUP --name $ZONE_NAME --query id -o tsv)

Erstellen der Azure Key Vault und des Zertifikats

Erstellen Sie die Azure Key Vault, die das TLS-Zertifikat speichert. Konfigurieren Sie den Tresor so, dass Azure RBAC für die Autorisierung verwendet wird. Dies ist das empfohlene Berechtigungsmodell:

export KV_NAME=<key-vault-name>
az keyvault create \
  --name $KV_NAME \
  --resource-group $RESOURCE_GROUP \
  --location $LOCATION \
  --enable-rbac-authorization true

Erstellen Sie ein selbstsigniertes Wildcardzertifikat in Azure Key Vault. Importieren Sie für Produktionsumgebungen stattdessen mithilfe von az keyvault certificate import ein von einer Zertifizierungsstelle (CA) signiertes Zertifikat.

cat > cert-policy.json <<EOF
{
  "issuerParameters": { "name": "Self" },
  "keyProperties": { "exportable": true, "keyType": "RSA", "keySize": 2048, "reuseKey": false },
  "secretProperties": { "contentType": "application/x-pkcs12" },
  "x509CertificateProperties": {
    "subject": "CN=*.${ZONE_NAME}",
    "subjectAlternativeNames": { "dnsNames": ["*.${ZONE_NAME}", "${ZONE_NAME}"] },
    "validityInMonths": 12,
    "keyUsage": ["digitalSignature", "keyEncipherment"]
  }
}
EOF

az keyvault certificate create \
  --vault-name $KV_NAME \
  --name approuting-demo-cert \
  --policy @cert-policy.json

Erfassen Sie die URI des unversionierten Zertifikats. Der Application-Routing-Operator verwendet diesen URI zur Konfiguration von SecretProviderClass. Eine URI ohne Versionsangabe stellt sicher, dass der Operator neue Zertifikatsversionen in Azure Key Vault abruft, wenn das Zertifikat rotiert wird.

export CERT_URI=$(az keyvault certificate show \
  --vault-name $KV_NAME \
  --name approuting-demo-cert \
  --query id -o tsv | sed 's|/[^/]*$||')
echo "Cert URI: $CERT_URI"

Erstellen der benutzerseitig zugewiesenen verwalteten Identität und Zuweisen von Azure RBAC-Rollen

Erstellen Sie eine benutzerseitig zugewiesene verwaltete Identität, die die external-dns-Bereitstellung des Application Routing-Operators und die TLS-Synchronisierung des Gateway-Listeners zur Authentifizierung bei Azure DNS und Azure Key Vault verwenden.

export UAMI_NAME=<managed-identity-name>
az identity create --resource-group $RESOURCE_GROUP --name $UAMI_NAME --location $LOCATION
export UAMI_CLIENT_ID=$(az identity show --resource-group $RESOURCE_GROUP --name $UAMI_NAME --query clientId -o tsv)
export UAMI_PRINCIPAL_ID=$(az identity show --resource-group $RESOURCE_GROUP --name $UAMI_NAME --query principalId -o tsv)

Gewähren Sie der verwalteten Identität die Rolle DNS Zone Contributor für die Ziel-Azure-DNS-Zone und die Rolle Key Vault Secrets User für den Ziel-Azure Key Vault:

az role assignment create \
  --assignee-object-id $UAMI_PRINCIPAL_ID \
  --assignee-principal-type ServicePrincipal \
  --role "DNS Zone Contributor" \
  --scope $ZONE_ID

az role assignment create \
  --assignee-object-id $UAMI_PRINCIPAL_ID \
  --assignee-principal-type ServicePrincipal \
  --role "Key Vault Secrets User" \
  --scope $(az keyvault show --name $KV_NAME --query id -o tsv)

Erstellen der Namespaces, ServiceAccounts und Verbundidentitätsanmeldeinformationen

Sowohl die TLS- als auch die DNS-Integrationen des Application Routing-Operators authentifizieren sich bei Azure über ein Kubernetes-ServiceAccount, das mithilfe einer FIC (Federated Identity Credential) an die benutzerseitig zugewiesene verwaltete Identität gebunden ist. Jedes (namespace, ServiceAccount) Paar, das authentifiziert werden muss, erfordert einen FIC.

Erfassen Sie die OIDC-Aussteller-URL des Clusters:

export OIDC_ISSUER=$(az aks show --resource-group $RESOURCE_GROUP --name $CLUSTER --query oidcIssuerProfile.issuerUrl -o tsv)

Erstellen Sie für jeden Namespace, in dem Sie eine Gateway-Ressource bereitstellen möchten, die die TLS-Integration verwendet, oder eine ExternalDNS-Ressource, den Namespace, eine Verbundidentitäts-Anmeldeinformation für den ServiceAccount und den ServiceAccount selbst. Im folgenden Beispiel werden zwei Namespaces erstellt, app-a und app-bjede mit einem ServiceAccount mit dem Namen approuting-demo-sa:

export SA_NAME=approuting-demo-sa
for ns in app-a app-b; do
  kubectl create namespace $ns

  az identity federated-credential create \
    --identity-name $UAMI_NAME \
    --resource-group $RESOURCE_GROUP \
    --name approuting-demo-fic-$ns \
    --issuer $OIDC_ISSUER \
    --subject "system:serviceaccount:$ns:$SA_NAME" \
    --audiences "api://AzureADTokenExchange"

  kubectl apply -n $ns -f - <<EOF
apiVersion: v1
kind: ServiceAccount
metadata:
  name: $SA_NAME
  annotations:
    azure.workload.identity/client-id: $UAMI_CLIENT_ID
  labels:
    azure.workload.identity/use: "true"
EOF
done

Die azure.workload.identity/client-id Anmerkung ordnet das ServiceAccount der verwalteten Identität zu, und die azure.workload.identity/use: "true" Bezeichnung weist den Microsoft Entra Workload Identity-Webhook an, ein Verbundtoken in Pods zu projizieren, die das ServiceAccount nutzen. Beide sind für die TLS- und DNS-Integrationen des Anwendungsroutinganbieters erforderlich, um sich erfolgreich bei Azure zu authentifizieren.

Konfigurieren der TLS-Beendigung auf einem Gateway

Stellen Sie in jedem Namespace eine Beispiel-Workload httpbin bereit:

for ns in app-a app-b; do
  kubectl apply -n $ns -f https://raw.githubusercontent.com/istio/istio/release-1.27/samples/httpbin/httpbin.yaml
done

Erstellen Sie eine Gateway Ressource in jedem Namespace mit einem HTTPS-Listener, der über die TLS-Optionen auf das Azure Key Vault Zertifikat verweist. Jeder Gateway verwendet einen eigenen Unterhost der zone Azure DNS (z. Ba.<zone>. und b.<zone>):

for pair in "app-a:a" "app-b:b"; do
  ns=${pair%%:*}
  sub=${pair##*:}
  fqdn=${sub}.${ZONE_NAME}
  kubectl apply -n $ns -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: ${sub}-gateway
  labels:
    app: approuting-demo
    zone: ${sub}
spec:
  gatewayClassName: approuting-istio
  listeners:
  - name: https
    hostname: $fqdn
    port: 443
    protocol: HTTPS
    tls:
      mode: Terminate
      options:
        kubernetes.azure.com/tls-cert-keyvault-uri: $CERT_URI
        kubernetes.azure.com/tls-cert-service-account: $SA_NAME
    allowedRoutes:
      namespaces:
        from: Same
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: ${sub}-route
spec:
  parentRefs:
  - name: ${sub}-gateway
  hostnames: ["$fqdn"]
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /get
    backendRefs:
    - name: httpbin
      port: 8000
EOF
done

Warten Sie, bis jeder Gateway die Programmed Bedingung erreicht:

kubectl wait -n app-a --for=condition=programmed gateway a-gateway --timeout=300s
kubectl wait -n app-b --for=condition=programmed gateway b-gateway --timeout=300s

Stellen Sie sicher, dass der Application Routing-Operator ein SecretProviderClass erstellt hat und dass der Azure Key Vault-Anbieter für Secrets Store CSI Driver das Zertifikat in jedem Namespace in ein kubernetes.io/tls-Secret synchronisiert hat:

kubectl get secretproviderclass,secret -n app-a
kubectl get secretproviderclass,secret -n app-b

Beispielausgabe für einen Namespace:

NAME                                                                        AGE
secretproviderclass.secrets-store.csi.x-k8s.io/kv-gw-cert-a-gateway-https   2m

NAME                                TYPE                DATA   AGE
secret/kv-gw-cert-a-gateway-https   kubernetes.io/tls   2      2m

Konfigurieren von Azure DNS Datensätzen mithilfe von ClusterExternalDNS

Stellen Sie eine external-dns-Instanz mit Cluster-Gültigkeit bereit, die A-Einträge für Gateway-Ressourcen in einem beliebigen Namespace veröffentlicht, indem Sie eine ClusterExternalDNS-benutzerdefinierte Ressource anwenden.

kubectl apply -f - <<EOF
apiVersion: approuting.kubernetes.azure.com/v1alpha1
kind: ClusterExternalDNS
metadata:
  name: demo-cluster-dns
spec:
  resourceName: demo-cluster-dns
  resourceNamespace: app-a
  dnsZoneResourceIDs:
  - $ZONE_ID
  resourceTypes:
  - gateway
  identity:
    type: workloadIdentity
    serviceAccount: $SA_NAME
EOF

Das resourceNamespace Feld gibt den Namespace an, in dem der Anwendungsroutingoperator die verwaltete external-dns Instanz bereitstellt. Der ServiceAccount, auf den identity.serviceAccount verweist, muss in diesem Namespace vorhanden sein.

Nach etwa einer Minute erscheinen in der Azure DNS-Zone zwei A-Datensätze – je einer für jedes Gateway:

az network dns record-set a list --resource-group $RESOURCE_GROUP --zone-name $ZONE_NAME -o table

Name    ResourceGroup              Ttl    Type    AutoRegistered    Metadata
------  -------------------------  -----  ------  ----------------  --------
a       <your-rg>                  300    A       False
b       <your-rg>                  300    A       False

Konfigurieren Sie Azure DNS-Einträge mithilfe eines auf einen Namespace beschränkten ExternalDNS

Wenn Sie Datensätze nur für eine Teilmenge von Gateway Ressourcen veröffentlichen möchten, verwenden Sie die benutzerdefinierte Ressource mit Namespacebereich ExternalDNS . Im Gegensatz zu ClusterExternalDNS beobachtet die namensraumbezogene Variante nur Gateway-, HTTPRoute- und GRPCRoute-Ressourcen im selben Namespace wie die benutzerdefinierte Ressource. Wie bei ClusterExternalDNS können Sie den Geltungsbereich optional weiter einschränken, indem Sie die Selektoren filters.gatewayLabels und filters.routeAndIngressLabels verwenden.

Löschen Sie zuerst den ClusterExternalDNS aus dem vorherigen Schritt:

kubectl delete clusterexternaldns demo-cluster-dns

Stellen Sie ein neues Gateway in app-a mit der Bezeichnung zone: c und einem entsprechenden HTTPRoute bereit:

kubectl apply -n app-a -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: c-gateway
  labels:
    app: approuting-demo
    zone: c
spec:
  gatewayClassName: approuting-istio
  listeners:
  - name: https
    hostname: c.${ZONE_NAME}
    port: 443
    protocol: HTTPS
    tls:
      mode: Terminate
      options:
        kubernetes.azure.com/tls-cert-keyvault-uri: $CERT_URI
        kubernetes.azure.com/tls-cert-service-account: $SA_NAME
    allowedRoutes:
      namespaces:
        from: Same
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: c-route
spec:
  parentRefs:
  - name: c-gateway
  hostnames: ["c.${ZONE_NAME}"]
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /get
    backendRefs:
    - name: httpbin
      port: 8000
EOF

kubectl wait -n app-a --for=condition=programmed gateway c-gateway --timeout=300s

Eine auf den Namespace bezogene ExternalDNS Ressource in app-a mit einem Labelfilter für zone=c anwenden:

kubectl apply -n app-a -f - <<EOF
apiVersion: approuting.kubernetes.azure.com/v1alpha1
kind: ExternalDNS
metadata:
  name: demo-ns-dns
spec:
  resourceName: demo-ns-dns
  dnsZoneResourceIDs:
  - $ZONE_ID
  resourceTypes:
  - gateway
  identity:
    type: workloadIdentity
    serviceAccount: $SA_NAME
  filters:
    gatewayLabels: "zone=c"
EOF

Es gelten zwei Regeln für den Gültigkeitsbereich:

• Der Namespacebereich von ExternalDNS schließt b-gateway aus, da es sich im Namespace app-b befindet.
• Der zone=c Labelfilter schließt a-gateway aus, da es sich in app-a befindet, aber mit zone=a gekennzeichnet ist.

Der Anwendungsrouting-Operator veröffentlicht einen neuen A-Eintrag für c.${ZONE_NAME}:

az network dns record-set a list --resource-group $RESOURCE_GROUP --zone-name $ZONE_NAME -o table

Überprüfen des TLS-beendeten HTTPS-Datenverkehrs

Lösen Sie den Gateway-Hostnamen über den autoritativen Nameserver der Azure DNS-Zone auf, und senden Sie eine HTTPS-Anfrage:

NS=$(az network dns zone show --resource-group $RESOURCE_GROUP --name $ZONE_NAME --query 'nameServers[0]' -o tsv | sed 's/\.$//')
GATEWAY_IP=$(dig +short @${NS} a.${ZONE_NAME} | tail -1)
curl -k -I --resolve "a.${ZONE_NAME}:443:${GATEWAY_IP}" "https://a.${ZONE_NAME}/get"

Es sollte eine HTTP/2 200-Antwort angezeigt werden. Das vom Gateway angezeigte TLS-Zertifikat ist das von Azure Key Vault synchronisierte Zertifikat. Wenn Sie ein CA-signiertes Zertifikat importiert haben, ersetzen Sie -k durch --cacert <path-to-ca-chain>, um die Zertifikatskette zu validieren.

Einschränkungen

• Die DNS- und TLS-Integrationen gelten nur für Gateway Ressourcen, die eine verwaltete GatewayClass verwenden: approuting-istio (Implementierung der Anwendungsroutinggateway-API) oder istio (das Istio-Dienst-Gitter-Add-On). Gateway Ressourcen, die andere GatewayClass verwenden, werden nicht unterstützt.
• Eine ClusterExternalDNS- oder ExternalDNS-benutzerdefinierte Ressource kann über dnsZoneResourceIDs auf bis zu sieben Azure-DNS-Zonen verweisen. Alle Zonen, auf die in einer einzelnen benutzerdefinierten Ressource verwiesen wird, müssen sich in derselben Azure Abonnement- und Ressourcengruppe befinden. Sie müssen auch denselben Typ aufweisen (öffentlich oder privat).
• Die verwaltete external-dns Instanz löscht DNS-Einträge nicht automatisch, wenn Sie die benutzerdefinierte Ressource ClusterExternalDNS oder ExternalDNS löschen. Um verwaiste Datensätze zu entfernen, löschen Sie sie direkt aus der zone Azure DNS nach dem Löschen der benutzerdefinierten Ressource.
• Die Abstimmung von DNS-Einträgen aus TLSRoute Ressourcen wird derzeit nicht unterstützt. Die verwaltete external-dns-Instanz bezieht Datensätze nur aus den Gateway-, HTTPRoute- und GRPCRoute-Ressourcen.

Nächste Schritte

• Konfigurieren Sie Ingress mit der Kubernetes-Gateway-API über das Add-On für Anwendungsrouting
• Absichern des eingehenden Datenverkehrs mit der API-Implementierung von Application Routing Gateway (manuelle Konfiguration)