Azure DNS en TLS configureren met de API-implementatie van Application Routing Gateway

Met de Application Routing Gateway-API kunnen gebruikers eenvoudig HTTPS-toepassingen beschikbaar maken op AKS met hun eigen Azure Key Vault certificaten, waaronder automatische domeinnaampublicatie. De operator voor toepassingsroutering integreert met Azure DNS en Azure Key Vault, en stemt een SecretProviderClass, een Kubernetes-secret voor TLS-certificaten, het listenerveld certificateRefs en de afzonderlijke external-dns Deployment op elkaar af, zodat u deze resources niet handmatig hoeft te beheren.

In dit artikel leest u hoe u het volgende kunt doen:

• Richt de vereiste Azure resources (Azure DNS zone, Azure Key Vault, door de gebruiker toegewezen beheerde identiteit, roltoewijzingen en federatieve identiteitsreferenties) in.
• Configureer een Gateway listener om TLS te beëindigen met behulp van een certificaat dat is opgeslagen in Azure Key Vault via de TLS-opties van kubernetes.azure.com/tls-cert-keyvault-uri de kubernetes.azure.com/tls-cert-service-account listener.
• Gebruik de ClusterExternalDNS en ExternalDNS aangepaste resources om DNS-records te publiceren naar Azure DNS op basis van de hostnamen van uw Gateway, HTTPRouteen GRPCRoute resources.

Hoe de integratie werkt

De operator voor toepassingsroutering maakt twee integraties beschikbaar om de resources die u anders handmatig zou maken, te automatiseren om een Gateway resource online te brengen met een aangepast domein en TLS-beëindiging.

TLS-integratie

Wanneer een Gateway resource gebruikmaakt van een beheerde GatewayClass (approuting-istiovan de implementatie van de Application Routing Gateway-API) of istio (vanuit de invoegtoepassing Istio-service-mesh) en een listener de volgende twee TLS-opties heeft, worden de resources die nodig zijn om TLS te beëindigen met behulp van een certificaat dat is opgeslagen in Azure Key Vault, afgestemd:

Voor elke listener die zowel de ene als de andere TLS-optie heeft, doet de operator het volgende:

1. Maakt een SecretProviderClass met de naam kv-gw-cert-<gateway-name>-<listener-name> aan in de naamruimte van Gateway, geconfigureerd om het certificaat op te halen uit Azure Key Vault met behulp van workload identity-verificatie.
2. Activeert de Azure Key Vault-provider voor het Secrets Store CSI-stuurprogramma om het certificaat te synchroniseren naar een kubernetes.io/tls Kubernetes Secret met dezelfde naam in de naamruimte van Gateway.
3. Patcht het veld tls.certificateRefs van de listener zodat het verwijst naar de gesynchroniseerde Kubernetes-secret.

DNS-integratie

De operator Toepassingsroutering beheert een external-dns exemplaar voor u via twee aangepaste resources:

Beide aangepaste resources accepteren optionele filters-selectors om verder te verfijnen welke resources de beheerde external-dns-instantie binnen zijn scope observeert:

Voor elke aangepaste resource doet de operator voor toepassingsroutering het volgende:

1. Hiermee wordt een beheerd external-dns exemplaar geïmplementeerd dat is geconfigureerd voor bronrecords van HTTPRoute en GRPCRoute resources en is gericht op de opgegeven Azure DNS zones.
2. Verifieert zich bij Azure DNS met behulp van Microsoft Entra Workload Identity, via het serviceaccount waarnaar wordt verwezen in het veld identity van de aangepaste resource.
3. Publiceert A-records in elk van de vermelde Azure DNS-zones voor elke HTTPRoute- of GRPCRoute-hostnaam die is gekoppeld aan een beheerde Gateway-resource binnen het toepassingsgebied.

Prerequisites

• Een AKS-cluster waarvoor beide functies zijn ingeschakeld:

  • De add-on voor Application Routing (--enable-app-routing). Met deze invoegtoepassing wordt de Application Routing-operator op het cluster geïnstalleerd. Dit is het onderdeel dat de DNS- en TLS-integraties afstemt die in dit artikel worden beschreven. Op een bestaand cluster kunt u deze functie ook inschakelen met behulp van az aks approuting enable.
  • Een beheerde Gateway API-implementatie waarmee de operator kan integreren. Kies een van de volgende opties (de twee opties sluiten elkaar wederzijds uit en kunnen niet tegelijkertijd worden ingeschakeld):
    • De api-implementatie van de app-routeringsgateway op Istio (--enable-app-routing-istio), die de approuting-istio GatewayClass biedt. Op een bestaand cluster kunt u het ook inschakelen met behulp van az aks approuting gateway istio enable. Gebruik gatewayClassName: approuting-istio voor uw Gateway-resources.
    • De Istio service mesh add-on, waarmee de istio GatewayClass wordt geleverd. Gebruik deze optie wanneer u wilt dat de DNS- en TLS-integraties op Gateway-resources worden beheerd door de Istio-service-mesh-invoegtoepassing en u gatewayClassName: istio op die resources wilt instellen.

  Als u deze integraties wilt gebruiken, schakelt u zowel de application routing-invoegtoepassing (met behulp van) az aks approuting enableals een van de eerder vermelde beheerde gateway-API-implementaties in.

