From e9514658c406d174d0ce072840485d462cadc021 Mon Sep 17 00:00:00 2001
From: hc-github-team-secure-vault-core
 <82990506+hc-github-team-secure-vault-core@users.noreply.github.com>
Date: Thu, 13 Jan 2022 13:41:33 -0500
Subject: [PATCH] Backport of secrets/keymgmt: Adds documentation for using
 Azure Private Link into stable-website (#13654)

This pull request was automerged via backport-assistant
---
 .../docs/secrets/key-management/awskms.mdx    |  2 +-
 .../secrets/key-management/azurekeyvault.mdx  | 32 +++++++++++++++++++
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/website/content/docs/secrets/key-management/awskms.mdx b/website/content/docs/secrets/key-management/awskms.mdx
index c825b2e9393b..7f6363986a1b 100644
--- a/website/content/docs/secrets/key-management/awskms.mdx
+++ b/website/content/docs/secrets/key-management/awskms.mdx
@@ -64,7 +64,7 @@ specification.
 
 ## Key Rotation
 
-Customer master keys (CMKs) with imported key material are not eligible for
+AWS KMS keys with imported key material are not eligible for
 [automatic key rotation](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html)
 within AWS KMS. As such, key rotations performed by the secrets engine use the
 [manual key rotation](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html#rotate-keys-manually)
diff --git a/website/content/docs/secrets/key-management/azurekeyvault.mdx b/website/content/docs/secrets/key-management/azurekeyvault.mdx
index ee2188525952..ade500f2ac8e 100644
--- a/website/content/docs/secrets/key-management/azurekeyvault.mdx
+++ b/website/content/docs/secrets/key-management/azurekeyvault.mdx
@@ -73,3 +73,35 @@ for each key type supported by GCP Cloud KMS.
 | `rsa-2048`     | [All purposes](/api-docs/secret/key-management#purpose) |
 | `rsa-3072`     | [All purposes](/api-docs/secret/key-management#purpose) |
 | `rsa-4096`     | [All purposes](/api-docs/secret/key-management#purpose) |
+
+## Azure Private Link
+
+The secrets engine can be configured to communicate with Azure Key Vault instances
+using [Azure Private Endpoints](https://docs.microsoft.com/en-us/azure/private-link/private-endpoint-overview).
+Follow the guide at [Integrate Key Vault with Azure Private Link](https://docs.microsoft.com/en-us/azure/key-vault/general/private-link-service?tabs=portal)
+to set up a Private Endpoint for your target Key Vault instance in Azure. The Private Endpoint must
+be network reachable by Vault. This means Vault needs to be running in the same virtual network or
+a peered virtual network to properly resolve the Key Vault domain name to the Private Endpoint IP
+address.
+
+The Private Endpoint configuration relies on a correct [Azure Private DNS](https://docs.microsoft.com/en-us/azure/dns/private-dns-overview)
+integration. From the host that Vault is running on, follow the steps in
+[Validate that the private link connection works](https://docs.microsoft.com/en-us/azure/key-vault/general/private-link-service?tabs=portal#validate-that-the-private-link-connection-works)
+to ensure that the Key Vault domain name resolves to the Private Endpoint IP address you've configured.
+
+```
+$ nslookup <keyvault-name>.vault.azure.net
+
+Non-authoritative answer:
+Name:
+Address:  10.0.2.5 (private IP address)
+Aliases:  <keyvault-name>.vault.azure.net
+          <keyvault-name>.privatelink.vaultcore.azure.net
+```
+
+The secrets engine doesn't require special configuration to communicate with a Key Vault instance
+over an Azure Private Endpoint. For example, the given [KMS configuration](/docs/secrets/key-management/azurekeyvault#configuration)
+will result in the secrets engine resolving a Key Vault domain name of `keyvault-name.vault.azure.net`
+to the Private Endpoint IP address. Note that it's possible to change the Key Vault DNS suffix using the
+[environment](/api-docs/secret/key-management/azurekeyvault#environment)
+configuration parameter or `AZURE_ENVIRONMENT` environment variable.