Configurare un'entità servizio di Azure AD per un cluster Kubernetes nel servizio contenitoreSet up an Azure AD service principal for a Kubernetes cluster in Container Service

Avviso

Si sta visualizzando la documentazione per la versione precedente del servizio contenitore di Azure.You are viewing documentation for the old version of the Azure Container Service. Il servizio contenitore di Azure è in fase di aggiornamento con l'aggiunta di nuove opzioni di distribuzione, funzionalità di gestione migliorate e vantaggi economici in Kubernetes in Azure.Azure Container Service (AKS) is being updated to add new deployment options, enhanced management capabilities, and cost benefit to Kubernetes on Azure. Per iniziare a usare tali funzionalità in anteprima, vedere AKS documentation (Documentazione del servizio contenitore di Azure).Visit the AKS documentation to start working with these preview features.

Un cluster Kubernetes richiede un'entità servizio di Azure Active Directory nel servizio contenitore di Azure per l'interazione con le API di Azure.In Azure Container Service, a Kubernetes cluster requires an Azure Active Directory service principal to interact with Azure APIs. L'entità servizio è necessaria per la gestione dinamica di risorse quali le route definite dall'utente e Azure Load Balancer di livello 4.The service principal is needed to dynamically manage resources such as user-defined routes and the Layer 4 Azure Load Balancer.

Questo articolo illustra le diverse opzioni disponibili per configurare un'entità servizio per il cluster Kubernetes.This article shows different options to set up a service principal for your Kubernetes cluster. Se, ad esempio, l'interfaccia della riga di comando di Azure 2.0 è già stata installata e configurata, è possibile eseguire il comando az acs create per creare il cluster Kubernetes e l'entità servizio contemporaneamente.For example, if you installed and set up the Azure CLI 2.0, you can run the az acs create command to create the Kubernetes cluster and the service principal at the same time.

Requisiti per l'entità servizioRequirements for the service principal

È possibile usare un'entità servizio di Azure AD esistente che soddisfi i requisiti seguenti oppure crearne una nuova.You can use an existing Azure AD service principal that meets the following requirements, or create a new one.

  • Ambito: gruppo di risorseScope: Resource group

  • Ruolo: collaboratoreRole: Contributor

  • Segreto client: deve essere una password.Client secret: Must be a password. Non è attualmente possibile usare un'entità servizio configurata per l'autenticazione del certificato.Currently, you can't use a service principal set up for certificate authentication.

Importante

Per creare un'entità servizio sono necessarie autorizzazioni sufficienti per registrare un'applicazione con il tenant di Azure AD e assegnare l'applicazione a un ruolo nella sottoscrizione.To create a service principal, you must have permissions to register an application with your Azure AD tenant, and to assign the application to a role in your subscription. È possibile verificare se si hanno a disposizione le autorizzazioni necessarie nel portale.To see if you have the required permissions, check in the Portal.

Opzione 1: creare un'entità servizio in Azure ADOption 1: Create a service principal in Azure AD

Azure mette a disposizione diversi metodi per creare un'entità servizio di Azure AD prima di distribuire il cluster Kubernetes.If you want to create an Azure AD service principal before you deploy your Kubernetes cluster, Azure provides several methods.

I comandi di esempio seguenti illustrano come eseguire questa operazione con l'interfaccia della riga di comando Azure 2.0.The following example commands show you how to do this with the Azure CLI 2.0. In alternativa è possibile creare un'entità servizio usando Azure PowerShell, il portale o altri metodi.You can alternatively create a service principal using Azure PowerShell, the portal, or other methods.

az login

az account set --subscription "mySubscriptionID"

az group create --name "myResourceGroup" --location "westus"

az ad sp create-for-rbac --role="Contributor" --scopes="/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>"

L'output è simile al seguente (visualizzato con alcune modifiche):Output is similar to the following (shown here redacted):

Creare un’entità servizio

Sono evidenziati l'ID client (appId) e il segreto client (password) usati come parametri dell'entità servizio per la distribuzione del cluster.Highlighted are the client ID (appId) and the client secret (password) that you use as service principal parameters for cluster deployment.

Specificare l'entità servizio quando si crea il cluster KubernetesSpecify service principal when creating the Kubernetes cluster

Specificare l'ID client, anche chiamato appId ovvero ID applicazione, e il segreto client (password) di un'entità servizio esistente come parametri durante la creazione del cluster Kubernetes.Provide the client ID (also called the appId, for Application ID) and client secret (password) of an existing service principal as parameters when you create the Kubernetes cluster. Verificare che l'entità servizio soddisfi i requisiti illustrati all'inizio di questo articolo.Make sure the service principal meets the requirements at the beginning this article.

