Een service-principal gebruiken met AKS (Azure Kubernetes Service)

  • Artikel

Een AKS-cluster vereist een Microsoft Entra-service-principal of een beheerde identiteit om dynamisch andere Azure-resources te maken en te beheren, zoals een Azure Load Balancer of Azure Container Registry (ACR).

Notitie

U wordt aangeraden beheerde identiteiten te gebruiken om te verifiëren met andere resources in Azure. Dit is de standaardverificatiemethode voor uw AKS-cluster. Zie Een door het systeem toegewezen beheerde identiteit gebruiken voor meer informatie over het gebruik van een beheerde identiteit met uw cluster.

In dit artikel leest u hoe u een service-principal voor uw AKS-clusters maakt en gebruikt.

Voordat u begint

Als u een Microsoft Entra-service-principal wilt maken, moet u gemachtigd zijn om een toepassing te registreren bij uw Microsoft Entra-tenant en om de toepassing toe te wijzen aan een rol in uw abonnement. Als u niet over de benodigde machtigingen beschikt, moet u uw Microsoft Entra-id of abonnementsbeheerder vragen om de benodigde machtigingen toe te wijzen of een service-principal vooraf te maken voor gebruik met uw AKS-cluster.

Als u een service-principal van een andere Microsoft Entra-tenant gebruikt, zijn er andere overwegingen met betrekking tot de beschikbare machtigingen wanneer u het cluster implementeert. Mogelijk hebt u niet de juiste machtigingen om mapgegevens te lezen en te schrijven. Zie Wat zijn de standaardgebruikersmachtigingen in Microsoft Entra-id?

Vereisten

  • Als u Azure CLI gebruikt, hebt u Azure CLI versie 2.0.59 of hoger nodig. Voer az --version uit om de versie te bekijken. Als u Azure CLI 2.0 wilt installeren of upgraden, raadpleegt u Azure CLI 2.0 installeren.
  • Als u Azure PowerShell gebruikt, hebt u Azure PowerShell versie 5.0.0 of hoger nodig. Voer Get-InstalledModule -Name Az uit om de versie te bekijken. Als u de Azure Az PowerShell-module wilt installeren of upgraden, raadpleegt u De Azure Az PowerShell-module installeren.

Handmatig een service-principal maken

  1. Maak een service-principal met behulp van de az ad sp create-for-rbac opdracht.

    az ad sp create-for-rbac --name myAKSClusterServicePrincipal

    De uitvoer moet er ongeveer uitzien als in de volgende voorbeelduitvoer:

    {
  "appId": "559513bd-0c19-4c1a-87cd-851a26afd5fc",
  "displayName": "myAKSClusterServicePrincipal",
  "name": "http://myAKSClusterServicePrincipal",
  "password": "e763725a-5eee-40e8-a466-dc88d980f415",
  "tenant": "72f988bf-86f1-41af-91ab-2d7cd011db48"
}

  2. Kopieer de waarden voor appId en password uit de uitvoer. U gebruikt deze bij het maken van een AKS-cluster in de volgende sectie.

Een service-principal opgeven voor een AKS-cluster

  • Gebruik een bestaande service-principal voor een nieuw AKS-cluster met behulp van de az aks create opdracht en gebruik de --service-principal en --client-secret parameters om de appId en password uit de uitvoer op te geven die u in de vorige sectie hebt ontvangen.

    az aks create \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --service-principal <appId> \
    --client-secret <password>

    Notitie

    Als u een bestaande service-principal met aangepast geheim gebruikt, moet u ervoor zorgen dat het geheim niet langer is dan 190 bytes.

Machtiging afgeven voor toegang tot andere Azure-resources

U kunt de service-principal voor het AKS-cluster gebruiken om toegang te krijgen tot andere resources. Als u bijvoorbeeld uw AKS-cluster wilt implementeren in een bestaand subnet van een virtueel Azure-netwerk of verbinding wilt maken met Azure Container Registry (ACR), moet u de toegang tot deze resources delegeren aan de service-principal. Het kan 60 minuten duren voordat machtigingen aan een cluster worden verleend met behulp van een door het systeem toegewezen beheerde identiteit.

  • Maak een roltoewijzing met behulp van de az role assignment create opdracht. Wijs het appId toe aan een bepaald bereik, zoals een resourcegroep of virtuele netwerkresource. De rol definieert welke machtigingen de service-principal heeft voor de resource.

    Notitie

    Voor --scope een resource moet een volledige resource-id zijn, zoals /subscriptions/<guid>/resourceGroups/myResourceGroup of /subscriptions/<guid>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet.

    az role assignment create --assignee <appId> --scope <resourceScope> --role Contributor

In de volgende secties worden algemene delegaties beschreven die u mogelijk moet toewijzen.

Azure Container Registry