• De installatie van de Managed Gateway-API is ingeschakeld op het cluster.

• De functie Microsoft Entra Workload-identiteit is ingeschakeld op het cluster, samen met de OIDC-uitgever. U kunt beide functies inschakelen met behulp van de --enable-oidc-issuer en --enable-workload-identity vlaggen op az aks create of az aks update.

• De invoegtoepassing Azure Key Vault-provider voor Secrets Store CSI Driver is ingeschakeld op het cluster. U kunt deze inschakelen met behulp van de az aks enable-addons opdracht met --addons azure-keyvault-secrets-providerof door te geven --enable-kv aan az aks approuting enable of az aks approuting update.

• Azure CLI-versie 2.86.0 of hoger. Voer az --version uit om uw azure-cli-versie te vinden en voer az upgrade uit om te upgraden.

• Voldoende Azure op rollen gebaseerd toegangsbeheer (RBAC) voor uw eigen identiteit om roltoewijzingen en federatieve identiteitsgegevens te maken. De Owner rol of een combinatie van Role Based Access Control Administrator en Managed Identity Contributor is voldoende.

Stel de volgende omgevingsvariabelen in. In deze handleiding worden deze bij elke volgende opdracht opnieuw gebruikt:

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

Clustergegevens voor kubectl ophalen:

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

De Azure-infrastructuur maken

De Azure DNS-zone maken

Als u al een Azure DNS zone hebt waarin u wilt dat de operator voor toepassingsroutering records beheert, kunt u deze stap overslaan en de waarde van ZONE_NAME de bestaande zonenaam toewijzen.

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)

Het Azure Key Vault en het certificaat maken

Maak de Azure Key Vault waarin het TLS-certificaat wordt opgeslagen. Configureer de kluis voor het gebruik van Azure RBAC voor autorisatie. Dit is het aanbevolen machtigingsmodel:

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

Maak een zelfondertekend jokertekencertificaat in Azure Key Vault. Voor productie-implementaties importeert u in plaats daarvan een door een certificaatautoriteit (CA) ondertekend certificaat met az keyvault certificate import.

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

Leg de niet-geversiede certificaat-URI vast. De Application Routing-operator gebruikt deze URI om de SecretProviderClass te configureren. Een niet-omgedraaide URI zorgt ervoor dat de operator nieuwe certificaatversies in Azure Key Vault ophaalt wanneer het certificaat wordt geroteerd.

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"

De door de gebruiker toegewezen beheerde identiteit maken en Azure RBAC-rollen verlenen

Maak een door de gebruiker toegewezen beheerde identiteit die de implementatie van de operator voor toepassingsroutering external-dns en de TLS-synchronisatie van de gateway-listener gebruiken om zich te verifiëren bij Azure DNS en Azure Key Vault.

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)

Wijs de beheerde identiteit de rol DNS Zone Contributor toe op de doel-Azure DNS-zone en de rol Key Vault Secrets User op de doel-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)

Maak de namespaces, ServiceAccounts en federatieve identiteitsreferenties aan

De TLS- en DNS-integraties van de toepassingsrouteringsoperator worden beide geverifieerd bij Azure via een Kubernetes ServiceAccount dat is gebonden aan de door de gebruiker toegewezen beheerde identiteit met behulp van een federatieve identiteitsreferentie (FIC). Voor elk (namespace, ServiceAccount) paar dat moet worden geverifieerd, is één FIC vereist.

Leg de URL van de OIDC-verlener van het cluster vast:

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

Voor elke naamruimte waarin u een Gateway resource wilt implementeren die gebruikmaakt van de TLS-integratie of een ExternalDNS resource, maakt u de naamruimte, een federatieve identiteitsreferentie voor het ServiceAccount en het ServiceAccount zelf. In het volgende voorbeeld worden twee naamruimten gemaakt, app-a en app-b, elk met een ServiceAccount met de naam 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

De azure.workload.identity/client-id aantekening koppelt het ServiceAccount aan de beheerde identiteit en het azure.workload.identity/use: "true" label geeft de Microsoft Entra Workload Identity-webhook opdracht om een federatief token te projecteren in pods die het ServiceAccount gebruiken. Beide zijn vereist opdat de TLS- en DNS-integraties van de operator voor toepassingsroutering zich succesvol bij Azure kunnen verifiëren.

TLS-beëindiging configureren op een gateway

