Documentation

AAD Pod Identity enables Kubernetes applications to access cloud resources securely with Azure Active Directory using User-assigned managed identity and Service Principal.

Note: Configuring system-assigned managed identity with AAD Pod Identity to access cloud resources is not supported.

Using Kubernetes primitives, administrators configure identities and bindings to match pods. Then without any code modifications, your containerized applications can leverage any resource in the cloud that depends on AAD as an identity provider.

v1.8.x Breaking Change

  • The API version of Pod Identity’s CRDs (AzureIdentity, AzureIdentityBinding, AzureAssignedIdentity, AzurePodIdentityException) have been upgraded from apiextensions.k8s.io/v1beta1 to apiextensions.k8s.io/v1. For Kubernetes clsuters with < 1.16, apiextensions.k8s.io/v1 CRDs would not work. You can either:

    1. Continue using AAD Pod Identity v1.7.5 or
    2. Upgrade your cluster to 1.16+, then upgrade AAD Pod Identity.

    If AAD Pod Identity was previously installed using Helm, subsequent helm install or helm upgrade would not upgrade the CRD API version from apiextensions.k8s.io/v1beta1 to apiextensions.k8s.io/v1 (although kubectl get crd -oyaml would display apiextensions.k8s.io/v1 since the API server internally converts v1beta1 CRDs to v1, it lacks a structural schema, which is what AAD Pod Identity introduced in v1.8.0). If you wish to upgrade to the official v1 CRDs for AAD Pod Identity:

    kubectl apply -f https://raw.githubusercontent.com/Azure/aad-pod-identity/master/charts/aad-pod-identity/crds/crd.yaml
    

    With managed mode enabled, you can remove the unused AzureAssignedIdentity CRD if you wish.

    # MANAGED MODE ONLY!
    kubectl delete crd azureassignedidentities.aadpodidentity.k8s.io
    

v1.7.x Breaking Change

  • With Azure/aad-pod-identity#842, aad-pod-identity no longer works on clusters with kubenet as the network plugin. For more details, please see Deploy AAD Pod Identity in a Cluster with Kubenet.

    If you still wish to install aad-pod-identity on a kubenet-enabled cluster, set the helm chart value nmi.allowNetworkPluginKubenet to true in the helm command:

    helm (install|upgrade) ... --set nmi.allowNetworkPluginKubenet=true ...
    
  • The forceNameSpaced helm configuration variable is deprecated in helm release 3.0.0 and will be removed in the future helm release. Instead use forceNamespaced to configure pod identity to run in namespaced mode.

  • (Only apply to app version ≥ v1.7.1 / chart version ≥ 3.0.0) azureIdentities in values.yaml is converted to a map instead of a list of identities.

    The following is an example of the required change in values.yaml from helm chart 2.x.x to 3.x.x:

    -azureIdentities:
    -  - name: "azure-identity"
    -    # if not defined, then the azure identity will be deployed in the same namespace as the chart
    -    namespace: ""
    -    # type 0: MSI, type 1: Service Principal
    -    type: 0
    -    # /subscriptions/subscription-id/resourcegroups/resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/identity-name
    -    resourceID: "resource-id"
    -    clientID: "client-id"
    -    binding:
    -      name: "azure-identity-binding"
    -      # The selector will also need to be included in labels for app deployment
    -      selector: "demo"
    +azureIdentities:
    +  "azure-identity":
    +    # if not defined, then the azure identity will be deployed in the same namespace as the chart
    +    namespace: ""
    +    # type 0: MSI, type 1: Service Principal
    +    type: 0
    +    # /subscriptions/subscription-id/resourcegroups/resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/identity-name
    +    resourceID: "resource-id"
    +    clientID: "client-id"
    +    binding:
    +      name: "azure-identity-binding"
    +      # The selector will also need to be included in labels for app deployment
    +      selector: "demo"
    
  • (Only apply to app version ≥ v1.7.5 / chart version ≥ 4.0.0) AAD Pod Identity has dropped Helm 2 starting from chart version 4.0.0/app version 1.7.5. To install or upgrade to the latest version of AAD Pod Identity, please use Helm 3 instead. Refer to this guide on how to migrate from Helm 2 to Helm 3.

v1.6.x Breaking Change

With Azure/aad-pod-identity#398, the client-go library is upgraded to v0.17.2, where CRD fields are now case sensitive. If you are upgrading MIC and NMI from v1.x.x to v1.6.0, MIC v1.6.0+ will upgrade the fields of existing AzureIdentity and AzureIdentityBinding on startup to the new format to ensure backward compatibility. A configmap called aad-pod-identity-config is created to record and confirm the successful type upgrade.

However, for future AzureIdentity and AzureIdentityBinding created using v1.6.0+, the following fields need to be changed:

AzureIdentity

< 1.6.0>= 1.6.0
ClientIDclientID
ClientPasswordclientPassword
ResourceIDresourceID
TenantIDtenantID

AzureIdentityBinding

< 1.6.0>= 1.6.0
AzureIdentityazureIdentity
Selectorselector

AzurePodIdentityException

< 1.6.0>= 1.6.0
PodLabelspodLabels

Ready to get started?

To get started, see the Getting Started page, or you can visit the GitHub repo.


Getting Started

Setup the necessary role assignments on Azure before installing AAD Pod Identity.

Concepts

The API of AAD Pod Identity CRDs and core components: Managed Identity Controller (MIC) and Node Managed Identity (NMI).

Demos

We have created several demos for you to get familiar with AAD Pod Identity

Configurations

An overview of all the features of AAD Pod Identity.

Best Practices

This document highlights the best practices when using aad-pod-identity.

Known Issues

This section lists the major known issues with aad-pod-identity.

Contributing

The AAD Pod Identity project welcomes contributions and suggestions.

Troubleshooting

An overview of a list of components to assist in troubleshooting.

Support

aad-pod-identity is an open source project that is not covered by the Microsoft Azure support policy.

Code of Conduct

The code of conduct outlines expectations for participation in Microsoft-managed open source communities, as well as steps for reporting unacceptable behavior.