Als u Azure Container Registry (ACR) als containerinstallatiekopiearchief gebruikt, moet u machtigingen verlenen aan de service-principal voor uw AKS-cluster om installatiekopieën te lezen en op te halen. U wordt aangeraden de az aks create of az aks update opdracht te gebruiken om te integreren met een register en de juiste rol toe te wijzen voor de service-principal. Zie Verifiëren met Azure Container Registry vanuit Azure Kubernetes Service voor gedetailleerde stappen.

Netwerken

U kunt gebruikmaken van geavanceerde netwerkmogelijkheden als het virtuele netwerk en het subnet of de openbare IP-adressen zich in een andere resourcegroep bevinden. Wijs de ingebouwde rol Inzender voor netwerk toe aan het subnet binnen het virtuele netwerk. U kunt ook een aangepaste rol maken met machtigingen voor toegang tot de netwerkresources in die resourcegroep. Zie AKS-servicemachtigingen voor meer informatie.

Storage

Als u toegang nodig hebt tot bestaande schijfresources in een andere resourcegroep, wijst u een van de volgende sets rolmachtigingen toe:

  • Maak een aangepaste rol en definieer de machtigingen Microsoft.Compute/disks/read en Microsoft.Compute/disks/write role, of
  • Wijs de ingebouwde rol Inzender voor virtuele machines toe aan de resourcegroep.

Azure Container Instances

Als u Virtual Kubelet gebruikt om te integreren met AKS en ervoor kiest Om Azure Container Instances (ACI) uit te voeren in de resourcegroep, gescheiden van het AKS-cluster, moet de service-principal van het AKS-cluster inzendermachtigingen krijgen voor de ACI-resourcegroep.

Overige overwegingen

Houd rekening met het volgende bij het gebruik van AKS en een Microsoft Entra-service-principal:

  • De service-principal voor Kubernetes maakt deel uit van de clusterconfiguratie, maar gebruik deze identiteit niet om het cluster te implementeren.
  • De referenties van de service-principal zijn standaard één jaar geldig. U kunt de referenties van de service-principal op elk gewenst moment bijwerken of draaien.
  • Elke service-principal is gekoppeld aan een Microsoft Entra-toepassing. U kunt de service-principal voor een Kubernetes-cluster koppelen aan elke geldige Microsoft Entra-toepassingsnaam (bijvoorbeeld: https://www.contoso.org/example). De URL van de toepassing hoeft geen echt eindpunt te zijn.
  • Gebruik bij het opgeven van de client-id van de service-principal de waarde van de appId.
  • Op de agentknooppunt-VM's in het Kubernetes-cluster worden de referenties van de service-principal opgeslagen in het /etc/kubernetes/azure.json bestand.
  • Wanneer u een AKS-cluster verwijdert dat is gemaakt met behulp van de az aks create opdracht, wordt de gemaakte service-principal niet automatisch verwijderd.

    • Als u de service-principal wilt verwijderen, voert u een query uit op de servicePrincipalProfile.clientId van uw cluster en verwijdert u deze met behulp van de az ad sp delete opdracht. Vervang de waarden voor de parameter voor de -g naam en -n parameter van de resourcegroep voor de clusternaam:

      az ad sp delete --id $(az aks show -g myResourceGroup -n myAKSCluster --query servicePrincipalProfile.clientId -o tsv)

Problemen oplossen

Azure CLI slaat de referenties van de service-principal voor AKS-clusters in de cache op. Als deze referenties verlopen, treden er fouten op tijdens de implementatie van het AKS-cluster. Als u de az aks create opdracht uitvoert en een foutbericht ontvangt dat lijkt op het volgende, kan dit duiden op een probleem met de referenties van de service-principal in de cache:

Operation failed with status: 'Bad Request'.
Details: The credentials in ServicePrincipalProfile were invalid. Please see https://aka.ms/aks-sp-help for more details.
(Details: adal: Refresh request failed. Status Code = '401'.

U kunt de vervaldatum van uw referenties voor de service-principal controleren met behulp van de az ad app credential list opdracht met de "[].endDateTime" query.

az ad app credential list --id <app-id> --query "[].endDateTime" -o tsv

De standaardverlooptijd voor de aanmeldingsgegevens van de service-principal is één jaar. Als uw referenties ouder zijn dan één jaar, kunt u de bestaande referenties opnieuw instellen of een nieuwe service-principal maken.

Algemene problemen met Azure CLI oplossen

De Azure CLI kan in verschillende shell-omgevingen worden uitgevoerd, maar met kleine variaties in de indeling. Als u onverwachte resultaten hebt met Azure CLI-opdrachten, raadpleegt u De Azure CLI gebruiken.

Volgende stappen

Zie Toepassings- en service-principalobjecten voor meer informatie over Microsoft Entra-service-principals.

Zie De referenties bijwerken of roteren voor een service-principal in AKS voor meer informatie over het bijwerken van de referenties.