Abilitare l'autenticazione dell'identità gestita di Azure per i cluster Kubernetes con kubelogin

  • Articolo

L'integrazione di Microsoft Entra gestita dal servizio Azure Kubernetes semplifica il processo di integrazione di Microsoft Entra. In precedenza, dovevi creare un'app client e server, e il tenant di Microsoft Entra doveva concedere le autorizzazioni di ruolo Directory Readers. Ora, il provider di risorse del servizio Azure Kubernetes gestisce automaticamente le app client e server per te.

Gli amministratori del cluster possono configurare il controllo degli accessi in basati sul ruolo di Kubernetes (Kubernetes RBAC), in base all'identità o all'appartenenza al gruppo di directory di un utente. L'autenticazione Di Microsoft Entra viene fornita ai cluster del servizio Azure Kubernetes con OpenID Connect. OpenID Connect è un livello di gestione delle identità basato sul protocollo OAuth 2.0. Per altre informazioni su OpenID Connect, vedere la documentazione OpenID Connect.

Scopri di più sul flusso di integrazione di Microsoft Entra nella documentazione di Microsoft Entra.

Questo articolo fornisce informazioni dettagliate su come abilitare e usare le identità gestite per le risorse di Azure con il cluster del servizio Azure Kubernetes.

Limiti

Di seguito sono riportati i vincoli che integrano l'autenticazione dell'identità gestita di Azure nel servizio Azure Kubernetes.

  • L'integrazione non può essere disabilitata una volta aggiunta.
  • I downgrade da un cluster integrato ai cluster Microsoft Entra ID legacy non sono supportati.
  • I cluster senza il supporto del controllo degli accessi in base al ruolo di Kubernetes non sono in grado di aggiungere l'integrazione.

Operazioni preliminari

Per installare correttamente il componente aggiuntivo del servizio Azure Kubernetes per l'identità gestita, è necessario soddisfare i requisiti seguenti.

  • Devi aver installato e configurato l’interfaccia della riga di comando di Azure versione 2.29.0 o successiva. Eseguire az --version per trovare la versione. Se è necessario eseguire l'installazione o l'aggiornamento, vedere Installare l'interfaccia della riga di comando di Azure.
  • Hai bisogno di kubectl con una versione minima di 1.18.1 o kubelogin. Con l'interfaccia della riga di comando di Azure e il modulo Azure PowerShell, questi due comandi vengono inclusi e gestiti automaticamente. Ciò significa che vengono aggiornati per impostazione predefinita e l'esecuzione di az aks install-cli non è necessaria o consigliata. Se usi una pipeline automatizzata, devi gestire gli aggiornamenti per la versione corretta o più recente. La differenza tra le versioni secondarie di Kubernetes e kubectl non deve essere più di una versione. In caso contrario, si verificano problemi di autenticazione nella versione errata.
  • Se usi helm, ti serve una versione minima di helm 3.3.
  • Per questa configurazione devi disporre di un gruppo Microsoft Entra per il cluster. Questo gruppo viene registrato come gruppo di amministrazione nel cluster per concedere autorizzazioni di amministratore. Se non disponi di un gruppo Microsoft Entra esistente, puoi crearne uno usando il comando az ad group create.

Nota

I cluster integrati di Microsoft Entra che usano una versione di Kubernetes più recente rispetto alla versione 1.24 usano automaticamente il formato kubelogin. A partire da Kubernetes versione 1.24, il formato predefinito della credenziale clusterUser per i cluster Microsoft Entra ID è exec, che richiede il binario kubelogin nel PERCORSO di esecuzione. Non esistono modifiche di comportamento per i cluster non Microsoft Entra o i cluster Microsoft Entra ID che eseguono una versione precedente alla 1.24. Il kubeconfig scaricato esistente continua a funzionare. Quando si ottengono le credenziali clusterUser per sovrascrivere la modifica del comportamento predefinito, è incluso un formatofacoltativo di parametro di query. Puoi specificare in modo esplicito il formato per azure se devi mantenere il formato kubeconfig precedente.

Abilita l'integrazione nel tuo cluster del servizio Azure Kubernetes

Creare un nuovo cluster

  1. Creare un gruppo di risorse di Azure usando il comando az group create.

    az group create --name myResourceGroup --location centralus

  2. Creare un cluster del servizio Azure Kubernetes e abilitare l'accesso amministrativo per il gruppo Microsoft Entra usando il comando az aks create.

    az aks create -g myResourceGroup -n myManagedCluster --enable-aad --aad-admin-group-object-ids <id> [--aad-tenant-id <id>]

    Una creazione corretta di un cluster Microsoft Entra ID gestito dal servizio Azure Kubernetes include la sezione seguente nel corpo della risposta:

    "AADProfile": {
    "adminGroupObjectIds": [
    "5d24****-****-****-****-****afa27aed"
    ],
    "clientAppId": null,
    "managed": true,
    "serverAppId": null,
    "serverAppSecret": null,
    "tenantId": "72f9****-****-****-****-****d011db47"
}

Usare un cluster esistente

