diff --git a/docs/provider/azure-key-vault.md b/docs/provider/azure-key-vault.md index 2a818270568..e8a0ad5b74d 100644 --- a/docs/provider/azure-key-vault.md +++ b/docs/provider/azure-key-vault.md @@ -7,9 +7,9 @@ External Secrets Operator integrates with [Azure Key vault](https://azure.micros ### Authentication -We support Service Principals, Managed Identity and Workload Identity authentication. +We support authentication with Microsoft Entra identities that can be used as Workload Identity or [AAD Pod Identity](https://azure.github.io/aad-pod-identity/docs/) as well as with Service Principal credentials. -To use Managed Identity authentication, you should use [aad-pod-identity](https://azure.github.io/aad-pod-identity/docs/) to assign the identity to external-secrets operator. To add the selector to external-secrets operator, use `podLabels` in your values.yaml in case of Helm installation of external-secrets. +Since the [AAD Pod Identity](https://azure.github.io/aad-pod-identity/docs/) is deprecated, it is recommended to use the [Workload Identity](https://azure.github.io/azure-workload-identity) authentication. We support connecting to different cloud flavours azure supports: `PublicCloud`, `USGovernmentCloud`, `ChinaCloud` and `GermanCloud`. You have to specify the `environmentType` and point to the correct cloud flavour. This defaults to `PublicCloud`. @@ -40,6 +40,8 @@ A service Principal client and Secret is created and the JSON keyfile is stored A Managed Identity should be created in Azure, and that Identity should have proper rights to the keyvault to be managed by the operator. +Use [aad-pod-identity](https://azure.github.io/aad-pod-identity/docs/) to assign the identity to external-secrets operator. To add the selector to external-secrets operator, use `podLabels` in your values.yaml in case of Helm installation of external-secrets. + If there are multiple Managed Identities for different keyvaults, the operator should have been assigned all identities via [aad-pod-identity](https://azure.github.io/aad-pod-identity/docs/), then the SecretStore configuration should include the Id of the identity to be used via the `identityId` field. ```yaml @@ -48,6 +50,8 @@ If there are multiple Managed Identities for different keyvaults, the operator s #### Workload Identity +In Microsoft Entra, Workload Identity can be Application, user-assigned Managed Identity and Service Principal. + You can use [Azure AD Workload Identity Federation](https://docs.microsoft.com/en-us/azure/active-directory/develop/workload-identity-federation) to access Azure managed services like Key Vault **without needing to manage secrets**. You need to configure a trust relationship between your Kubernetes Cluster and Azure AD. This can be done in various ways, for instance using `terraform`, the Azure Portal or the `az` cli. We found the [azwi](https://azure.github.io/azure-workload-identity/docs/installation/azwi.html) cli very helpful. The Azure [Workload Identity Quick Start Guide](https://azure.github.io/azure-workload-identity/docs/quick-start.html) is also good place to get started. This is basically a two step process: @@ -80,7 +84,7 @@ You run the controller and mount that particular service account into the pod by ``` ##### Referenced Service Account -You run the controller without service account (effectively without azure permissions). Now you have to configure the SecretStore and set the `serviceAccountRef` and point to the service account you have just created. **This is usually the recommended approach**. It makes sense for everyone who wants to run the controller withour Azure permissions and delegate authentication via service accounts in particular namespaces. Also see our [Multi-Tenancy Guide] for design considerations. +You run the controller without service account (effectively without azure permissions). Now you have to configure the SecretStore and set the `serviceAccountRef` and point to the service account you have just created. **This is usually the recommended approach**. It makes sense for everyone who wants to run the controller without Azure permissions and delegate authentication via service accounts in particular namespaces. Also see our [Multi-Tenancy Guide](../guides/multi-tenancy.md) for design considerations. ```yaml {% include 'azkv-workload-identity.yaml' %} @@ -102,17 +106,17 @@ Or in case of Managed Identity authentication: ### Object Types -Azure KeyVault manages different [object types](https://docs.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates#object-types), we support `keys`, `secrets` and `certificates`. Simply prefix the key with `key`, `secret` or `cert` to retrieve the desired type (defaults to secret). +Azure Key Vault manages different [object types](https://docs.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates#object-types), we support `keys`, `secrets` and `certificates`. Simply prefix the key with `key`, `secret` or `cert` to retrieve the desired type (defaults to secret). | Object Type | Return Value | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `secret` | the raw secret value. | -| `key` | A JWK which contains the public key. Azure KeyVault does **not** export the private key. You may want to use [template functions](../guides/templating.md) to transform this JWK into PEM encoded PKIX ASN.1 DER format. | +| `key` | A JWK which contains the public key. Azure Key Vault does **not** export the private key. You may want to use [template functions](../guides/templating.md) to transform this JWK into PEM encoded PKIX ASN.1 DER format. | | `certificate` | The raw CER contents of the x509 certificate. You may want to use [template functions](../guides/templating.md) to transform this into your desired encoding | ### Creating external secret -To create a kubernetes secret from the Azure Key vault secret a `Kind=ExternalSecret` is needed. +To create a Kubernetes secret from the Azure Key vault secret a `Kind=ExternalSecret` is needed. You can manage keys/secrets/certificates saved inside the keyvault , by setting a "/" prefixed type in the secret name, the default type is a `secret`. Other supported values are `cert` and `key`. @@ -139,10 +143,10 @@ To get a PKCS#12 certificate from Azure Key Vault and inject it as a `Kind=Secre ``` ### Creating a PushSecret -You can push secrets to Keyvault into the different `secret`, `key` and `certificate` APIs. +You can push secrets to Azure Key Vault into the different `secret`, `key` and `certificate` APIs. #### Pushing to a Secret -Pushing to a Secret requires no previous setup. with the secret available in kubernetes, you can simply refer it to a PushSecret object to have it created on Azure Keyvault: +Pushing to a Secret requires no previous setup. with the secret available in Kubernetes, you can simply refer it to a PushSecret object to have it created on Azure Key Vault: ```yaml {% include 'azkv-pushsecret-secret.yaml' %} ``` @@ -159,7 +163,7 @@ The first step is to generate a valid Private Key. Supported Formats include `PR !!! note In order to create a PushSecret targeting keys, `ImportKey` and `DeleteKey` actions must be granted to the Service Principal/Identity configured on the SecretStore. #### Pushing to a Certificate -The first step is to generate a valid P12 certificate. Currently, only PKCS1/PKCS8 types are supported. Currently only passwordless P12 certificates are supported. +The first step is to generate a valid P12 certificate. Currently, only PKCS1/PKCS8 types are supported. Currently only password-less P12 certificates are supported. After uploading your P12 certificate to a Kubernetes Secret, the next step is to create a PushSecret manifest with the following configuration ```yaml