Service principals with Azure Container Service (AKS)

An AKS 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 for setting up a service principal for your Kubernetes cluster in AKS.

Before you begin

To create an Azure AD 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. If you don't have the necessary permissions, you might need to ask your Azure AD or subscription administrator to assign the necessary permissions, or pre-create a service principal for the Kubernetes cluster.

You also need the Azure CLI version 2.0.21 or later installed and configured. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.

Create SP with AKS cluster

When deploying an AKS cluster with the az aks create command, you have the option to automatically generate a service principal.

In the following example, an AKS cluster is created, and because an existing service principal is not specified, a service principal is created for the cluster. In order to complete this operation, your account must have the proper rights for creating a service principal.

az aks create --name myK8SCluster --resource-group myResourceGroup --generate-ssh-keys

Use an existing SP

An existing Azure AD service principal can be used or pre-created for use with an AKS cluster. This is helpful when deploying a cluster from the Azure portal where you are required to provide the service principal information. When using an existing service principal, the client secret must be configured as a password.

Pre-create a new SP

To create the service principal with the Azure CLI, use the az ad sp create-for-rbac command.

az ad sp create-for-rbac --skip-assignment

Output is similar to the following. Take note of the appId and password. These values are used when creating an AKS cluster.

{
  "appId": "7248f250-0000-0000-0000-dbdeb8400d85",
  "displayName": "azure-cli-2017-10-15-02-20-15",
  "name": "http://azure-cli-2017-10-15-02-20-15",
  "password": "77851d2c-0000-0000-0000-cb3ebc97975a",
  "tenant": "72f988bf-0000-0000-0000-2d7cd011db47"
}

Use an existing SP

When using a pre-created service principal, provide the appId and password as argument values to the az aks create command.

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

If you're deploying an AKS cluster by using the Azure portal, enter the appId value in the Service principal client ID field, and the password value in the Service principal client secret field in the AKS cluster configuration form.

Image of browsing to Azure Vote

Additional considerations

When working with AKS and Azure AD service principals, keep the following in mind.

  • 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 node VMs in the Kubernetes cluster, the service principal credentials are stored in the file /etc/kubernetes/azure.json.
  • When you use the az aks 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 aks create command to generate the service principal automatically, the service principal can also authenticate with an [Azure container registry][acr-into] created in the same subscription.
  • When deleting an AKS cluster which was created by az aks create, the service principal which was created automatically will not be deleted. You can use az ad sp delete --id $clientID to delete it.

Next steps

For more information about Azure Active Directory service principals, see the Azure AD applications documentation.