Set up an Azure AD service principal for a Kubernetes cluster in Container Service

In Azure Container Service, a Kubernetes cluster requires an Azure Active Directory service principal to interact with Azure APIs. The service principal is needed to dynamically manage resources such as user-defined routes and the Layer 4 Azure Load Balancer.

This article shows different options to set up a service principal for your Kubernetes cluster. 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.

Requirements for the service principal

You can use an existing Azure AD service principal that meets the following requirements, or create a new one.

  • Scope: the resource group in the subscription used to deploy the Kubernetes cluster, or (less restrictively) the subscription used to deploy the cluster.

  • Role: Contributor

  • Client secret: must be a password. Currently, you can't use a service principal set up for certificate authentication.

Important

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. To see if you have the required permissions, check in the Portal.

Option 1: Create a service principal in Azure AD

If you want to create an Azure AD service principal before you deploy your Kubernetes cluster, Azure provides several methods.

The following example commands show you how to do this with the Azure CLI 2.0. 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 -n "myResourceGroupName" -l "westus"

az ad sp create-for-rbac --role="Contributor" --scopes="/subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName"

Output is similar to the following (shown here redacted):

Create a service principal

Highlighted are the client ID (appId) and the client secret (password) that you use as service principal parameters for cluster deployment.

Specify service principal when creating the Kubernetes cluster

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. Make sure the service principal meets the requirements at the beginning this article.

You can specify these parameters when deploying the Kubernetes cluster using the Azure Command-Line Interface (CLI) 2.0, Azure portal, or other methods.

Tip

When specifying the client ID, be sure to use the appId, not the ObjectId, of the service principal.

The following example shows one way to pass the parameters with the Azure CLI 2.0. This example uses the Kubernetes quickstart template.

  1. Download the template parameters file azuredeploy.parameters.json from GitHub.

  2. To specify the service principal, enter values for servicePrincipalClientId and servicePrincipalClientSecret in the file. (You also need to provide your own values for dnsNamePrefix and sshRSAPublicKey. The latter is the SSH public key to access the cluster.) Save the file.

    Pass service principal parameters

  3. Run the following command, using --parameters to set the path to the azuredeploy.parameters.json file. 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
    

Option 2: Generate a service principal when creating the cluster with az acs create

If you run the az acs create command to create the Kubernetes cluster, you have the option to generate a service principal automatically.

As with other Kubernetes cluster creation options, you can specify parameters for an existing service principal when you run az acs create. However, when you omit these parameters, the Azure CLI creates one automatically for use with Container Service. This takes place transparently during the deployment.

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
Important

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.

Additional considerations

  • 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.

  • The service principal for Kubernetes is a part of the cluster configuration. However, don't use the identity to deploy the cluster.

  • Every service principal is associated with an Azure AD application. The service principal for a Kubernetes cluster can be associated with any valid Azure AD application name (for example: https://www.contoso.org/example). The URL for the application doesn't have to be a real endpoint.

  • 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).

  • On the master and agent VMs in the Kubernetes cluster, the service principal credentials are stored in the file /etc/kubernetes/azure.json.

  • 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.

  • 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.

Next steps