Skip to content

Commit d257cd3

Browse files
Stacyrch140Stacyrch140
authored
Merge pull request #269457 from anaharris-ms/relocate-key-vault
Relocation - Key vault update
2 parents 941e303 + 17215bd commit d257cd3

File tree

1 file changed

+331
-23
lines changed

1 file changed

+331
-23
lines changed

‎articles/operational-excellence/relocation-key-vault.md

Lines changed: 331 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,367 @@
11
---
2-
title: Relocate Azure KeyVault to another region
2+
title: Relocate Azure Key Vault to another region
33
description: This article offers guidance on moving a key vault to a different region.
44
services: key-vault
55
author: anaharris
66
ms.service: key-vault
77
ms.subservice: general
88
ms.topic: concept
9-
ms.date: 02/29/2024
9+
ms.date: 03/18/2024
1010
ms.author: mbaldwin
11-
ms.custom: subject-relocation
12-
11+
ms.custom: subject-relocation
1312
# Customer intent: As a key vault administrator, I want to move my vault to another region.
1413
---
1514

16-
# Relocate Azure KeyVault to another region
15+
# Relocate Azure Key Vault to another region
16+
17+
Azure Key Vault doesn't support key vault relocation to another region.
18+
19+
Instead of relocation, you need to:
1720

18-
Azure Key Vault does not allow you to move a key vault from one region to another. You can, however, create a key vault in the new region, manually backup/restore each individual key, secret, or certificate from your existing key vault to the new key vault, and then remove the original key vault.
21+
- Create a new key vault with the relocation of the associated Azure services.
22+
- Regenerate any required [keys](/azure/key-vault/keys/about-keys), [secrets](/azure/key-vault/secrets/about-secrets), or [certificates](/azure/key-vault/certificates/about-certificates). In some cases, you may need to transfer the secrets or certificates from your existing key vault to the relocated key vault.
23+
24+
![Diagram showing Azure Key vault relocation pattern](./media/relocation/keyvault/akv-pattern-design.png)
1925

2026
## Prerequisites
2127

22-
It's critical to understand the implications of this workaround before you attempt to apply it in a production environment.
28+
- Verify that your Azure subscription allows you to create key vaults in the target region.
29+
30+
- Create a dependency map with all the Azure services used by the Key Vault. For the services that are in scope of the relocation, you must choose the appropriate relocation strategy.
31+
32+
- Depending on your Key Vault design, you may need to deploy and configure the [Virtual Network](./relocation-virtual-network.md) in the target region.
33+
34+
- Document and plan to re-configure in the Key Vault in the target region:
35+
- Access Policies and Network configuration settings.
36+
- Soft delete and purge protection.
37+
- Autorotation settings.
38+
39+
## Consideration for Service Endpoints
40+
41+
The virtual network service endpoints for Azure Key Vault restrict access to a specified virtual network. The endpoints can also restrict access to a list of IPv4 (internet protocol version 4) address ranges. Any user connecting to the Key Vault from outside those sources is denied access. If Service endpoints were configured in the source region for the Key Vault resource, the same would need to be done in the target one.
42+
43+
For a successful recreation of the Key Vault to the target region, the VNet and Subnet must be created beforehand. In case the move of these two resources is being carried out with the Azure Resource Mover tool, the service endpoints won’t be configured automatically. Hence, they need to be configured manually, which can be done through the [Azure portal](/azure/key-vault/general/quick-create-portal), the [Azure CLI](/azure/key-vault/general/quick-create-cli), or [Azure PowerShell](/azure/key-vault/general/quick-create-powershell).
44+
45+
46+
## Consideration for Private Endpoint
47+
48+
Azure Private Link provides private connectivity from a virtual network to [Azure platform as a service (PaaS), customer-owned, or Microsoft partner services](/azure/private-link/private-endpoint-overview). Private Link simplifies the network architecture and secures the connection between endpoints in Azure by eliminating data exposure to the public internet.
49+
50+
For a successful recreation of the Key Vault in the target region, the VNet and Subnet must be created before the actual recreation occurs.
51+
52+
### Consideration for Azure Private Endpoint DNS Integration
53+
54+
It’s important to correctly configure your DNS settings to resolve the private endpoint IP address to the fully qualified domain name (FQDN) of the connection string.
55+
56+
Existing Microsoft Azure services might already have a DNS configuration for a public endpoint. This configuration must be overridden to connect using your private endpoint.
57+
58+
The network interface associated with the private endpoint contains the information to configure your DNS. The network interface information includes FQDN and private IP addresses for your private link resource.
59+
60+
You can use the following options to configure your DNS settings for private endpoints:
61+
62+
- **Use the host file (only recommended for testing)**. You can use the host file on a virtual machine to override the DNS.
63+
- **Use a private DNS zone.** You can use private DNS zones to override the DNS resolution for a private endpoint. A private DNS zone can be linked to your virtual network to resolve specific domains.
64+
- **Use your DNS forwarder (optional).** You can use your DNS forwarder to override the DNS resolution for a private link resource. Create a DNS forwarding rule to use a private DNS zone on your DNS server hosted in a virtual network.
2365