Implementeer een voorbeeldworkload httpbin in elke naamruimte:

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

Maak een Gateway resource in elke naamruimte met een HTTPS-listener die verwijst naar het Azure Key Vault-certificaat via de TLS-opties. Elk Gateway maakt gebruik van een eigen subhost van de Azure DNS zone (bijvoorbeeld a.<zone> enb.<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

Wacht totdat elke Gateway de Programmed-conditie bereikt:

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

Controleer of de Application Routing-operator een SecretProviderClass heeft gemaakt en of de Azure Key Vault-provider voor Secrets Store CSI Driver het certificaat naar een kubernetes.io/tls-secret in elke namespace heeft gesynchroniseerd:

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

Voorbeelduitvoer voor één naamruimte:

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

Azure DNS records configureren met behulp van ClusterExternalDNS

Implementeer een clusterbreed external-dns-exemplaar dat A-records publiceert voor Gateway-resources in elke naamruimte door een ClusterExternalDNS-custom resource toe te passen.

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

In resourceNamespace het veld wordt de naamruimte opgegeven waarin de operator Toepassingsroutering het beheerde external-dns exemplaar implementeert. Het ServiceAccount waarnaar wordt identity.serviceAccount verwezen, moet aanwezig zijn in die naamruimte.

Na ongeveer een minuut worden twee A-records weergegeven in de Azure DNS zone: één voor elkGateway:

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

Azure DNS-records configureren met behulp van een naamruimtegebonden ExternalDNS

Als u records wilt publiceren voor slechts een subset van Gateway resources, gebruikt u de aangepaste resource met naamruimtebereik ExternalDNS . In tegenstelling tot ClusterExternalDNS observeert de variant met naamruimtebereik alleen Gateway, HTTPRoute en GRPCRoute resources in dezelfde naamruimte als de aangepaste resource. Net als bij ClusterExternalDNS, kunt u desgewenst het bereik verder beperken met behulp van de filters.gatewayLabels en filters.routeAndIngressLabels selectors.

Verwijder eerst de ClusterExternalDNS uit de vorige stap:

kubectl delete clusterexternaldns demo-cluster-dns

Implementeer een nieuwe Gateway in app-a met het label zone: c en een bijbehorende HTTPRoute:

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

Een naamruimtegebonden resource ExternalDNS toepassen in app-a met een labelfilter voor zone=c:

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

Er zijn twee regels voor het toepassingsgebied:

• Het bereik van de naamruimte van ExternalDNS sluit b-gateway uit omdat deze zich in de naamruimte app-b bevindt.
• Het zone=c labelfilter sluit a-gateway uit omdat het in app-a staat, maar het label zone=a heeft.

De operator Voor toepassingsroutering publiceert een nieuwe A-record voor c.${ZONE_NAME}:

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

HTTPS-verkeer met TLS-terminatie controleren

Los de hostnaam van de Gateway's op via de gezaghebbende naamserver van de Azure DNS zone en verzend een HTTPS-aanvraag:

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"

U zou een HTTP/2 200 antwoord moeten zien. Het TLS-certificaat dat de gateway presenteert, is het certificaat dat vanuit Azure Key Vault is gesynchroniseerd. Als u een door een CA ondertekend certificaat hebt geïmporteerd, vervang -k door --cacert <path-to-ca-chain> om de certificaatketen te valideren.

Limitations

• De DNS- en TLS-integraties zijn alleen van toepassing op Gateway resources die gebruikmaken van een beheerde GatewayClass: approuting-istio (de implementatie van de Application Routing Gateway-API) of istio (de invoegtoepassing istio-service-mesh). Gateway resources die gebruikmaken van een andere GatewayClass worden niet ondersteund.
• Een ClusterExternalDNS- of ExternalDNS-aangepaste resource kan via dnsZoneResourceIDs naar maximaal zeven Azure DNS-zones verwijzen. Alle zones waarnaar in één aangepaste resource wordt verwezen, moeten zich in hetzelfde Azure abonnement en resourcegroep bevinden. Ze moeten ook allemaal van hetzelfde type zijn (openbaar of privé).
• Het beheerde external-dns exemplaar verwijdert niet automatisch DNS-records wanneer u de ClusterExternalDNS of ExternalDNS aangepaste resource verwijdert. Als u verweesde records wilt verwijderen, verwijdert u deze rechtstreeks uit de Azure DNS-zone nadat u de aangepaste resource hebt verwijderd.
• Het afstemmen van DNS-records van TLSRoute resources wordt momenteel niet ondersteund. De beheerde external-dns-instantie haalt alleen records op uit de resources Gateway, HTTPRoute en GRPCRoute.

Volgende stappen 

• Ingress configureren met de Kubernetes Gateway API via de invoegtoepassing voor toepassingsroutering
• Inkomend verkeer beveiligen met de api-implementatie van Application Routing Gateway (handmatige configuratie)