Skip to content

Commit 45b0c4a

Browse files
Stacyrch140Stacyrch140
authored
Merge pull request #267369 from zfengms/zfeng/kvexttemplate
add KeyVault Extension for Windows template and troubleshooting information
2 parents 4ba158d + 75b6b02 commit 45b0c4a

File tree

2 files changed

+196
-35
lines changed

2 files changed

+196
-35
lines changed

‎articles/batch/automatic-certificate-rotation.md

Lines changed: 87 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,32 @@
11
---
22
title: Enable automatic certificate rotation in a Batch pool
3-
description: You can create a Batch pool with a managed identity and a certificate that will automatically be renewed.
3+
description: You can create a Batch pool with a managed identity and a certificate that can automatically be renewed.
44
ms.topic: conceptual
55
ms.custom: linux-related-content
66
ms.date: 12/05/2023
77
---
8+
89
# Enable automatic certificate rotation in a Batch pool
910

10-
You can create a Batch pool with a certificate that will automatically be renewed. To do so, your pool must be created with a [user-assigned managed identity](managed-identity-pools.md) that will have access to the certificate in [Azure Key Vault](../key-vault/general/overview.md).
11+
You can create a Batch pool with a certificate that can automatically be renewed. To do so, your pool must be created with a [user-assigned managed identity](managed-identity-pools.md) that has access to the certificate in [Azure Key Vault](../key-vault/general/overview.md).
1112

1213
## Create a user-assigned identity
1314