2466
## Prepare
2567

26-
First, you must create a new key vault in the region to which you wish to move. You can do so through the [Azure portal](/azure/key-vault/general/quick-create-portal), the [Azure CLI](/azure/key-vault/general/quick-create-cli), or [Azure PowerShell](/azure/key-vault/general/quick-create-powershell).
68+
### [Portal](#tab/azure-portal)
69+
70+
To export a template by using Azure portal:
71+
72+
1. Sign in to the [Azure portal](https://portal.azure.com).
73+
74+
2. Select **All resources** and then select your key vault.
75+
76+
3. Select > **Automation** > **Export template**.
77+
78+
4. Choose **Download** in the **Export template** blade.
79+
80+
5. Locate the .zip file that you downloaded from the portal, and unzip that file to a folder of your choice.
81+
82+
This zip file contains the .json files that comprise the template and scripts to deploy the template.
83+
84+
### [PowerShell](#tab/azure-powershell)
85+
86+
To export a template by using PowerShell:
87+
88+
1. Sign in to your Azure subscription with the [Connect-AzAccount](/powershell/module/az.accounts/connect-azaccount) command and follow the on-screen directions:
89+
90+
```azurepowershell-interactive
91+
Connect-AzAccount
92+
```
93+
94+
2. If your identity is associated with more than one subscription, then set your active subscription to subscription of the key vault that you want to move.
95+
96+
```azurepowershell-interactive
97+
$context = Get-AzSubscription -SubscriptionId <subscription-id>
98+
Set-AzContext $context
99+
```
100+
101+
3. Export the template of your source key vault. These commands save a json template to your current directory.
102+
103+
```azurepowershell-interactive
104+
$resource = Get-AzResource `
105+
-ResourceGroupName <resource-group-name> `
106+
-ResourceName <key-vault-name> `
107+
-ResourceType Microsoft.KeyVault/vaults `
108+
Export-AzResourceGroup `
109+
-ResourceGroupName <resource-group-name> `
110+
-Resource $resource.ResourceId
111+
```
112+
113+
---
27114

28115
Keep in mind the following concepts:
29116

30-
* Key vault names are globally unique. You can't reuse a vault name.
31-
* You need to reconfigure your access policies and network configuration settings in the new key vault.
32-
* You need to reconfigure soft-delete and purge protection in the new key vault.
33-
* The backup and restore operation won't preserve your autorotation settings. You might need to reconfigure the settings.
117+
- Key vault names are globally unique. You can't reuse a vault name.
118+
- You need to reconfigure your access policies and network configuration settings in the new key vault.
119+
- You need to reconfigure soft-delete and purge protection in the new key vault.
120+
- The backup and restore operation doesn't preserve your autorotation settings. You might need to reconfigure the settings.
34121

35-
## Move
122+
## Modify the template
36123

37-
Export your keys, secrets, or certificates from your old key vault, and then import them into your new vault.
124+
Modify the template by changing the key vault name and region.
38125

39-
You can back up each individual secret, key, and certificate in your vault by using the backup command. Your secrets are downloaded as an encrypted blob. For step by step guidance, see [Azure Key Vault backup and restore](/azure/key-vault/general/backup).
126+
### [Portal](#tab/azure-portal)
40127

41-
Alternatively, you can download certain secret types manually. For example, you can download certificates as a PFX file. This option eliminates the geographical restrictions for some secret types, such as certificates. You can upload the PFX files to any key vault in any region. The secrets are downloaded in a non-password protected format. You are responsible for securing your secrets during the move.
128+
To deploy the template by using Azure portal:
42129

43-
After you have downloaded your keys, secrets, or certificates, you can restore them to your new key vault.
130+
1. In the Azure portal, select **Create a resource**.
44131

45-
Using the backup and restore commands has two limitations:
132+
2. In **Search the Marketplace**, type **template deployment**, and then press **ENTER**.
46133

47-
* You can't back up a key vault in one geography and restore it into another geography. For more information, see [Azure geographies](https://azure.microsoft.com/global-infrastructure/geographies/).
134+
3. Select **Template deployment**.
48135

49-
* The backup command backs up all versions of each secret. If you have a secret with a large number of previous versions (more than 10), the request size might exceed the allowed maximum and the operation might fail.
136+
4. Select **Create**.
50137

51-
## Verify
138+
5. Select **Build your own template in the editor**.
139+
140+
6. Select **Load file**, and then follow the instructions to load the **template.json** file that you downloaded in the last section.
141+
142+
7. In the **template.json** file, name the key vault by setting the default value of the key vault name. This example sets the default value of the key vault name to `mytargetaccount`.
143+
144+
```json
145+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
146+
"contentVersion": "1.0.0.0",
147+
"parameters": {
148+
"vaults_name": {
149+
"defaultValue": "key-vault-name",
150+
"type": "String"
151+
}
152+
},
153+
```
154+
155+
8. Edit the **location** property in the **template.json** file to the target region. This example sets the target region to `centralus`.
156+
157+
```json
158+
"resources": [
159+
{
160+
"type": "Microsoft.KeyVault/vaults",
161+
"apiVersion": "2023-07-01",
162+
"name": "[parameters('vaults_name')]",
163+
"location": "centralus",
164+
...
165+
},
166+
...
167+
]
168+
```
169+
170+
To obtain region location codes, see [Azure Locations](https://azure.microsoft.com/global-infrastructure/locations/). The code for a region is the region name with no spaces, **Central US** = **centralus**.
171+
172+
9. Remove resources of typ private endpoint in the template.
173+
174+
```json
175+
{
176+
"type": "Microsoft.KeyVault/vaults/privateEndpointConnections",
177+
...
178+
}
179+
```
52180

53-
Before deleting your old key vault, verify that the new vault contains all of the required keys, secrets, and certificates.
181+
10. In case you configured a service endpoint in your key vault, in the _networkAcl_ section, under _virtualNetworkRules_, add the rule for the target subnet. Ensure that the _ignoreMissingVnetServiceEndpoint_ flag is set to False, so that the IaC fails to deploy the Key Vault in case the service endpoint isn’t configured in the target region.
182+
183+
_parameter.json_
184+
185+
```json
186+
{
187+
"$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
188+
"contentVersion": "1.0.0.0",
189+
"parameters": {
190+
"target_vnet_externalid": {
191+
"value": "virtualnetwork-externalid"
192+
},
193+
"target_subnet_name": {
194+
"value": "subnet-name"
195+
}
196+
}
197+
}
198+
```
199+
200+
\_template.json
201+
202+
```json
203+
"networkAcls": {
204+
"bypass": "AzureServices",
205+
"defaultAction": "Deny",
206+
"ipRules": [],
207+
"virtualNetworkRules": [
208+
{
209+
"id": "[concat(parameters('target_subnet_name'), concat('/subnets/', parameters('target_subnet_name')]",
210+
"ignoreMissingVnetServiceEndpoint": false
211+
}
212+
]
213+
}
214+
```
215+
216+
### [PowerShell](#tab/azure-powershell)
217+
218+
To deploy the template by using PowerShell:
219+
220+
1. In the **template.json** file, name the target key vault by setting the default value of the key vault name. This example sets the default value of the key vault name to `key-vault-name`.
221+
222+
```json
223+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
224+
"contentVersion": "1.0.0.0",
225+
"parameters": {
226+
"vaults_name": {
227+
"defaultValue": "key-vault-name",
228+
"type": "String"
229+
}
230+
},
231+
```
232+
233+
2. Edit the **location** property in the **template.json** file to the target region. This example sets the target region to `eastus`.
234+
235+
```json
236+
"resources": [
237+
{
238+
"type": "Microsoft.KeyVault/vaults",
239+
"apiVersion": "2023-07-01",
240+
"name": "[parameters('vaults_name')]",
241+
"location": "eastus",
242+
...
243+
},
244+
...
245+
]
246+
```
247+
248+
You can obtain region codes by running the [Get-AzLocation](/powershell/module/az.resources/get-azlocation) command.
249+
250+
```azurepowershell-interactive
251+
Get-AzLocation | format-table
252+
```
253+
254+
3. Remove resources of typ private endpoint in the template.
255+
256+
```json
257+
{
258+
"type": "Microsoft.KeyVault/vaults/privateEndpointConnections",
259+
...
260+
}
261+
```
262+
263+
4. In case you have configured a service endpoint in your key vault, in the _networkAcl_ section, under _virtualNetworkRules_, add the rule for the target subnet. Ensure that the _ignoreMissingVnetServiceEndpoint_ flag is set to False, so that the IaC fails to deploy the Key Vault in case the service endpoint isn’t configured in the target region.
264+
265+
_parameter.json_
266+
267+
```json
268+
{
269+
"$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
270+
"contentVersion": "1.0.0.0",
271+
"parameters": {
272+
"target_vnet_externalid": {
273+
"value": "virtualnetwork-externalid"
274+
},
275+
"target_subnet_name": {
276+
"value": "subnet-name"
277+
}
278+
}
279+
}
280+
```
281+
282+
_template.json_
283+
284+
```json
285+
"networkAcls": {
286+
"bypass": "AzureServices",
287+
"defaultAction": "Deny",
288+
"ipRules": [],
289+
"virtualNetworkRules": [
290+
{
291+
"id": "[concat(parameters('target_subnet_name'), concat('/subnets/', parameters('target_subnet_name')]",
292+
"ignoreMissingVnetServiceEndpoint": false
293+
}
294+
]
295+
}
296+
```
297+
298+
---
299+
300+
### Redeploy
301+
302+
Deploy the template to create a new key vault in the target region.
303+
304+
#### [Portal](#tab/azure-portal)
305+
306+
1. Save the **template.json** file.
307+
308+
2. Enter or select the property values:
309+
310+
- **Subscription**: Select an Azure subscription.
311+
312+
- **Resource group**: Select **Create new** and give the resource group a name.
313+
314+
- **Location**: Select an Azure location.
315+
316+
3. Select **I agree to the terms and conditions stated above**, and then select **Select Purchase**.
317+
318+
4. Access Policies and Network configuration settings (private endpoints) need to be re-configured in the new Key Vault. Soft delete and purge protection need to be re-configured in the new key vault and the _Autorotation settings_.
319+
320+
#### [PowerShell](#tab/azure-powershell)
321+
322+
1. Obtain the subscription ID where you want to deploy the target public IP with [Get-AzSubscription](/powershell/module/az.accounts/get-azsubscription):
323+
324+
```azurepowershell-interactive
325+
Get-AzSubscription
326+
```
327+
328+
2. Use these commands to deploy your template:
329+
330+
```azurepowershell-interactive
331+
$resourceGroupName = Read-Host -Prompt "Enter the Resource Group name"
332+
$location = Read-Host -Prompt "Enter the location (i.e. eastus)"
333+
334+
New-AzResourceGroup -Name $resourceGroupName -Location "$location"
335+
New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateUri "<name of your local template file>"
336+
```
337+
338+
3. Access Policies and Network configuration settings (private endpoints) need to be re-configured in the new Key Vault. Soft delete and purge protection need to be re-configured in the new key vault and as the _Autorotation settings_.
339+
---
340+
341+
342+
> [!TIP]
343+
> If you receive an error which states that the XML specified is not syntactically valid, compare the JSON in your template with the schemas described in the Azure Resource Manager documentation.
344+
345+
### Redeploy with data migration
346+
347+
>[!IMPORTANT]
348+
>If you plan to move a Key Vault across regions but within the same geography, it's recommended that you do a [backup and restore for secrets, keys and certificates](/azure/key-vault/general/backup) is recommended.
349+
350+
1. Follow steps in the described in the [redeploy approach](#redeploy).
351+
2. For [secrets](/azure/key-vault/secrets/about-secrets):
352+
1. Copy and save the secret value in the source key vault.
353+
1. Recreate the secret in the target key vault and set the value to saved secret.
354+
1. For [certificates](/azure/key-vault/certificates/about-certificates):
355+
1. Export the certificate into a PFX file.
356+
1. Import the PFX file into the target key vault. If you can't export the private key (`exportable` is not set) you must generate certificate a new certificate and import it into the target key vault.
357+
1. With the relocation of the associated Azure service the [keys](/azure/key-vault/keys/about-keys) are regenerated.
358+
1. Confirm that the keys have been generated for the associated service.
359+
360+
## Verify
54361

362+
Before deleting your old key vault, verify that the new vault contains all of the required keys, secrets, and certificates after the relocation of the associated Azure services.
55363

56-
## Next steps
364+
## Links
57365

58366
- [Azure Key Vault backup and restore](/azure/key-vault/general/backup)
59367
- [Moving an Azure Key Vault across resource groups](/azure/key-vault/general/move-resourcegroup)

0 commit comments

Comments
 (0)