È possibile specificare questi parametri durante la distribuzione del cluster Kubernetes usando l'interfaccia della riga di comando di Azure 2.0, il portale di Azure o altri metodi.You can specify these parameters when deploying the Kubernetes cluster using the Azure Command-Line Interface (CLI) 2.0, Azure portal, or other methods.

Suggerimento

Quando si specifica l'ID client, assicurarsi di usare il valore appId, non ObjectId, dell'entità servizio.When specifying the client ID, be sure to use the appId, not the ObjectId, of the service principal.

L'esempio seguente illustra un modo per passare i parametri con l'interfaccia della riga di comando di Azure 2.0.The following example shows one way to pass the parameters with the Azure CLI 2.0. Questo esempio usa il modello di avvio rapido di Kubernetes.This example uses the Kubernetes quickstart template.

  1. Scaricare il file di parametri del modello azuredeploy.parameters.json da GitHub.Download the template parameters file azuredeploy.parameters.json from GitHub.

  2. Per specificare l'entità servizio, immettere i valori per servicePrincipalClientId e servicePrincipalClientSecret nel file.To specify the service principal, enter values for servicePrincipalClientId and servicePrincipalClientSecret in the file. È anche necessario specificare valori personalizzati per dnsNamePrefix e sshRSAPublicKey,(You also need to provide your own values for dnsNamePrefix and sshRSAPublicKey. che indica la chiave pubblica SSH per l'accesso al cluster. Salvare il file.The latter is the SSH public key to access the cluster.) Save the file.

    Passare i parametri dell'entità servizio

  3. Eseguire il comando seguente, usando --parameters per impostare il percorso per il file azuredeploy.parameters.json.Run the following command, using --parameters to set the path to the azuredeploy.parameters.json file. Questo comando distribuisce il cluster in un gruppo di risorse creato dall'utente e denominato myResourceGroup nell'area Stati Uniti occidentali.This command deploys the cluster in a resource group you create called myResourceGroup in the West US region.

    az login
    
    az account set --subscription "mySubscriptionID"
    
    az group create --name "myResourceGroup" --location "westus"
    
    az group deployment create -g "myResourceGroup" --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/101-acs-kubernetes/azuredeploy.json" --parameters @azuredeploy.parameters.json
    

Opzione 2: generare un'entità servizio durante la creazione del cluster con az acs createOption 2: Generate a service principal when creating the cluster with az acs create

Se si esegue il comando az acs create per creare il cluster Kubernetes, è possibile scegliere di generare automaticamente un'entità servizio.If you run the az acs create command to create the Kubernetes cluster, you have the option to generate a service principal automatically.

Analogamente alle altre opzioni di creazione del cluster Kubernetes, è possibile specificare i parametri per un'entità servizio esistente quando si esegue az acs create.As with other Kubernetes cluster creation options, you can specify parameters for an existing service principal when you run az acs create. Quando tuttavia si omettono questi parametri, l'interfaccia della riga di comando di Azure crea automaticamente un'entità servizio da usare con il servizio contenitore.However, when you omit these parameters, the Azure CLI creates one automatically for use with Container Service. Questa operazione viene eseguita in modo trasparente durante la distribuzione.This takes place transparently during the deployment.

Il comando seguente crea un cluster Kubernetes e genera sia le chiavi SSH che le credenziali dell'entità servizio:The following command creates a Kubernetes cluster and generates both SSH keys and service principal credentials:

az acs create -n myClusterName -d myDNSPrefix -g myResourceGroup --generate-ssh-keys --orchestrator-type kubernetes

Importante

Se l'account non ha le autorizzazioni di Azure AD e della sottoscrizione necessarie per creare un'entità servizio, il comando genera un errore simile a Insufficient privileges to complete the operation.If your account doesn't have the Azure AD and subscription permissions to create a service principal, the command generates an error similar to Insufficient privileges to complete the operation.

