Usare un entità servizio con il servizio Azure Kubernetes (AKS)

1. Creare un'entità servizio usando il comando az ad sp create-for-rbac.

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

   L'output dovrebbe essere simile all'output di esempio seguente:

   {
     "appId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
     "displayName": "myAKSClusterServicePrincipal",
     "name": "http://myAKSClusterServicePrincipal",
     "password": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
     "tenant": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
   }
   

2. Copiare i valori per appId e password dall'output. Questi vengono usati durante la creazione di un cluster del servizio Azure Kubernetes nella sezione successiva.

1. Creare un'entità servizio usando il comando New-AzADServicePrincipal.

   New-AzADServicePrincipal -DisplayName myAKSClusterServicePrincipal -OutVariable sp
   

   L'output dovrebbe essere simile all'output di esempio seguente:

   Secret                : System.Security.SecureString
   ServicePrincipalNames : {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, http://myAKSClusterServicePrincipal}
   ApplicationId         : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   ObjectType            : ServicePrincipal
   DisplayName           : myAKSClusterServicePrincipal
   Id                    : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   Type                  :
   

   I valori vengono archiviati in una variabile usata durante la creazione di un cluster del servizio Azure Kubernetes nella sezione successiva.

2. Decrittografare il valore archiviato nella stringa sicura segreto usando il comando seguente.

   $BSTR = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($sp.Secret)
   [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($BSTR)
   

• Usare un'entità servizio esistente per un nuovo cluster del servizio Azure Kubernetes usando il comando az aks create, e usare i parametri --service-principal e --client-secret per specificare il appId e password dall'output ricevuto nella sezione precedente.

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

  Nota

  Se si usa un'entità servizio esistente con segreto personalizzato, assicurarsi che il segreto non sia più lungo di 190 byte.

1. Convertire l'entità servizio ApplicationId e Secret in un oggetto PSCredential usando il comando seguente.

   $Cred = New-Object -TypeName System.Management.Automation.PSCredential ($sp.ApplicationId, $sp.Secret)
   

2. Usare un'entità servizio esistente per un nuovo cluster del servizio Azure Kubernetes usando il comando New-AzAksCluster e specificare il parametro ServicePrincipalIdAndSecret con la PSCredential oggetto creato in precedenza come valore.

   New-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster -ServicePrincipalIdAndSecret $Cred
   

   Nota

   Se si usa un'entità servizio esistente con segreto personalizzato, assicurarsi che il segreto non sia più lungo di 190 byte.

• Creare un'assegnazione di ruolo usando il comando az role assignment create. Specificare il valore dell'ID app dell'entità servizio per il parametro appId. Specificare l'ambito per l'assegnazione di ruolo, ad esempio un gruppo di risorse o una risorsa di rete virtuale. L'assegnazione di ruolo determina quali autorizzazioni sono disponibili per l'entità servizio per la risorsa e in quale ambito.

  Ad esempio, per assegnare all'entità servizio le autorizzazioni per accedere ai segreti in un insieme di credenziali delle chiavi, è possibile usare il comando seguente:

  az role assignment create \
      --assignee <appId> \
      --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KeyVault/vaults/<vault-name>" \
      --role "Key Vault Secrets User"
  

  Nota

  L'oggetto --scope per una risorsa deve essere un ID risorsa completo, ad esempio /subscriptions/<guid>/resourceGroups/myResourceGroup o /subscriptions/<guid >/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet.

• Creare un'assegnazione di ruolo usando il comando New-AzRoleAssignment. Specificare il valore dell'ID app dell'entità servizio per il parametro ApplicationId. Specificare l'ambito per l'assegnazione di ruolo, ad esempio un gruppo di risorse o una risorsa di rete virtuale. L'assegnazione di ruolo determina quali autorizzazioni sono disponibili per l'entità servizio per la risorsa e in quale ambito.

  Ad esempio, per assegnare all'entità servizio le autorizzazioni per accedere ai segreti in un insieme di credenziali delle chiavi, è possibile usare il comando seguente:

  New-AzRoleAssignment -ApplicationId <ApplicationId> `
      -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KeyVault/vaults/<vault-name>" `
      -RoleDefinitionName "Key Vault Secrets User"
  

  Nota

  L'oggetto Scope per una risorsa deve essere un ID risorsa completo, ad esempio /subscriptions/<guid>/resourceGroups/myResourceGroup o /subscriptions/<guid >/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet

Se si usa Registro Azure Container come archivio immagini del contenitore, è necessario concedere autorizzazioni all'entità servizio per il cluster del servizio Azure Kubernetes per leggere ed eseguire il pull delle immagini. È consigliabile usare il comando az aks create o az aks update per l'integrazione con un registro e assegnare il ruolo appropriato per l'entità servizio. Per i passaggi dettagliati, vedere Eseguire l'autenticazione con Registro Azure Container dal servizio Azure Kubernetes.

Se si usa Registro Azure Container come archivio immagini del contenitore, è necessario concedere autorizzazioni all'entità servizio per il cluster del servizio Azure Kubernetes per leggere ed eseguire il pull delle immagini. È consigliabile usare il comando New-AzAksCluster o Set-AzAksCluster per l'integrazione con un registro e assegnare il ruolo appropriato per l'entità servizio. Per i passaggi dettagliati, vedere Eseguire l'autenticazione con Registro Azure Container dal servizio Azure Kubernetes.

Quando si usa il servizio Azure Kubernetes e un'entità servizio Microsoft Entra, tenere presente quanto segue:

• L'entità servizio per Kubernetes fa parte della configurazione del cluster, ma non usa questa identità per distribuire il cluster.
• Per impostazione predefinita, le credenziali dell'entità servizio sono valide per un anno. È possibile aggiornare o ruotare le credenziali dell'entità servizio in qualsiasi momento.
• Ogni entità servizio è associata a un'applicazione Microsoft Entra. È possibile associare l'entità servizio per un cluster Kubernetes a qualsiasi nome dell'applicazione Microsoft Entra valido( ad esempio: https://www.contoso.org/example). L'URL per l'applicazione non deve essere necessariamente un endpoint reale.
• Quando si specifica l'ID client dell'entità servizio, usare il valore di appId.
• Nelle macchine virtuali del nodo agente nel cluster Kubernetes le credenziali dell'entità servizio vengono archiviate nel file /etc/kubernetes/azure.json.
• Quando si elimina un cluster del servizio Azure Kubernetes creato usando il comando az aks create, l'entità servizio creata non viene eliminata automaticamente.

  • Per eliminare l'entità servizio, eseguire una query per servicePrincipalProfile.clientId del cluster ed eliminarla usando il comando az ad sp delete. Sostituire i valori per il parametro -g per il nome del gruppo di risorse e -n parametro per il nome del cluster:

    az ad sp delete --id $(az aks show \
      --resource-group myResourceGroup \
      --name myAKSCluster \
      --query servicePrincipalProfile.clientId \
      --output tsv)
    

Quando si usa il servizio Azure Kubernetes e un'entità servizio Microsoft Entra, tenere presente quanto segue:

• L'entità servizio per Kubernetes fa parte della configurazione del cluster, ma non usa questa identità per distribuire il cluster.
• Per impostazione predefinita, le credenziali dell'entità servizio sono valide per un anno. È possibile aggiornare o ruotare le credenziali dell'entità servizio in qualsiasi momento.
• Ogni entità servizio è associata a un'applicazione Microsoft Entra. È possibile associare l'entità servizio per un cluster Kubernetes a qualsiasi nome dell'applicazione Microsoft Entra valido( ad esempio: https://www.contoso.org/example). L'URL per l'applicazione non deve essere necessariamente un endpoint reale.
• Quando si specifica l'ID client dell'entità servizio, usare il valore di ApplicationId.
• Nelle macchine virtuali del nodo agente nel cluster Kubernetes le credenziali dell'entità servizio vengono archiviate nel file /etc/kubernetes/azure.json.
• Quando si elimina un cluster del servizio Azure Kubernetes creato usando New-AzAksCluster, l'entità servizio creata non viene eliminata automaticamente.

  • Per eliminare l'entità servizio, eseguire una query per servicePrincipalProfile.ClientId del cluster ed eliminarla usando il comando Remove-AzADServicePrincipal. Sostituire i valori per il parametro -ResourceGroupName per il nome del gruppo di risorse e il parametro -Name per il nome del cluster:

    $ClientId = (Get-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster ).ServicePrincipalProfile.ClientId
    Remove-AzADServicePrincipal -ApplicationId $ClientId
    

L'interfaccia della riga di comando di Azure memorizza nella cache le credenziali dell'entità servizio per i cluster del servizio Azure Kubernetes. Se queste credenziali scadono, è possibile che si verifichino errori durante la distribuzione del cluster del servizio Azure Kubernetes. Se si esegue il comando az aks create e si riceve un messaggio di errore simile al seguente, potrebbe indicare un problema con le credenziali dell'entità servizio memorizzate nella 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'.

È possibile controllare la data di scadenza delle credenziali dell'entità servizio usando il comando az ad app credential list con la query "[].endDateTime".

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

La scadenza predefinita per le credenziali dell'entità servizio è di un anno. Se le credenziali sono precedenti a un anno, è possibile reimpostare le credenziali esistenti o creare una nuova entità servizio.

Risoluzione dei problemi generali dell'interfaccia della riga di comando di Azure

L'interfaccia della riga di comando di Azure può essere eseguita in diversi ambienti della shell, ma con lievi variazioni di formato. Se si hanno risultati imprevisti con i comandi dell'interfaccia della riga di comando di Azure, vedere Come usare correttamente l'interfaccia della riga di comando di Azure.

Azure PowerShell memorizza nella cache le credenziali dell'entità servizio per i cluster del servizio Azure Kubernetes. Se queste credenziali scadono, si verificano errori durante la distribuzione del cluster del servizio Azure Kubernetes. Se si esegue il comando New-AzAksCluster e si riceve un messaggio di errore simile al seguente, potrebbe indicare un problema con le credenziali dell'entità servizio memorizzate nella 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'.

È possibile controllare la data di scadenza delle credenziali dell'entità servizio usando il comando Get-AzADAppCredential. L'output mostra l'oggetto StartDateTime delle credenziali.

Get-AzADAppCredential -ApplicationId <ApplicationId> 

La scadenza predefinita per le credenziali dell'entità servizio è di un anno. Se le credenziali sono precedenti a un anno, è possibile reimpostare le credenziali esistenti o creare una nuova entità servizio.