Skip to content

Commit aca8d4e

Browse files
jlichwajlichwa
authored
Update key-vault-linux.md
1 parent dffe957 commit aca8d4e

File tree

1 file changed

+247
-11
lines changed

1 file changed

+247
-11
lines changed

‎articles/virtual-machines/extensions/key-vault-linux.md

Lines changed: 247 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ ms.custom: devx-track-azurepowershell, devx-track-azurecli, linux-related-conten
1515

1616
The Key Vault VM extension provides automatic refresh of certificates stored in an Azure key vault. Specifically, the extension monitors a list of observed certificates stored in key vaults. The extension retrieves and installs the corresponding certificates after detecting a change. This document details the supported platforms, configurations, and deployment options for the Key Vault VM extension for Linux.
1717

18-
### Operating system
18+
## Operating system
1919

2020
The Key Vault VM extension supports these Linux distributions:
2121

@@ -30,6 +30,16 @@ The Key Vault VM extension supports these Linux distributions:
3030
- PKCS #12
3131
- PEM
3232

33+
## Updates in Version 3.0+
34+
35+
Version 3.0+ of the Key Vault VM extension for Linux adds support for the following features:
36+
37+
- Add ACL permissions for downloaded certificates
38+
- Certificate installation location configuration
39+
- Custom symbolic name support
40+
- VM extension logging integration support through [Fluentd](https://www.fluentd.org/)
41+
42+
3343
## Prerequisites
3444
- Key Vault instance with certificate. See [Create a Key Vault](../../key-vault/general/quick-create-portal.md)
3545
- Assigned [managed identity](../../active-directory/managed-identities-azure-resources/overview.md) on VM/VMSS
@@ -56,20 +66,88 @@ The Key Vault VM extension supports these Linux distributions:
5666
`
5767
## Key Vault VM extension version
5868

59-
* Users can choose to upgrade their Key Vault vm extension version to `V2.0` to use full certificate chain download feature. Issuer certificates (intermediate and root) are included with leaf certificate in the PEM file.
69+
* Users can choose to upgrade their existing Key Vault vn extension version to newer version.
6070

61-
* If you prefer to upgrade to `v2.0`, you would need to delete `v1.0` first, then install `v2.0`.
71+
* If you prefer to upgrade to newer version, you would need to delete previous version first, then install newer version.
6272
```azurecli
6373
az vm extension delete --name KeyVaultForLinux --resource-group ${resourceGroup} --vm-name ${vmName}
64-
az vm extension set -n "KeyVaultForLinux" --publisher Microsoft.Azure.KeyVault --resource-group "${resourceGroup}" --vm-name "${vmName}" –settings .\akvvm.json –version 2.0
74+
az vm extension set -n "KeyVaultForLinux" --publisher Microsoft.Azure.KeyVault --resource-group "${resourceGroup}" --vm-name "${vmName}" –settings .\akvvm.json –version 3.0
6575
```
66-
The flag --version 2.0 is optional because the latest version is installed by default.
76+
The flag --version 3.0 is optional because the latest version is installed by default.
6777

68-
* If the VM has certificates downloaded by v1.0, deleting the v1.0 AKVVM extension doesn't delete the downloaded certificates. After installing v2.0, the existing certificates aren't modified. You would need to delete the certificate files or roll-over the certificate to get the PEM file with full-chain on the VM.
78+
* If the VM has certificates downloaded by previous version, deleting VM extension doesn't delete the downloaded certificates. After installing newer version, the existing certificates aren't modified. You would need to delete the certificate files or roll-over the certificate to get the PEM file with full-chain on the VM.
6979

7080
## Extension schema
7181

7282
The following JSON shows the schema for the Key Vault VM extension. The extension doesn't require protected settings - all its settings are considered information without security impact. The extension requires a list of monitored secrets, polling frequency, and the destination certificate store. Specifically:
83+
84+
### [Version-3.0](#tab/version3)
85+
86+
```json
87+
{
88+
"type": "Microsoft.Compute/virtualMachines/extensions",
89+
"name": "KVVMExtensionForLinux",
90+
"apiVersion": "2022-11-01",
91+
"location": "<location>",
92+
"dependsOn": [
93+
"[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
94+
],
95+
"properties": {
96+
"publisher": "Microsoft.Azure.KeyVault",
97+
"type": "KeyVaultForLinux",
98+
"typeHandlerVersion": "3.0",
99+
"autoUpgradeMinorVersion": true,
100+
"enableAutomaticUpgrade": true,
101+
"settings": {
102+
"loggingSettings": {
103+
"logger": <Logger engine name. e.g.: "fluentd">,
104+
"endpoint": <Logger listening endpoint "unix:///var/run/azuremonitoragent/sometenant/default_fluent.socket">,
105+
"format": <Logging format. e.g.: "forward">,
106+
"servicename": <Service name used in logs. e.g.: "akvvm_service">
107+
},
108+
"secretsManagementSettings": {
109+
"pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
110+
"linkOnRenewal": <Not available on Linux e.g.: false>,
111+
"requireInitialSync": <initial synchronization of certificates e..g: true>,
112+
"aclEnabled": <Enables ACLs for downloaded certificates, e.g.: true>,
113+
"observedCertificates": <An array of KeyVault URIs that represent monitored certificates, including certificate store location, ACL permission to certificate private key, and custom symbolic name. e.g.:
114+
[
115+
{
116+
"url": <A Key Vault URI to the secret portion of the certificate. e.g.: "https://myvault.vault.azure.net/secrets/mycertificate1">,
117+
"certificateStoreLocation": <disk path where certificate is stored, e.g.: "/var/lib/waagent/Microsoft.Azure.KeyVault/app1">,
118+
"customSymbolicLinkName": <symbolic name for the certificate. e.g.: "app1Cert1">,
119+
"acls": [
120+
{
121+
"user": "app1",
122+
"group": "appGroup1"
123+
},
124+
{
125+
"user": "service1"
126+
}
127+
]
128+
},
129+
{
130+
"url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate2">,
131+
"certificateStoreLocation": <disk path where the certificate is stored, e.g.: "/var/lib/waagent/Microsoft.Azure.KeyVault/app2">,
132+
"acls": [
133+
{
134+
"user": "app2",
135+
}
136+
]
137+
}
138+
]>
139+
},
140+
"authenticationSettings": {
141+
"msiEndpoint": <Required when msiClientId is provided. MSI endpoint e.g. for most Azure VMs: "http://169.254.169.254/metadata/identity">,
142+
"msiClientId": <Required when VM has any user assigned identities. MSI identity e.g.: "c7373ae5-91c2-4165-8ab6-7381d6e75619".>
143+
}
144+
}
145+
}
146+
}
147+
```
148+
149+
### [Version-1.0/2.0](#tab/version12)
150+
73151
```json
74152
{
75153
"type": "Microsoft.Compute/virtualMachines/extensions",
@@ -103,6 +181,8 @@ The following JSON shows the schema for the Key Vault VM extension. The extensio
103181
}
104182
```
105183

184+
---
185+
106186
> [!NOTE]
107187
> Your observed certificates URLs should be of the form `https://myVaultName.vault.azure.net/secrets/myCertName`.
108188
>
@@ -117,6 +197,34 @@ The following JSON shows the schema for the Key Vault VM extension. The extensio
117197
118198
### Property values
119199

200+
#### [Version-3.0](#tab/version3)
201+
202+
| Name | Value / Example | Data Type |
203+
| ---- | ---- | ---- |
204+
| apiVersion | 2022-07-01 | date |
205+
| publisher | Microsoft.Azure.KeyVault | string |
206+
| type | KeyVaultForLinux | string |
207+
| typeHandlerVersion | 3.0 | int |
208+
| pollingIntervalInS | 3600 | string |
209+
| certificateStoreName | It's ignored on Linux | string |
210+
| linkOnRenewal | false | boolean |
211+
| requireInitialSync | true | boolean |
212+
| certificateStoreLocation | /var/lib/waagent/Microsoft.Azure.KeyVault.Store | string |
213+
| observedCertificates | [{...}, {...}] | string array |
214+
| observedCertificates/url | "https://myvault.vault.azure.net/secrets/mycertificate1" | string |
215+
| observedCertificates/certificateStoreLocation | "/var/lib/waagent/Microsoft.Azure.KeyVault/app1" | string |
216+
| observedCertificates/customSymbolicLinkName | "app1Cert1" | string |
217+
| observedCertificates/acls | "{...}, {...}" | string array |
218+
| msiEndpoint | http://169.254.169.254/metadata/identity | string |
219+
| msiClientId | c7373ae5-91c2-4165-8ab6-7381d6e75619 | string |
220+
| logger | "fluentd" | string |
221+
| endpoint | "unix:///var/run/azuremonitoragent/sometenant/default_fluent.socket" | string |
222+
| format | "forward" | string |
223+
| servicename | "akvvm_service" | string |
224+
225+
226+
#### [Version-1.0/2.0](#tab/version12)
227+
120228
| Name | Value / Example | Data Type |
121229
| ---- | ---- | ---- |
122230
| apiVersion | 2022-07-01 | date |
@@ -132,6 +240,8 @@ The following JSON shows the schema for the Key Vault VM extension. The extensio
132240
| msiEndpoint | http://169.254.169.254/metadata/identity | string |
133241
| msiClientId | c7373ae5-91c2-4165-8ab6-7381d6e75619 | string |
134242

243+
---
244+
135245
## Template deployment
136246

137247
Azure VM extensions can be deployed with Azure Resource Manager templates. Templates are ideal when deploying one or more virtual machines that require post deployment refresh of certificates. The extension can be deployed to individual VMs or virtual machine scale sets. The schema and configuration are common to both template types.
@@ -142,6 +252,74 @@ The JSON configuration for a virtual machine extension must be nested inside the
142252
> The VM extension would require system or user managed identity to be assigned to authenticate to Key vault. See [How to authenticate to Key Vault and assign a Key Vault access policy.](../../active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm.md)
143253
>
144254
255+
### [Version-3.0](#tab/version3)
256+
257+
```json
258+
{
259+
"type": "Microsoft.Compute/virtualMachines/extensions",
260+
"name": "KeyVaultForLinux",
261+
"apiVersion": "2022-11-01",
262+
"location": "<location>",
263+
"dependsOn": [
264+
"[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
265+
],
266+
"properties": {
267+
"publisher": "Microsoft.Azure.KeyVault",
268+
"type": "KeyVaultForLinux",
269+
"typeHandlerVersion": "3.0",
270+
"autoUpgradeMinorVersion": true,
271+
"enableAutomaticUpgrade": true,
272+
"settings": {
273+
"loggingSettings": {
274+
"logger": <Logger engine name. e.g.: "fluentd">,
275+
"endpoint": <Logger listening endpoint "unix:///var/run/azuremonitoragent/sometenant/default_fluent.socket">,
276+
"format": <Logging format. e.g.: "forward">,
277+
"servicename": <Service name used in logs. e.g.: "akvvm_service">
278+
},
279+
"secretsManagementSettings": {
280+
"pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
281+
"requireInitialSync": <initial synchronization of certificates e..g: false>,
282+
"observedCertificates": <An array of KeyVault URIs that represent monitored certificates, including certificate store location and ACL permission to certificate private key. Example:
283+
[
284+
{
285+
"url": <A Key Vault URI to the secret portion of the certificate. Example: "https://myvault.vault.azure.net/secrets/mycertificate1">,
286+
"certificateStoreLocation": <The certificate store location, which currently works locally only. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault.Store">,
287+
"acls": <Optional. An array of preferred acls with read access to certificate private keys. Example:
288+
[
289+
{
290+
"user": "app1",
291+
"group": "appGroup1"
292+
},
293+
{
294+
"user": "service1"
295+
}
296+
]>
297+
},
298+
{
299+
"url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate2">,
300+
"certificateStoreName": <ignored on linux>,
301+
"certificateStoreLocation": <The certificate store location, which currently works locally only. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault.Store">,
302+
"acls": <Optional. An array of preferred acls with read access to certificate private keys. Example:
303+
[
304+
{
305+
"user": "app2"
306+
}
307+
]>
308+
}
309+
310+
]>
311+
},
312+
"authenticationSettings": {
313+
"msiEndpoint": <Required when msiClientId is provided. MSI endpoint e.g. for most Azure VMs: "http://169.254.169.254/metadata/identity">,
314+
"msiClientId": <Required when VM has any user assigned identities. MSI identity e.g.: "c7373ae5-91c2-4165-8ab6-7381d6e75619">
315+
}
316+
}
317+
}
318+
}
319+
```
320+
321+
### [Version-1.0/2.0](#tab/version12)
322+
145323
```json
146324
{
147325
"type": "Microsoft.Compute/virtualMachines/extensions",
@@ -160,16 +338,23 @@ The JSON configuration for a virtual machine extension must be nested inside the
160338
"settings": {
161339
"secretsManagementSettings": {
162340
"pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
163-
"certificateStoreName": <ingnored on linux>,
341+
"certificateStoreName": <ignored on linux>,
164342
"certificateStoreLocation": <disk path where certificate is stored, default: "/var/lib/waagent/Microsoft.Azure.KeyVault">,
165343
"observedCertificates": <list of KeyVault URIs representing monitored certificates, e.g.: "https://myvault.vault.azure.net/secrets/mycertificate"
344+
},
345+
"authenticationSettings": {
346+
"msiEndpoint": <Required when msiClientId is provided. MSI endpoint e.g. for most Azure VMs: "http://169.254.169.254/metadata/identity">,
347+
"msiClientId": <Required when VM has any user assigned identities. MSI identity e.g.: "c7373ae5-91c2-4165-8ab6-7381d6e75619">
348+
}
166349
}
167350
}
168-
}
169351
}
170352
```
171353

354+
---
355+
172356
### Extension Dependency Ordering
357+
173358
The Key Vault VM extension supports extension ordering if configured. By default the extension reports successful start as soon as polling starts. However, you can configure it to wait until it successfully download the complete list of certificates before reporting a successful start. If other extensions depend on installed certificates before they start, then enabling this setting will allow those extensions to declare a dependency on the Key Vault extension. This will prevent those extensions from starting until all certificates they depend on have been installed. The extension will retry the initial download indefinitely and remain in a `Transitioning` state.
174359

175360
To turn on extension dependency, set the following:
@@ -190,7 +375,10 @@ The Azure PowerShell can be used to deploy the Key Vault VM extension to an exis
190375

191376
* To deploy the extension on a VM:
192377

378+
### [Version-3.0](#tab/version3)
379+
193380
```powershell
381+
194382
# Build settings
195383
$settings = '{"secretsManagementSettings":
196384
{ "pollingIntervalInS": "' + <pollingInterval> +
@@ -227,14 +415,60 @@ The Azure PowerShell can be used to deploy the Key Vault VM extension to an exis
227415
228416
# Start the deployment
229417
Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss
418+
```
419+
420+
### [Version-1.0/2.0](#tab/version12)
421+
422+
```powershell
423+
# Build settings
424+
$settings = '{"secretsManagementSettings":
425+
{ "pollingIntervalInS": "' + <pollingInterval> +
426+
'", "certificateStoreName": "' + <certStoreName> +
427+
'", "certificateStoreLocation": "' + <certStoreLoc> +
428+
'", "observedCertificates": ["' + <observedCert1> + '","' + <observedCert2> + '"] } }'
429+
$extName = "KeyVaultForLinux"
430+
$extPublisher = "Microsoft.Azure.KeyVault"
431+
$extType = "KeyVaultForLinux"
432+
433+
434+
# Start the deployment
435+
Set-AzVmExtension -TypeHandlerVersion "2.0" -EnableAutomaticUpgrade true -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings
436+
230437
```
231438
439+
* To deploy the extension on a virtual machine scale set:
440+
441+
```powershell
442+
443+
# Build settings
444+
$settings = '{"secretsManagementSettings":
445+
{ "pollingIntervalInS": "' + <pollingInterval> +
446+
'", "certificateStoreName": "' + <certStoreName> +
447+
'", "certificateStoreLocation": "' + <certStoreLoc> +
448+
'", "observedCertificates": ["' + <observedCert1> + '","' + <observedCert2> + '"] } }'
449+
$extName = "KeyVaultForLinux"
450+
$extPublisher = "Microsoft.Azure.KeyVault"
451+
$extType = "KeyVaultForLinux"
452+
453+
# Add Extension to VMSS
454+
$vmss = Get-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName>
455+
Add-AzVmssExtension -VirtualMachineScaleSet $vmss -Name $extName -Publisher $extPublisher -Type $extType -TypeHandlerVersion "2.0" -EnableAutomaticUpgrade true -Setting $settings
456+
457+
# Start the deployment
458+
Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss
459+
```
460+
---
461+
232462
## Azure CLI deployment
233463
234464
The Azure CLI can be used to deploy the Key Vault VM extension to an existing virtual machine or virtual machine scale set.
235465
236466
* To deploy the extension on a VM:
237467
468+
### [Version-3.0](#tab/version3)
469+
470+
### [Version-1.0/2.0](#tab/version12)
471+
238472
```azurecli
239473
# Start the deployment
240474
az vm extension set -n "KeyVaultForLinux" `
@@ -258,10 +492,12 @@ The Azure CLI can be used to deploy the Key Vault VM extension to an existing vi
258492
--enable-auto-upgrade true `
259493
--settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'
260494
```
495+
---
496+
261497
Please be aware of the following restrictions/requirements:
262498
- Key Vault restrictions:
263499
- It must exist at the time of the deployment
264-
- The Key Vault Access Policy must be set for VM/VMSS Identity using a Managed Identity. See [How to Authenticate to Key Vault](../../key-vault/general/authentication.md) and [Assign a Key Vault access policy](../../key-vault/general/assign-access-policy-cli.md).
500+
- The Key Vault Secrets User role must be assigned to Key Vault for VM identity
265501
266502
267503
## Troubleshoot and Support
@@ -278,11 +514,11 @@ Get-AzVMExtension -VMName <vmName> -ResourceGroupname <resource group name>
278514
az vm get-instance-view --resource-group <resource group name> --name <vmName> --query "instanceView.extensions"
279515
```
280516

281-
[!INCLUDE [azure-cli-troubleshooting.md](~/reusable-content/ce-skilling/azure/includes/azure-cli-troubleshooting.md)]
517+
[!INCLUDE [azure-cli-troubleshooting.md](../../../includes/azure-cli-troubleshooting.md)]
282518

283519
### Logs and configuration
284520

285-
The Key Vault VM extension logs only exist locally on the VM and are most informative when it comes to troubleshooting.
521+
The Key Vault VM extension logs exist locally on the VM and are most informative when it comes to troubleshooting.
286522

287523
|Location|Description|
288524
|--|--|

0 commit comments

Comments
 (0)