Ulteriori considerazioniAdditional considerations

  • Se non si hanno le autorizzazioni per creare un'entità servizio nella sottoscrizione, potrebbe essere necessario chiedere all'amministratore di Azure AD o della sottoscrizione di assegnare le autorizzazioni necessarie oppure chiedere che venga creata un'entità servizio da usare con il servizio contenitore di Azure.If you don't have permissions to create a service principal in your subscription, you might need to ask your Azure AD or subscription administrator to assign the necessary permissions, or ask them for a service principal to use with Azure Container Service.

  • L'entità servizio per Kubernetes fa parte della configurazione del cluster.The service principal for Kubernetes is a part of the cluster configuration. Non usare tuttavia l'identità per distribuire il cluster.However, don't use the identity to deploy the cluster.

  • Ogni entità servizio è associata a un'applicazione Azure AD.Every service principal is associated with an Azure AD application. L'entità servizio per un cluster Kubernetes può essere associata a qualsiasi nome applicazione Azure AD valido, ad esempio https://www.contoso.org/example.The service principal for a Kubernetes cluster can be associated with any valid Azure AD application name (for example: https://www.contoso.org/example). L'URL per l'applicazione non deve essere necessariamente un endpoint reale.The URL for the application doesn't have to be a real endpoint.

  • Quando si specifica l'ID client dell'entità servizio, è possibile usare il valore di appId, come illustrato in questo articolo, o il valore name corrispondente dell'entità servizio, ad esempio https://www.contoso.org/example.When specifying the service principal Client ID, you can use the value of the appId (as shown in this article) or the corresponding service principal name (for example,https://www.contoso.org/example).

  • Nelle macchine virtuali master e agente nel cluster Kubernetes, le credenziali dell'entità servizio sono archiviate nel file /etc/kubernetes/azure.json.On the master and agent VMs in the Kubernetes cluster, the service principal credentials are stored in the file /etc/kubernetes/azure.json.

  • Quando si usa il comando az acs create per generare automaticamente l'entità servizio, le credenziali dell'entità servizio vengono scritte nel file ~/.azure/acsServicePrincipal.json nel computer usato per eseguire il comando.When you use the az acs create command to generate the service principal automatically, the service principal credentials are written to the file ~/.azure/acsServicePrincipal.json on the machine used to run the command.

  • Quando si usa il comando az acs create per generare automaticamente l'entità servizio, questa può anche eseguire l'autenticazione con un registro contenitori di Azure creato nella stessa sottoscrizione.When you use the az acs create command to generate the service principal automatically, the service principal can also authenticate with an Azure container registry created in the same subscription.

  • Le credenziali dell'entità servizio possono scadere e in questo caso i nodi del cluster passano a uno stato Non pronto.Service principal credentials can expire, causing your cluster nodes to enter a NotReady state. Per informazioni sulle opzioni di mitigazione, vedere la sezione Scadenza delle credenziali.See the Credential expiration section for mitigation information.

Scadenza delle credenzialiCredential expiration

Se non si specifica una finestra di validità personalizzata con il parametro --years quando si crea un'entità servizio, le relative credenziali sono valide per un anno dal momento della creazione.Unless you specify a custom validity window with the --years parameter when you create a service principal, its credentials are valid for 1 year from time of creation. Quando le credenziali scadono, i nodi del cluster possono passare a uno stato Non pronto.When the credential expires, your cluster nodes might enter a NotReady state.

Per verificare la data di scadenza di un'entità servizio, eseguire il comando az ad app show con il parametro --debug e cercare il valore endDate di passwordCredentials nella parte inferiore dell'output:To check the expiration date of a service principal, execute the az ad app show command with the --debug parameter, and look for the endDate value of passwordCredentials near the bottom of the output:

az ad app show --id <appId> --debug

Output (troncato):Output (shown here truncated):

...
"passwordCredentials":[{"customKeyIdentifier":null,"endDate":"2018-11-20T23:29:49.316176Z"
...

Se le credenziali dell'entità servizio sono scadute, usare il comando az ad sp reset-credentials per aggiornarle:If your service principal credentials have expired, use the az ad sp reset-credentials command to update the credentials:

az ad sp reset-credentials --name <appId>

Output:Output:

{
  "appId": "4fd193b0-e6c6-408c-a21a-803441ad2851",
  "name": "4fd193b0-e6c6-408c-a21a-803441ad2851",
  "password": "404203c3-0000-0000-0000-d1d2956f3606",
  "tenant": "72f988bf-0000-0000-0000b-2d7cd011db47"
}

Aggiornare quindi /etc/kubernetes/azure.json con le nuove credenziali in tutti i nodi del cluster e riavviare i nodi.Then, update /etc/kubernetes/azure.json with the new credentials on all cluster nodes, and restart the nodes.

Passaggi successiviNext steps