Applications running on the POD on Azure Container Service (AKS/ACS Engine) require access to identities in Azure Active Directory (AAD)to access resources that use an identity provider. AAD provides a construct called a Service Principal that allows applications to assume identities with limited permissions, and Managed Service Identity (MSI) - automatically generated and rotated credentials that easily retrieved by an application at run-time to authenticate as a service principal. An cluster admin configures the Azure Identity Binding to the Pod. Without any change of auth code the application running on the pod works on the cluster.
The detailed design of the project can be found in the following docs:
This controller watches for pod changes through the api server and caches pod to admin configured azure identity map.
The authorization request of fetching Service Principal Token from MSI endpoint is sent to a standard Instance Metadata endpoint which is redirected to the NMI pod by adding ruled to redirect POD CIDR traffic with metadata endpoint IP on port 80 to be sent to the NMI endpoint. The NMI server identifies the pod based on the remote address of the request and then queries the k8s (through MIC) for a matching azure identity. It then make a adal request to get the token for the client id and returns as a reponse to the request. If the request had client id as part of the query it validates it againsts 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 a adal request to get a token for the resource in the request, returns the token and the clientid as a reponse to the request.
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"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)
A running k8s cluster on Azure using AKS or ACS Engine
Deploy the infrastructure with the following command to deploy MIC, NMI, and the MIC CRDs.
kubectl create -f https://raw.githubusercontent.com/Azure/aad-pod-identity/master/deploy/infra/deployment.yaml
Pod Identity requires two components:
- Managed Identity Controller (MIC). A pod that binds Azure Ids to other pods - creates azureAssignedIdentity CRD.
- Node Managed Identity (NMI). Identifies the pod based on the remote address of the incoming request, and then queries k8s (through MIC) for a matching Azure Id. It then makes an adal request to get the token for the client id and returns as a reponse to the request. Implemented as a DaemonSet.
If you have RBAC enabled, use the following deployment instead:
kubectl create -f https://raw.githubusercontent.com/Azure/aad-pod-identity/master/deploy/infra/deployment-rbac.yaml
Get the client id and resource id for the identity
az identity create -g <resourcegroup> -n <managedidentity-resourcename>
Using the principalid from the last step, assign reader role to new identity for this resource group
az role assignment create --role Reader --assignee <principalid> --scope /subscriptions/<subscriptionid>/resourcegroups/<resourcegroup>
This step is only required if you are using User assigned MSI.
MIC uses the service principal credentials stored within the the AKS cluster to access azure resources. This service principal needs to have Microsoft.ManagedIdentity/userAssignedIdentities/*/assign/action permission on the identity for usage with User assigned MSI. If your identity is created in the same resource group as that of the AKS nodes (typically this resource group is prefixed with 'MC_' string and is automatically generated when you create the cluster), you can skip the next steps.
-
Find the service principal used by your cluster - please refer the AKS docs to figure out the service principle app Id. For example, if your cluster uses automatically generated service principal, the ~/.azure/aksServicePrincipal.json file in the machine from which you created the AKS cluster has the required information.
-
Assign the required permissions - the following command can be used to assign the required permission:
az role assignment create --role "Managed Identity Operator" --assignee <sp id> --scope <full id of the managed identity>
Edit and save this as aadpodidentity.yaml
Set type: 0 for User Assigned MSI; type: 1 for Service Principal
apiVersion: "aadpodidentity.k8s.io/v1"
kind: AzureIdentity
metadata:
name: <a-idname>
spec:
type: 0
ResourceID: /subscriptions/<subid>/resourcegroups/<resourcegroup>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<managedidentity-resourcename>
ClientID: <clientid>
kubectl create -f aadpodidentity.yaml
Edit and save this as aadpodidentitybinding.yaml. Note the AzureIdentity name must match the one chosen in aadpodidentity.yaml.
apiVersion: "aadpodidentity.k8s.io/v1"
kind: AzureIdentityBinding
metadata:
name: demo1-azure-identity-binding
spec:
AzureIdentity: <a-idname>
Selector: <label value to match>
kubectl create -f aadpodidentitybinding.yaml
The name of the identity which we created earlier needs to be filled in AzureIdentity. For a pod to match a binding, it should have a label with the key 'aadpodidbinding' whose value matches the Selector field in the binding above.
Here an example pod with the label specified:
$ kubectl get po busybox0 --show-labels
NAME READY STATUS RESTARTS AGE LABELS
busybox0 1/1 Running 10 10h aadpodidbinding=select_it,app=busybox0
This 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"
To deploy the demo app, ensure you have completed the above prerequisite steps!
Update the deploy/demo/deployment.yaml arguments with your subscription, clientID and resource group.
Make sure your identity with the client ID has reader permission to the resource group provided in the input.
kubectl create -f deploy/demo/deployment.yaml
There's also a detailed tutorial here.
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.