github.com/Azure/aad-pod-identity@v1.8.17/manifest_staging/charts/aad-pod-identity/README.md (about) 1 # aad-pod-identity 2 3 [aad-pod-identity](https://github.com/Azure/aad-pod-identity) enables Kubernetes applications to access cloud resources securely with [Azure Active Directory](https://azure.microsoft.com/en-us/services/active-directory/) (AAD). 4 5 ## TL;DR 6 7 ```console 8 helm repo add aad-pod-identity https://raw.githubusercontent.com/Azure/aad-pod-identity/master/charts 9 10 # Helm 3 11 helm install aad-pod-identity aad-pod-identity/aad-pod-identity 12 ``` 13 14 ## Helm chart and aad-pod-identity versions 15 16 | Helm Chart Version | AAD Pod Identity Version | Compatible with Helm 2 | 17 | ------------------ | ------------------------ | ---------------------- | 18 | `2.1.0` | `1.7.0` | ✔️ | 19 | `3.0.0` | `1.7.1` | ✔️ | 20 | `3.0.1` | `1.7.2` | ✔️ | 21 | `3.0.2` | `1.7.3` | ✔️ | 22 | `3.0.3` | `1.7.4` | ✔️ | 23 | `4.0.0` | `1.7.5` | ✕ | 24 | `4.1.0` | `1.8.0` | ✕ | 25 | `4.1.1` | `1.8.0` | ✕ | 26 | `4.1.2` | `1.8.1` | ✕ | 27 | `4.1.3` | `1.8.2` | ✕ | 28 | `4.1.4` | `1.8.3` | ✕ | 29 | `4.1.5` | `1.8.4` | ✕ | 30 | `4.1.6` | `1.8.5` | ✕ | 31 | `4.1.7` | `1.8.6` | ✕ | 32 | `4.1.8` | `1.8.7` | ✕ | 33 | `4.1.9` | `1.8.8` | ✕ | 34 | `4.1.10` | `1.8.9` | ✕ | 35 36 ## Introduction 37 38 A simple [helm](https://helm.sh/) chart for setting up the components needed to use [Azure Active Directory Pod Identity](https://github.com/Azure/aad-pod-identity) in Kubernetes. 39 40 This helm chart will deploy the following resources: 41 * AzureIdentity `CustomResourceDefinition` 42 * AzureIdentityBinding `CustomResourceDefinition` 43 * AzureAssignedIdentity `CustomResourceDefinition` 44 * AzurePodIdentityException `CustomResourceDefinition` 45 * AzureIdentity instance (optional) 46 * AzureIdentityBinding instance (optional) 47 * Managed Identity Controller (MIC) `Deployment` 48 * Node Managed Identity (NMI) `DaemonSet` 49 50 ## Getting Started 51 The following steps will help you create a new Azure identity ([Managed Service Identity](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview) or [Service Principal](https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals)) and assign it to pods running in your Kubernetes cluster. 52 53 ### Prerequisites 54 * [Azure Subscription](https://azure.microsoft.com/) 55 * [Azure Kubernetes Service (AKS)](https://azure.microsoft.com/services/kubernetes-service/) deployment 56 * [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) (authenticated to your Kubernetes cluster) 57 * [Helm 3](https://v3.helm.sh/) 58 * [Azure CLI 2.0](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest) 59 * [git](https://git-scm.com/downloads) 60 61 > It is recommended to use [Helm 3](https://v3.helm.sh/) for installation and uninstallation, however, [Helm 2](https://v2.helm.sh/) is also supported until chart version 3.0.3. 62 63 <details> 64 <summary><strong>[Optional] Creating user identity</strong></summary> 65 66 1. Create a new [Azure User Identity](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview) using the Azure CLI: 67 > __NOTE:__ It's simpler to use the same resource group as your Kubernetes nodes are deployed in. For AKS this is the MC_* resource group. If you can't use the same resource group, you'll need to grant the Kubernetes cluster's service principal the "Managed Identity Operator" role. 68 ```shell 69 az identity create -g <resource-group> -n <id-name> 70 ``` 71 72 2. Assign your newly created identity the appropriate role to the resource you want to access. 73 </details> 74 75 76 #### Installing charts 77 78 * If you need one or more `AzureIdentity` and `AzureIdentityBinding` resources to be created as part of the chart installation, add them to the azureidentities list in the values.yaml and replace the resourceID, clientID using the values for the respective user identities. 79 * If you need the aad-pod-identity deployment to use its own service principal credentials instead of the cluster service principal `/etc/kubernetes/azure.json`, then uncomment this section and add the appropriate values for each required field. 80 * To use a User Managed Identity instead of a service principal set `clientID` and `clientSecret` to `msi`, set `useMSI` to `true`, and `userAssignedMSIClientID` to the client ID of the User Managed Identity. 81 82 ``` 83 adminsecret: 84 cloud: <cloud environment name> 85 subscriptionID: <subscription id> 86 resourceGroup: <node resource group> 87 vmType: <`standard` for normal virtual machine nodes, and `vmss` for cluster deployed with a virtual machine scale set> 88 tenantID: <service principal tenant id> 89 clientID: <service principal client id. Set to `msi` when using a User Managed Identity> 90 clientSecret: <service principal client secret. Set to `msi` when using a User Managed Identity> 91 useMSI: <set to true when using a User Managed Identity> 92 userAssignedMSIClientID: <client id for the User Managed Identity> 93 ``` 94 95 To install the chart with the release name `my-release`: 96 97 ```console 98 helm install --name my-release aad-pod-identity/aad-pod-identity 99 ``` 100 101 Deploy your application to Kubernetes. The application can use [ADAL](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-authentication-libraries) to request a token from the MSI endpoint as usual. If you do not currently have such an application, a demo application is available [here](https://github.com/Azure/aad-pod-identity#demo-app). If you do use the demo application, please update the `deployment.yaml` with the appropriate subscription ID, client ID and resource group name. Also make sure the selector you defined in your `AzureIdentityBinding` matches the `aadpodidbinding` label on the deployment. 102 103 ## Uninstalling the Chart 104 105 To uninstall/delete the last deployment: 106 107 ```console 108 helm ls 109 110 # Helm 3 111 helm uninstall <ReleaseName> 112 113 # Helm 2 114 helm delete <ReleaseName> --purge 115 ``` 116 117 The command removes all the Kubernetes components associated with the chart and deletes the release. 118 119 > The CRD created by the chart are not removed by default and should be manually cleaned up (if required) 120 121 ```bash 122 kubectl delete crd azureassignedidentities.aadpodidentity.k8s.io 123 kubectl delete crd azureidentities.aadpodidentity.k8s.io 124 kubectl delete crd azureidentitybindings.aadpodidentity.k8s.io 125 kubectl delete crd azurepodidentityexceptions.aadpodidentity.k8s.io 126 ``` 127 128 ## Upgrade guide 129 130 ### Upgrading from chart version 1.5.5 131 132 1.5.5 helm chart had introduced 2 labels which could possibly change with chart upgrade: 133 134 ```yaml 135 app.kubernetes.io/managed-by: Helm 136 helm.sh/chart: aad-pod-identity-1.5.5 137 ``` 138 139 This has been fixed in chart version `1.5.6` to prevent any issues with future upgrades of helm chart. For upgrading from 1.5.5 to any new chart version, a suggested workaround is editing the nmi and mic manifests to remove those 2 labels from `selector.matchLabels`: 140 141 ```bash 142 kubectl get ds aad-pod-identity-nmi -o jsonpath='{.spec.selector.matchLabels}' 143 map[app.kubernetes.io/component:nmi app.kubernetes.io/instance:pod-identity app.kubernetes.io/managed-by:Helm app.kubernetes.io/name:aad-pod-identity helm.sh/chart:aad-pod-identity-1.5.5] 144 145 kubectl edit ds aad-pod-identity-nmi 146 (Remove `app.kubernetes.io/managed-by: Helm` and `helm.sh/chart: aad-pod-identity-1.5.5` from the spec.selector.matchLabels) 147 148 kubectl get deploy aad-pod-identity-mic -o jsonpath='{.spec.selector.matchLabels}' 149 map[app.kubernetes.io/component:mic app.kubernetes.io/instance:pod-identity app.kubernetes.io/managed-by:Helm app.kubernetes.io/name:aad-pod-identity helm.sh/chart:aad-pod-identity-1.5.5] 150 151 kubectl edit deploy aad-pod-identity-mic 152 (Remove `app.kubernetes.io/managed-by: Helm` and `helm.sh/chart: aad-pod-identity-1.5.5` from the spec.selector.matchLabels) 153 ``` 154 Once this is done, the helm upgrade command will succeed. 155 156 157 ### Upgrading to a New Major Chart Version 158 159 A major chart version change (like v1.6.0 -> v2.0.0) indicates that there is a backward-incompatible (breaking) change needing manual actions. 160 161 #### 4.0.0 162 163 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](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/) on how to migrate from Helm 2 to Helm 3. 164 165 #### 3.0.0 166 167 Accessing the identities in the list is harder for the user to figure out and prone to errors if the order is changed. This version updates the `azureIdentities` to be a map instead of a list of identities. 168 169 The following is a basic example of the required change in the user-supplied values file. 170 171 ```diff 172 -azureIdentities: 173 - - name: "azure-identity" 174 - # if not defined, then the azure identity will be deployed in the same namespace as the chart 175 - namespace: "" 176 - # type 0: MSI, type 1: Service Principal 177 - type: 0 178 - # /subscriptions/subscription-id/resourcegroups/resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/identity-name 179 - resourceID: "resource-id" 180 - clientID: "client-id" 181 - binding: 182 - name: "azure-identity-binding" 183 - # The selector will also need to be included in labels for app deployment 184 - selector: "demo" 185 +azureIdentities: 186 + "azure-identity": 187 + # if not defined, then the name of azure identity will be the same as the key 188 + name: "" 189 + # if not defined, then the azure identity will be deployed in the same namespace as the chart 190 + namespace: "" 191 + # type 0: MSI, type 1: Service Principal 192 + type: 0 193 + # /subscriptions/subscription-id/resourcegroups/resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/identity-name 194 + resourceID: "resource-id" 195 + clientID: "client-id" 196 + binding: 197 + name: "azure-identity-binding" 198 + # The selector will also need to be included in labels for app deployment 199 + selector: "demo" 200 ``` 201 202 In addition, `forceNameSpaced` in `values.yaml` has been **deprecated**, and will be removed in future releases. Please switch to `forceNamespaced` instead. 203 204 #### 2.0.0 205 206 This version removes the `azureIdentity` and `azureIdentityBinding` values in favor of `azureIdentities`, a list of identities and their respective bindings, to support the creation of multiple AzureIdentity and AzureIdentityBinding resources. 207 208 The following is a basic example of the required change in the user-supplied values file. 209 210 ```diff 211 - azureIdentity: 212 - enabled: true 213 - name: "azure-identity" 214 - namespace: "azure-identity-namespace" 215 - type: 0 216 - resourceID: "resource-id" 217 - clientID: "client-id" 218 - azureIdentityBinding: 219 - name: "azure-identity-binding" 220 - selector: "demo" 221 + azureIdentities: 222 + - name: "azure-identity" 223 + namespace: "azure-identity-namespace" 224 + type: 0 225 + resourceID: "resource-id" 226 + clientID: "client-id" 227 + binding: 228 + name: "azure-identity-binding" 229 + selector: "demo" 230 ``` 231 232 ## Configuration 233 234 The following tables list the configurable parameters of the aad-pod-identity chart and their default values. 235 236 | Parameter | Description | Default | 237 | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | 238 | `nameOverride` | String to partially override aad-pod-identity.fullname template with a string (will prepend the release name) | `""` | 239 | `fullnameOverride` | String to fully override aad-pod-identity.fullname template with a string | `""` | 240 | `image.repository` | Image repository | `mcr.microsoft.com/oss/azure/aad-pod-identity` | 241 | `image.imagePullPolicy` | Image pull policy | `IfNotPresent` | 242 | `imagePullSecrets` | One or more secrets to be used when pulling images | `[]` | 243 | `forceNamespaced` | By default, AAD Pod Identity matches pods to identities across namespaces. To match only pods in the namespace containing AzureIdentity set this to true. | `false` | 244 | `installMICException` | When NMI runs on a node where MIC is running, then MIC token request call is also intercepted by NMI. MIC can't get a valid token to initialize and then assign the identity. Installing an exception for MIC would ensure all token requests for MIC pods directly go to IMDS and not go through the pod-identity validation | `true` | 245 | `adminsecret.cloud` | Azure cloud environment name | ` ` | 246 | `adminsecret.subscriptionID` | Azure subscription ID | ` ` | 247 | `adminsecret.resourceGroup` | Azure resource group | ` ` | 248 | `adminsecret.vmType` | `standard` for normal virtual machine nodes, and `vmss` for cluster deployed with a virtual machine scale set | ` ` | 249 | `adminsecret.tenantID` | Azure service principal tenantID | ` ` | 250 | `adminsecret.clientID` | Azure service principal clientID or `msi` when using a managed identity | ` ` | 251 | `adminsecret.clientSecret` | Azure service principal clientSecret or `msi` when using a user managed identity | ` ` | 252 | `adminsecret.useMSI` | Set to `true` when using a user managed identity | ` ` | 253 | `adminsecret.userAssignedMSIClientID` | Azure user managed identity client ID | ` ` | 254 | `mic.image` | MIC image name | `mic` | 255 | `mic.tag` | MIC image tag | `v1.8.17` | 256 | `mic.priorityClassName` | MIC priority class (can only be set when deploying to kube-system namespace) | | 257 | `mic.logVerbosity` | Log level. Uses V logs (klog) | `0` | 258 | `mic.loggingFormat` | Log format. One of (text \| json) | `text` | 259 | `mic.replicas` | Number of replicas for MIC | `2` | 260 | `mic.resources` | Resource limit for MIC | `{}` | 261 | `mic.podAnnotations` | Pod annotations for MIC | `{}` | 262 | `mic.podLabels` | Pod labels for MIC | `{}` | 263 | `mic.affinity` | Affinity settings | A "soft" anti-affinity rule to avoid co-location on a node | 264 | `mic.tolerations` | List of node taints to tolerate | `[]` | 265 | `mic.topologySpreadConstraints` | Pod topology spread constraints settings | `[]` | 266 | `mic.podDisruptionBudget` | Pod disruption budget settings | `{}` | 267 | `mic.leaderElection.instance` | Override leader election instance name | If not provided, default value is `hostname` | 268 | `mic.leaderElection.namespace` | Override the namespace to create leader election objects | `default` | 269 | `mic.leaderElection.name` | Override leader election name | If not provided, default value is `aad-pod-identity-mic` | 270 | `mic.leaderElection.duration` | Override leader election duration | If not provided, default value is `15s` | 271 | `mic.probePort` | Override http liveliness probe port | If not provided, default port is `8080` | 272 | `mic.syncRetryDuration` | Override interval in seconds at which sync loop should periodically check for errors and reconcile | If not provided, default value is `3600s` | 273 | `mic.immutableUserMSIs` | List of user-defined identities that shouldn't be deleted from VM/VMSS. | If not provided, default value is empty | 274 | `mic.cloudConfig` | The cloud configuration used to authenticate with Azure | If not provided, default value is `/etc/kubernetes/azure.json` | 275 | `mic.customCloud.enabled` | Indicates whether or not a custom cloud (e.g., AzureStack) is in use | If not provided, default value is `false` | 276 | `mic.customCloud.configPath` | The location of the custom cloud config file | If not provided, default value is `/etc/kubernetes/akscustom.json` | 277 | `mic.updateUserMSIMaxRetry` | The maximum retry of UpdateUserMSI call in case of assignment errors | If not provided, default value is `2` | 278 | `mic.updateUserMSIRetryInterval` | The duration to wait before retrying UpdateUserMSI (batch assigning/un-assigning identity from VM/VMSS) in case of errors | If not provided, default value is `1s` | 279 | `mic.identityAssignmentReconcileInterval` | The interval between reconciling identity assignment on Azure based on an existing list of AzureAssignedIdentities | If not provided, default value is `3m` | 280 | `nmi.image` | NMI image name | `nmi` | 281 | `nmi.tag` | NMI image tag | `v1.8.17` | 282 | `nmi.priorityClassName` | NMI priority class (can only be set when deploying to kube-system namespace) | | 283 | `nmi.logVerbosity` | Log level. Uses V logs (klog) | `0` | 284 | `nmi.loggingFormat` | Log format. One of (text \| json) | `text` | 285 | `nmi.resources` | Resource limit for NMI | `{}` | 286 | `nmi.podAnnotations` | Pod annotations for NMI | `{}` | 287 | `nmi.podLabels` | Pod labels for NMI | `{}` | 288 | `nmi.affinity` | Affinity settings | `{}` | 289 | `nmi.tolerations` | List of node taints to tolerate | `[{"operator": "Exists"}]` | 290 | `nmi.ipTableUpdateTimeIntervalInSeconds` | Override iptables update interval in seconds | `60` | 291 | `nmi.micNamespace` | Override mic namespace to short circuit MIC token requests | If not provided, default is `default` namespace | 292 | `nmi.probePort` | Override http liveliness probe port | If not provided, default is `8085` | 293 | `nmi.retryAttemptsForCreated` | Override number of retries in NMI to find assigned identity in CREATED state | If not provided, default is `16` | 294 | `nmi.retryAttemptsForAssigned` | Override number of retries in NMI to find assigned identity in ASSIGNED state | If not provided, default is `4` | 295 | `nmi.findIdentityRetryIntervalInSeconds` | Override retry interval to find assigned identities in seconds | If not provided, default is `5` | 296 | `nmi.allowNetworkPluginKubenet` | Allow running aad-pod-identity in cluster with kubenet | `false` | 297 | `nmi.kubeletConfig` | Path to kubelet default config | `/etc/default/kubelet` | 298 | `nmi.setRetryAfterHeader` | Set Retry-After header in NMI responses | `false` | 299 | `nmi.updateStrategy` | Override the Kubernetes update strategy used when rolling out the NMI Daemonset | If not provided, defaults to a `RollingUpdate` with a `maxUnavailable` of `1` (i.e., one node at a time) | 300 | `rbac.enabled` | Create and use RBAC for all aad-pod-identity resources | `true` | 301 | `rbac.pspEnabled` | If `true`, create and use a restricted pod security policy for AAD Pod Identity pod(s) | `false` | 302 | `rbac.allowAccessToSecrets` | NMI requires permissions to get secrets when service principal (type: 1) is used in AzureIdentity. If using only MSI (type: 0) in AzureIdentity, secret get permission can be disabled by setting this to false. | `true` | 303 | `rbac.createUserFacingClusterRoles` | If set to true, then view and edit cluster roles will be created with annotations for the admin, edit and view built-in Kubernetes cluster roles. These roles will be able to create the necessary resources to allow pod identity binding on pods. | `false` | 304 | `azureIdentities` | Map of azure identities and azure identity bindings resources to create. The map key is the `AzureIdentity` name. | `{}` | 305 | `customUserAgent` | Custom user agent to add to ADAL, ARM and Kubernetes API server requests | `""` | 306 307 ## Troubleshooting 308 309 If the helm chart is deleted and then reinstalled without manually deleting the crds, then you can get an error like - 310 311 ```console 312 ➜ helm install aad-pod-identity/aad-pod-identity --name pod-identity 313 Error: customresourcedefinitions.apiextensions.k8s.io "azureassignedidentities.aadpodidentity.k8s.io" already exists 314 ``` 315 316 In this case, since there is no update to the crd definition since it was last installed, you can use a parameter to say not to use hook to install the CRD: 317 318 ```console 319 helm install aad-pod-identity/aad-pod-identity --name pod-identity --no-hooks 320 ```