Abilita l'integrazione di Microsoft Entra gestita dal servizio Azure Kubernetes nel tuo cluster abilitato per il controllo degli accessi in base al ruolo di Kubernetes esistente usando il comando az aks update. Assicurati di impostare il gruppo di amministrazione per mantenere l'accesso al tuo cluster.

az aks update -g MyResourceGroup -n myManagedCluster --enable-aad --aad-admin-group-object-ids <id-1>,<id-2> [--aad-tenant-id <id>]

Un'attivazione corretta di un cluster Microsoft Entra ID gestito dal servizio Azure Kubernetes include la sezione seguente nel corpo della risposta:

"AADProfile": {
    "adminGroupObjectIds": [
        "5d24****-****-****-****-****afa27aed"
    ],
    "clientAppId": null,
    "managed": true,
    "serverAppId": null,
    "serverAppSecret": null,
    "tenantId": "72f9****-****-****-****-****d011db47"
    }

Eseguire la migrazione del cluster legacy all'integrazione

Se il tuo cluster usa l'integrazione legacy di Microsoft Entra, puoi eseguire l'aggiornamento all'integrazione di Microsoft Entra gestita dal servizio Azure Kubernetes usando il comando az aks update.

Avviso

I cluster di livello gratuito possono riscontrare tempi di inattività del server API durante l'aggiornamento. È consigliabile eseguire l'aggiornamento durante le ore non lavorative. Dopo l'aggiornamento, il contenuto kubeconfig cambia. Devi eseguire az aks get-credentials --resource-group <AKS resource group name> --name <AKS cluster name> per unire le nuove credenziali nel file kubeconfig.

az aks update -g myResourceGroup -n myManagedCluster --enable-aad --aad-admin-group-object-ids <id> [--aad-tenant-id <id>]

Una corretta migrazione di un cluster Microsoft Entra ID gestito dal servizio Azure Kubernetes include la sezione seguente nel corpo della risposta:

"AADProfile": {
    "adminGroupObjectIds": [
        "5d24****-****-****-****-****afa27aed"
    ],
    "clientAppId": null,
    "managed": true,
    "serverAppId": null,
    "serverAppSecret": null,
    "tenantId": "72f9****-****-****-****-****d011db47"
    }

Accedi al cluster abilitato

  1. Ottieni le credenziali utente per accedere al cluster usando il comando az aks get-credentials.

    az aks get-credentials --resource-group myResourceGroup --name myManagedCluster

  2. Segui le istruzioni per accedere.

  3. Imposta kubelogin per usare l'interfaccia della riga di comando di Azure.

    kubelogin convert-kubeconfig -l azurecli

  4. Visualizza i nodi nel cluster usando il comando kubectl get nodes.

    kubectl get nodes

Accesso non interattivo con kubelogin

Esistono alcuni scenari non interattivi che non supportano kubectl. In questi casi, usa kubelogin per connetterti al cluster con credenziali dell'entità servizio non interattive per eseguire pipeline di integrazione continua.

Nota

I cluster integrati di Microsoft Entra che usano una versione di Kubernetes più recente rispetto alla versione 1.24 usano automaticamente il formato kubelogin. A partire da Kubernetes versione 1.24, il formato predefinito della credenziale clusterUser per i cluster Microsoft Entra ID è exec, che richiede il binario kubelogin nel PERCORSO di esecuzione. Non esistono modifiche di comportamento per i cluster non Microsoft Entra o i cluster Microsoft Entra ID che eseguono una versione precedente alla 1.24. Il kubeconfig scaricato esistente continua a funzionare. Quando si ottengono le credenziali clusterUser per sovrascrivere la modifica del comportamento predefinito, è incluso un formatofacoltativo di parametro di query. Puoi specificare in modo esplicito il formato per azure se devi mantenere il formato kubeconfig precedente.

  • Quando ottieni le credenziali clusterUser, puoi usare il parametro di query format per sovrascrivere il comportamento predefinito. Puoi impostare il valore su azure per usare il formato kubeconfig originale:

    az aks get-credentials --format azure

  • Se il tuo cluster integrato Microsoft Entra usa Kubernetes versione 1.24 o precedente, devi convertire manualmente il formato kubeconfig.

    export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig

Nota

Se visualizzi il messaggio di errore: Il plug-in di autenticazione di Azure è stato rimosso., devi eseguire il comando kubelogin convert-kubeconfig per convertire manualmente il formato kubeconfig.

Per ulteriori informazioni, puoi fare riferimento a Problemi noti di Azure Kubelogin.

Risolvere i problemi di accesso

Importante

Il passaggio descritto in questa sezione suggerisce un metodo di autenticazione alternativo rispetto alla normale autenticazione del gruppo Microsoft Entra. Utilizza questa opzione solo in caso di emergenza.

Se non disponi dell'accesso amministrativo a un gruppo Microsoft Entra valido, puoi seguire questa soluzione alternativa. Accedi con un account membro del ruolo di amministratore del cluster del servizio Azure Kubernetes e concedi al tuo gruppo o tenant le credenziali di amministratore per accedere al cluster.

Passaggi successivi