Edit

Use a service principal with Azure Kubernetes Service (AKS)

  • Article
  • 9 minutes to read

To access other Azure Active Directory (Azure AD) resources, an AKS cluster requires either an Azure Active Directory (AD) service principal or a managed identity. A service principal or managed identity is needed to dynamically create and manage other Azure resources such as an Azure load balancer or container registry (ACR).

Managed identities are the recommended way to authenticate with other resources in Azure, and is the default authentication method for your AKS cluster. For more information about using a managed identity with your cluster, see Use a system-assigned managed identity.

This article shows how to create and use a service principal for your AKS clusters.

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 need to ask your Azure AD or subscription administrator to assign the necessary permissions, or pre-create a service principal for you to use with the AKS cluster.

If you're using a service principal from a different Azure AD tenant, there are other considerations around the permissions available when you deploy the cluster. You may not have the appropriate permissions to read and write directory information. For more information, see What are the default user permissions in Azure Active Directory?

Prerequisites

Azure CLI version 2.0.59 or later. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.

Azure PowerShell version 5.0.0 or later. Run Get-InstalledModule -Name Az to find the version. If you need to install or upgrade, see Install the Azure Az PowerShell module.

Manually create a service principal

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

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

The output is similar to the following example. Copy the values for appId and password. These values are used when you create an AKS cluster in the next section.

{
  "appId": "559513bd-0c19-4c1a-87cd-851a26afd5fc",
  "displayName": "myAKSClusterServicePrincipal",
  "name": "http://myAKSClusterServicePrincipal",
  "password": "e763725a-5eee-40e8-a466-dc88d980f415",
  "tenant": "72f988bf-86f1-41af-91ab-2d7cd011db48"
}

Specify a service principal for an AKS cluster

To use an existing service principal when you create an AKS cluster using the az aks create command, use the --service-principal and --client-secret parameters to specify the appId and password from the output of the az ad sp create-for-rbac command:

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

Note

If you're using an existing service principal with customized secret, ensure the secret is not longer than 190 bytes.

Delegate access to other Azure resources

The service principal for the AKS cluster can be used to access other resources. For example, if you want to deploy your AKS cluster into an existing Azure virtual network subnet or connect to Azure Container Registry (ACR), you need to delegate access to those resources to the service principal.

To delegate permissions, create a role assignment using the az role assignment create command. Assign the appId to a particular scope, such as a resource group or virtual network resource. A role then defines what permissions the service principal has on the resource, as shown in the following example:

az role assignment create --assignee <appId> --scope <resourceScope> --role Contributor

The --scope for a resource needs to be a full resource ID, such as /subscriptions/<guid>/resourceGroups/myResourceGroup or /subscriptions/<guid>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet

Note

If you have removed the Contributor role assignment from the node resource group, the operations below may fail. Permission granted to a cluster using a system-assigned managed identity may take up 60 minutes to populate.

The following sections detail common delegations that you may need to assign.

Azure Container Registry

If you use Azure Container Registry (ACR) as your container image store, you need to grant permissions to the service principal for your AKS cluster to read and pull images. Currently, the recommended configuration is to use the az aks create or az aks update command to integrate with a registry and assign the appropriate role for the service principal. For detailed steps, see Authenticate with Azure Container Registry from Azure Kubernetes Service.

Networking

You may use advanced networking where the virtual network and subnet or public IP addresses are in another resource group. Assign the Network Contributor built-in role on the subnet within the virtual network. Alternatively, you can create a custom role with permissions to access the network resources in that resource group. For more information, see AKS service permissions.

Storage

If you need to access existing disk resources in another resource group, assign one of the following set of role permissions:

  • Create a custom role and define the following role permissions:
    • Microsoft.Compute/disks/read
    • Microsoft.Compute/disks/write
  • Or, assign the Virtual Machine Contributor built-in role on the resource group

Azure Container Instances

If you use Virtual Kubelet to integrate with AKS and choose to run Azure Container Instances (ACI) in resource group separate from the AKS cluster, the AKS cluster service principal must be granted Contributor permissions on the ACI resource group.

Other considerations

When using AKS and an Azure AD service principal, consider the following:

  • The service principal for Kubernetes is a part of the cluster configuration. However, don't use this identity to deploy the cluster.
  • By default, the service principal credentials are valid for one year. You can update or rotate the service principal credentials at any time.
  • 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 you specify the service principal Client ID, use the value of the appId.
  • On the agent node VMs in the Kubernetes cluster, the service principal credentials are stored in the file /etc/kubernetes/azure.json
  • When you delete an AKS cluster that was created by az aks create, the service principal created automatically isn't deleted.

    • To delete the service principal, query for your clusters servicePrincipalProfile.clientId and then delete it using the az ad sp delete command. Replace the values for the -g parameter for the resource group name, and -n parameter for the cluster name:

      az ad sp delete --id $(az aks show -g myResourceGroup -n myAKSCluster --query servicePrincipalProfile.clientId -o tsv)

Troubleshoot

The service principal credentials for an AKS cluster are cached by the Azure CLI. If these credentials have expired, you encounter errors during deployment of the AKS cluster. The following error message when running az aks create may indicate a problem with the cached service principal credentials:

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

Check the expiration date of your service principal credentials using the az ad app credential list command with the "[].endDateTime" query.

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

The default expiration time for the service principal credentials is one year. If your credentials are older than one year, you can reset the existing credentials or create a new service principal.

General Azure CLI troubleshooting

The Azure CLI can run in several shell environments, but with slight format variations. If you have unexpected results with Azure CLI commands, see How to use the Azure CLI successfully.

Next steps

For more information about Azure Active Directory service principals, see Application and service principal objects.

For information on how to update the credentials, see Update or rotate the credentials for a service principal in AKS.