AAD Pod Identity enables Kubernetes applications to access cloud resources securely with Azure Active Directory (AAD).
Using Kubernetes primitives, administrators configure identities and bindings to match pods. Then without any code modifications, your containerized applications can leverage anything in the cloud that depends on AAD as an identity provider.
You will need a Kubernetes cluster running on Azure, either managed by AKS or provisioned with AKS Engine.
AAD Pod Identity consists of the Managed Identity Controller (MIC) and Node Managed Identity (NMI) components in a Kubernetes deployment. For more information, see Components.
Run this command to create the aad-pod-identity deployment on an RBAC-enabled cluster:
kubectl create -f https://raw.githubusercontent.com/Azure/aad-pod-identity/master/deploy/infra/deployment-rbac.yamlOr run this command to deploy to a non-RBAC cluster:
kubectl create -f https://raw.githubusercontent.com/Azure/aad-pod-identity/master/deploy/infra/deployment.yamlRun this Azure CLI command, and take note of the clientId and id values it returns:
az identity create -g <resourcegroup> -n <name> -o jsonSave this Kubernetes manifest to a file named aadpodidentity.yaml:
apiVersion: "aadpodidentity.k8s.io/v1"
kind: AzureIdentity
metadata:
name: <a-idname>
spec:
type: 0
ResourceID: /subscriptions/<subid>/resourcegroups/<resourcegroup>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<name>
ClientID: <clientId>Replace the placeholders with your user identity values. Set type: 0 for user-assigned MSI or type: 1 for Service Principal.
Finally, save your changes to the file, then create the AzureIdentity resource in your cluster:
kubectl create -f aadpodidentity.yamlBy default, AAD Pod Identity matches pods to identities across namespaces. To match only pods in the namespace containing AzureIdentity, use one of these techniques:
- Attach a
aadpodidentity.k8s.io/Behavior: namespacedannotation to eachAzureIdentityresource. - Add the
--forceNamespaced=truecommand line argument or set theFORCENAMESPACED=trueenvironment variable when starting both the MIC and NMI components.
Save this Kubernetes manifest to a file named aadpodidentitybinding.yaml:
apiVersion: "aadpodidentity.k8s.io/v1"
kind: AzureIdentityBinding
metadata:
name: demo1-azure-identity-binding
spec:
AzureIdentity: <a-idname>
Selector: <label value to match>Replace the placeholders with your values. Ensure that the AzureIdentity name matches the one in aadpodidentity.yaml.
Finally, save your changes to the file, then create the AzureIdentityBinding resource in your cluster:
kubectl create -f aadpodidentitybinding.yamlFor a pod to match an identity binding, it needs a label with the key aadpodidbinding whose value is that of the Selector: field in the binding. Here is an example pod with a label:
$ kubectl get po busybox0 --show-labels
NAME READY STATUS RESTARTS AGE LABELS
busybox0 1/1 Running 10 10h aadpodidbinding=select_it,app=busybox0This pod will match the binding below:
apiVersion: "aadpodidentity.k8s.io/v1"
kind: AzureIdentityBinding
metadata:
name: test-azure-id-binding
spec:
AzureIdentity: "test-azure-identity"
Selector: "select_it"This step is only required for user-assigned MSI.
The MIC uses the service principal credentials stored in the cluster to access Azure resources. This service principal needs Microsoft.ManagedIdentity/userAssignedIdentities/\*/assign/action permission on the identity to work with user-assigned MSI.
If the Azure identity is in the same resource group as your AKS cluster nodes, you can skip this section. (For AKS, a resource group was added with an MC_ prefix when you created the cluster.) Otherwise, follow these steps to assign the required permissions:
-
Find the service principal used by your cluster. Please refer to the AKS docs for details. For example, if you didn't specify a service principal to the
az aks createcommand, it will have generated one in the~/.azure/aksServicePrincipal.jsonfile. -
Assign the required permissions with the following command:
az role assignment create --role "Managed Identity Operator" --assignee <sp id> --scope <full id of the managed identity>Dive deeper into AAD Pod Identity by following the detailed Tutorial.
The demonstration program illustrates how, after setting the identity and binding, the sample app can list VMs in an Azure resource group. To deploy the demo, please ensure you have completed the Prerequisites and understood the previous sections in this document.
The demo program can be found here: cmd/demo.
Here are some excerpts from the demo.
spt, err := adal.NewServicePrincipalTokenFromMSI(msiEndpoint, resource)import "github.com/Azure/go-autorest/autorest/azure/auth"
authorizer, err := auth.NewAuthorizerFromEnvironment()
if err != nil {
logger.Errorf("failed NewAuthorizerFromEnvironment: %+v", authorizer)
return
}
vmClient := compute.NewVirtualMachinesClient(subscriptionID)
vmClient.Authorizer = authorizer
vmlist, err := vmClient.List(context.Background(), resourceGroup)The user-assigned identity needs the "Reader" role on the resource group to list its VMs. Provide the principalId from the user-assigned identity to this command:
az role assignment create --role Reader --assignee <principalid> --scope /subscriptions/<subscriptionid>/resourcegroups/<resourcegroup>Update the deploy/demo/deployment.yaml arguments with your subscription, clientID and resource group, then create the demo deployment:
kubectl create -f deploy/demo/deployment.yamlDetails of AAD Pod Identity's design can be found in these documents:
AAD Pod Identity has two components: the Managed Identity Controller (MIC) and the Node Managed Identity (NMI) pod.
The Managed Identity Controller (MIC) is a Kubernetes custom resource that watches for changes to pods, identities, and bindings through the Kubernetes API server. When it detects a relevant change, the MIC adds or deletes assigned identities as needed.
Specifically, when a pod is scheduled, the MIC assigns an identity to the underlying VM during the creation phase. When the pod is deleted, it removes the assigned identity from the VM. The MIC takes similar actions when identities or bindings are created or deleted.
The authorization request to fetch a Service Principal Token from an MSI endpoint is sent to a standard Instance Metadata endpoint which is redirected to the NMI pod. The redirection is accomplished by adding rules to redirect POD CIDR traffic with metadata endpoint IP on port 80 to the NMI endpoint. The NMI server identifies the pod based on the remote address of the request and then queries Kubernetes (through MIC) for a matching Azure identity. NMI then makes an Azure Active Directory Authentication Library (ADAL) request to get the token for the client id and returns it as a response. If the request had client id as part of the query, it is validated against the admin-configured client id.
Similarly, a host can make an authorization request to fetch Service Principal Token for a resource directly from the NMI host endpoint (http://127.0.0.1:2579/host/token/). The request must include the pod namespace podns and the pod name podname in the request header and the resource endpoint of the resource requesting the token. The NMI server identifies the pod based on the podns and podname in the request header and then queries k8s (through MIC) for a matching azure identity. Then NMI makes an ADAL request to get a token for the resource in the request, returning the token and the clientid as a response.
Here is an example cURL command:
curl http://127.0.0.1:2579/host/token/?resource=https://vault.azure.net -H "podname: nginx-flex-kv-int" -H "podns: default"The NMI pods modify the nodes' iptables to intercept calls to Azure Instance Metadata endpoint. This allows NMI to insert identities assigned to a pod before executing the request on behalf of the caller.
These iptables entries will be cleaned up when the pod-identity pods are uninstalled. However, if the pods are terminated for unexpected reasons, the iptables entries can be removed with these commands on the node:
# remove the custom chain reference
iptables -t nat -D PREROUTING -j aad-metadata
# flush the custom chain
iptables -t nat -F aad-metadata
# remove the custom chain
iptables -t nat -X aad-metadataLearn how to debug this project at the Debugging wiki page.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.