1415
First, [create your user-assigned managed identity](../active-directory/managed-identities-azure-resources/how-to-manage-ua-identity-portal.md#create-a-user-assigned-managed-identity) in the same tenant as your Batch account. This managed identity doesn't need to be in the same resource group or even in the same subscription.
1516

16-
Be sure to note the **Client ID** of the user-assigned managed identity. You'll need this value later.
17+
Be sure to note the **Client ID** of the user-assigned managed identity. You need this value later.
1718

1819
:::image type="content" source="media/automatic-certificate-rotation/client-id.png" alt-text="Screenshot showing the client ID of a user-assigned managed identity in the Azure portal.":::
1920

2021
## Create your certificate
2122

22-
Next, you'll need to create a certificate and add it to Azure Key Vault. If you haven't already created a key vault, you'll need to do that first. For instructions, see [Quickstart: Set and retrieve a certificate from Azure Key Vault using the Azure portal](../key-vault/certificates/quick-create-portal.md).
23+
Next, you need to create a certificate and add it to Azure Key Vault. If you haven't already created a key vault, you need to do that first. For instructions, see [Quickstart: Set and retrieve a certificate from Azure Key Vault using the Azure portal](../key-vault/certificates/quick-create-portal.md).
2324

2425
When creating your certificate, be sure to set **Lifetime Action Type** to automatically renew, and specify the number of days after which the certificate should renew.
2526

2627
:::image type="content" source="media/automatic-certificate-rotation/certificate.png" alt-text="Screenshot of the certificate creation screen in the Azure portal.":::
2728

28-
After your certificate has been created, make note of its **Secret Identifier**. You'll need this value later.
29+
After your certificate has been created, make note of its **Secret Identifier**. You need this value later.
2930

3031
:::image type="content" source="media/automatic-certificate-rotation/secret-identifier.png" alt-text="Screenshot showing the Secret Identifier of a certificate.":::
3132

@@ -48,7 +49,68 @@ REST API URI
4849
PUT https://management.azure.com/subscriptions/<subscriptionid>/resourceGroups/<resourcegroupName>/providers/Microsoft.Batch/batchAccounts/<batchaccountname>/pools/<poolname>?api-version=2021-01-01
4950
```
5051

51-
Request Body
52+
Request Body for Linux node
53+
54+
```json
55+
{
56+
"name": "test2",
57+
"type": "Microsoft.Batch/batchAccounts/pools",
58+
"properties": {
59+
"vmSize": "STANDARD_DS2_V2",
60+
"taskSchedulingPolicy": {
61+
"nodeFillType": "Pack"
62+
},
63+
"deploymentConfiguration": {
64+
"virtualMachineConfiguration": {
65+
"imageReference": {
66+
"publisher": "canonical",
67+
"offer": "ubuntuserver",
68+
"sku": "20.04-lts",
69+
"version": "latest"
70+
},
71+
"nodeAgentSkuId": "batch.node.ubuntu 20.04",
72+
"extensions": [
73+
{
74+
"name": "KVExtensions",
75+
"type": "KeyVaultForLinux",
76+
"publisher": "Microsoft.Azure.KeyVault",
77+
"typeHandlerVersion": "3.0",
78+
"autoUpgradeMinorVersion": true,
79+
"settings": {
80+
"secretsManagementSettings": {
81+
"pollingIntervalInS": "300",
82+
"certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault",
83+
"requireInitialSync": true,
84+
"observedCertificates": [
85+
"https://testkvwestus2s.vault.azure.net/secrets/authcertforumatesting/8f5f3f491afd48cb99286ba2aacd39af"
86+
]
87+
},
88+
"authenticationSettings": {
89+
"msiEndpoint": "http://169.254.169.254/metadata/identity",
90+
"msiClientId": "b9f6dd56-d2d6-4967-99d7-8062d56fd84c"
91+
}
92+
}
93+
}
94+
]
95+
}
96+
},
97+
"scaleSettings": {
98+
"fixedScale": {
99+
"targetDedicatedNodes": 1,
100+
"resizeTimeout": "PT15M"
101+
}
102+
}
103+
},
104+
"identity": {
105+
"type": "UserAssigned",
106+
"userAssignedIdentities": {
107+
"/subscriptions/042998e4-36dc-4b7d-8ce3-a7a2c4877d33/resourceGroups/ACR/providers/Microsoft.ManagedIdentity/userAssignedIdentities/testumaforpools": {}
108+
}
109+
}
110+
}
111+
```
112+
113+
Request Body for Windows node
52114

53115
```json
54116
{
@@ -62,26 +124,29 @@ Request Body
62124
"deploymentConfiguration": {
63125
"virtualMachineConfiguration": {
64126
"imageReference": {
65-
"publisher": "canonical",
66-
"offer": "ubuntuserver",
67-
"sku": "20.04-lts",
127+
"publisher": "microsoftwindowsserver",
128+
"offer": "windowsserver",
129+
"sku": "2022-datacenter",
68130
"version": "latest"
69131
},
70-
"nodeAgentSkuId": "batch.node.ubuntu 20.04",
132+
"nodeAgentSkuId": "batch.node.windows amd64",
71133
"extensions": [
72134
{
73135
"name": "KVExtensions",
74-
"type": "KeyVaultForLinux",
136+
"type": "KeyVaultForWindows",
75137
"publisher": "Microsoft.Azure.KeyVault",
76-
"typeHandlerVersion": "1.0",
138+
"typeHandlerVersion": "3.0",
77139
"autoUpgradeMinorVersion": true,
78140
"settings": {
79141
"secretsManagementSettings": {
80142
"pollingIntervalInS": "300",
81-
"certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault",
82143
"requireInitialSync": true,
83144
"observedCertificates": [
84-
"https://testkvwestus2s.vault.azure.net/secrets/authcertforumatesting/8f5f3f491afd48cb99286ba2aacd39af"
145+
{
146+
"https://testkvwestus2s.vault.azure.net/secrets/authcertforumatesting/8f5f3f491afd48cb99286ba2aacd39af",
147+
"certificateStoreLocation": "LocalMachine",
148+
"keyExportable": true
149+
}
85150
]
86151
},
87152
"authenticationSettings": {
@@ -112,13 +177,20 @@ Request Body
112177

113178
## Validate the certificate
114179

115-
To confirm that the certificate has been successfully deployed, log in to the compute node. You should see output similar to the following:
180+
To confirm that the certificate is successfully deployed, log in to the compute node. You should see output similar to the following:
116181

117182
```
118183
root@74773db5fe1b42ab9a4b6cf679d929da000000:/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-1.0.1363.13/status# cat 1.status
119184
[{"status":{"code":0,"formattedMessage":{"lang":"en","message":"Successfully started Key Vault extension service. 2021-03-03T23:12:23Z"},"operation":"Service start.","status":"success"},"timestampUTC":"2021-03-03T23:12:23Z","version":"1.0"}]root@74773db5fe1b42ab9a4b6cf679d929da000000:/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-1.0.1363.13/status#
120185
```
121186

187+
## Troubleshooting Key Vault Extension
188+
189+
If Key Vault extension is configured incorrectly, the compute node might be in usuable state. To troubleshoot Key Vault extension failure, you can temporarily set requireInitialSync to false and redeploy your pool, then the compute node is in idle state, you can log in to the compute node to check KeyVault extension logs for errors and fix the configuration issues. Visit following Key Vault extension doc link for more information.
190+
191+
- [Azure Key Vault extension for Linux](../virtual-machines/extensions/key-vault-linux.md)
192+
- [Azure Key Vault extension for Windows](../virtual-machines/extensions/key-vault-windows.md)
193+
122194
## Next steps
123195

124196
- Learn more about [Managed identities for Azure resources](../active-directory/managed-identities-azure-resources/overview.md).

‎articles/batch/create-pool-extensions.md

Lines changed: 109 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,15 @@ ms.date: 12/05/2023
88

99
# Use extensions with Batch pools
1010

11-
Extensions are small applications that facilitate post-provisioning configuration and setup on Batch compute nodes. You can select any of the extensions that are allowed by Azure Batch and have them installed on the compute nodes as they're provisioned. After that, the extension can perform its intended operation.
11+
Extensions are small applications that facilitate post-provisioning configuration and setup on Batch compute nodes. You can select any of the extensions that are allowed by Azure Batch and install them on the compute nodes as they're provisioned. After that, the extension can perform its intended operation.
1212

1313
You can check the live status of the extensions you use and retrieve the information they return in order to pursue any detection, correction, or diagnostics capabilities.
1414

1515
## Prerequisites
1616

1717
- Pools with extensions must use [Virtual Machine Configuration](nodes-and-pools.md#virtual-machine-configuration).
1818
- The CustomScript extension type is reserved for the Azure Batch service and can't be overridden.
19-
- Some extensions may need pool-level Managed Identity accessible in the context of a compute node in order to function properly. Please see [configuring managed identities in Batch pools](managed-identity-pools.md) if applicable for the extension(s).
19+
- Some extensions may need pool-level Managed Identity accessible in the context of a compute node in order to function properly. See [configuring managed identities in Batch pools](managed-identity-pools.md) if applicable for the extensions.
2020

2121
> [!TIP]
2222
> Extensions cannot be added to an existing pool. Pools must be recreated to add, remove, or update extensions.
@@ -38,19 +38,82 @@ The following extensions can currently be installed when creating a Batch pool:
3838
- [Azure Monitor agent for Linux](../azure-monitor/agents/azure-monitor-agent-manage.md)
3939
- [Azure Monitor agent for Windows](../azure-monitor/agents/azure-monitor-agent-manage.md)
4040

41-
You can request support for additional publishers and/or extension types by opening a support request.
41+
You can request support for other publishers and/or extension types by opening a support request.
4242

4343
## Create a pool with extensions
4444

45-
The example below creates a Batch pool of Linux nodes that uses the Azure Key Vault extension.
45+
The following example creates a Batch pool of Linux/Windows nodes that uses the Azure Key Vault extension.
4646

4747
REST API URI
4848

4949
```http
5050
PUT https://management.azure.com/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.Batch/batchAccounts/<batchaccountName>/pools/<batchpoolName>?api-version=2021-01-01
5151
```
5252

53-
Request Body
53+
Request Body for Linux node
54+
55+
```json
56+
{
57+
"name": "test1",
58+
"type": "Microsoft.Batch/batchAccounts/pools",
59+
"properties": {
60+
"vmSize": "STANDARD_DS2_V2",
61+
"taskSchedulingPolicy": {
62+
"nodeFillType": "Pack"
63+
},
64+
"deploymentConfiguration": {
65+
"virtualMachineConfiguration": {
66+
"imageReference": {
67+
"publisher": "microsoftcblmariner",
68+
"offer": "cbl-mariner",
69+
"sku": "cbl-mariner-2",
70+
"version": "latest"
71+
},
72+
"nodeAgentSkuId": "batch.node.mariner 2.0",
73+
"extensions": [
74+
{
75+
"name": "secretext",
76+
"type": "KeyVaultForLinux",
77+
"publisher": "Microsoft.Azure.KeyVault",
78+
"typeHandlerVersion": "3.0",
79+
"autoUpgradeMinorVersion": true,
80+
"settings": {
81+
"secretsManagementSettings": {
82+
"pollingIntervalInS": "300",
83+
"certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault",
84+
"requireInitialSync": true,
85+
"observedCertificates": [
86+
"https://testkvwestus2.vault.azure.net/secrets/authsecreat"
87+
]
88+
},
89+
"authenticationSettings": {
90+
"msiEndpoint": "http://169.254.169.254/metadata/identity",
91+
"msiClientId": "885b1a3d-f13c-4030-afcf-9f05044d78dc"
92+
}
93+
},
94+
"protectedSettings": {}
95+
}
96+
]
97+
}
98+
},
99+
"scaleSettings": {
100+
"fixedScale": {
101+
"targetDedicatedNodes": 1,
102+
"targetLowPriorityNodes": 0,
103+
"resizeTimeout": "PT15M"
104+
}
105+
}
106+
},
107+
"identity": {
108+
"type": "UserAssigned",
109+
"userAssignedIdentities": {
110+
"/subscriptions/042998e4-36dc-4b7d-8ce3-a7a2c4877d33/resourceGroups/ACR/providers/Microsoft.ManagedIdentity/userAssignedIdentities/testumaforpools": {}
111+
}
112+
}
113+
}
114+
```
115+
116+
Request Body for Windows node
54117

55118
```json
56119
{
@@ -64,26 +127,29 @@ Request Body
64127
"deploymentConfiguration": {
65128
"virtualMachineConfiguration": {
66129
"imageReference": {
67-
"publisher": "microsoftcblmariner",
68-
"offer": "cbl-mariner",
69-
"sku": "cbl-mariner-2",
130+
"publisher": "microsoftwindowsserver",
131+
"offer": "windowsserver",
132+
"sku": "2022-datacenter",
70133
"version": "latest"
71134
},
72-
"nodeAgentSkuId": "batch.node.mariner 2.0",
135+
"nodeAgentSkuId": "batch.node.windows amd64",
73136
"extensions": [
74137
{
75138
"name": "secretext",
76-
"type": "KeyVaultForLinux",
139+
"type": "KeyVaultForWindows",
77140
"publisher": "Microsoft.Azure.KeyVault",
78-
"typeHandlerVersion": "1.0",
141+
"typeHandlerVersion": "3.0",
79142
"autoUpgradeMinorVersion": true,
80143
"settings": {
81144
"secretsManagementSettings": {
82145
"pollingIntervalInS": "300",
83-
"certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault",
84146
"requireInitialSync": true,
85147
"observedCertificates": [
86-
"https://testkvwestus2.vault.azure.net/secrets/authsecreat"
148+
{
149+
"https://testkvwestus2.vault.azure.net/secrets/authsecreat"
150+
"certificateStoreLocation": "LocalMachine",
151+
"keyExportable": true
152+
}
87153
]
88154
},
89155
"authenticationSettings": {
@@ -103,13 +169,19 @@ Request Body
103169
"resizeTimeout": "PT15M"
104170
}
105171
}
172+
},
173+
"identity": {
174+
"type": "UserAssigned",
175+
"userAssignedIdentities": {
176+
"/subscriptions/042998e4-36dc-4b7d-8ce3-a7a2c4877d33/resourceGroups/ACR/providers/Microsoft.ManagedIdentity/userAssignedIdentities/testumaforpools": {}
177+
}
106178
}
107179
}
108180
```
109181

110182
## Get extension data from a pool
111183

112-
The example below retrieves data from the Azure Key Vault extension.
184+
The following example retrieves data from the Azure Key Vault extension.
113185

114186
REST API URI
115187

@@ -121,19 +193,36 @@ Response Body
121193

122194
```json
123195
{
124-
"odata.metadata":"https://testwestus2batch.westus2.batch.azure.com/$metadata#extensions/@Element","instanceView":{
125-
"name":"secretext","statuses":[
196+
"odata.metadata": "https://testwestus2batch.westus2.batch.azure.com/$metadata#extensions/@Element",
197+
"instanceView": {
198+
"name": "secretext",
199+
"statuses": [
126200
{
127-
"code":"ProvisioningState/succeeded","level":0,"displayStatus":"Provisioning succeeded","message":"Successfully started Key Vault extension service. 2021-02-08T19:49:39Z"
201+
"code": "ProvisioningState/succeeded",
202+
"level": 0,
203+
"displayStatus": "Provisioning succeeded",
204+
"message": "Successfully started Key Vault extension service. 2021-02-08T19:49:39Z"
128205
}
129206
]
130-
},"vmExtension":{
131-
"name":"KVExtensions","publisher":"Microsoft.Azure.KeyVault","type":"KeyVaultForLinux","typeHandlerVersion":"1.0","autoUpgradeMinorVersion":true,"settings":"{\r\n \"secretsManagementSettings\": {\r\n \"pollingIntervalInS\": \"300\",\r\n \"certificateStoreLocation\": \"/var/lib/waagent/Microsoft.Azure.KeyVault\",\r\n \"requireInitialSync\": true,\r\n \"observedCertificates\": [\r\n \"https://testkvwestus2.vault.azure.net/secrets/testumi\"\r\n ]\r\n },\r\n \"authenticationSettings\": {\r\n \"msiEndpoint\": \"http://169.254.169.254/metadata/identity\",\r\n \"msiClientId\": \"885b1a3d-f13c-4030-afcf-922f05044d78dc\"\r\n }\r\n}"
207+
},
208+
"vmExtension": {
209+
"name": "KVExtensions",
210+
"publisher": "Microsoft.Azure.KeyVault",
211+
"type": "KeyVaultForLinux",
212+
"typeHandlerVersion": "1.0",
213+
"autoUpgradeMinorVersion": true,
214+
"settings": "{\r\n \"secretsManagementSettings\": {\r\n \"pollingIntervalInS\": \"300\",\r\n \"certificateStoreLocation\": \"/var/lib/waagent/Microsoft.Azure.KeyVault\",\r\n \"requireInitialSync\": true,\r\n \"observedCertificates\": [\r\n \"https://testkvwestus2.vault.azure.net/secrets/testumi\"\r\n ]\r\n },\r\n \"authenticationSettings\": {\r\n \"msiEndpoint\": \"http://169.254.169.254/metadata/identity\",\r\n \"msiClientId\": \"885b1a3d-f13c-4030-afcf-922f05044d78dc\"\r\n }\r\n}"
132215
}
133216
}
134-
135217
```
136218

219+
## Troubleshooting Key Vault Extension
220+
221+
If Key Vault extension is configured incorrectly, the compute node might be in a usable state. To troubleshoot Key Vault extension failure, you can temporarily set requireInitialSync to false and redeploy your pool, then the compute node is in idle state, you can log in to the compute node to check KeyVault extension logs for errors and fix the configuration issues. Visit following Key Vault extension doc link for more information.
222+
223+
- [Azure Key Vault extension for Linux](../virtual-machines/extensions/key-vault-linux.md)
224+
- [Azure Key Vault extension for Windows](../virtual-machines/extensions/key-vault-windows.md)
225+
137226
## Next steps
138227

139228
- Learn about various ways to [copy applications and data to pool nodes](batch-applications-to-pool-nodes.md).

0 commit comments

Comments
 (0)