Skip to content

Commit b02e987

Browse files
prmerger-automator[bot]prmerger-automator[bot]
authored
Merge pull request #249946 from linglingye001/user/linglingye/keyVaultRefresh
Add key vault refresh feature in Kubernetes provider
2 parents 47cffed + de73bde commit b02e987

File tree

1 file changed

+86
-55
lines changed

1 file changed

+86
-55
lines changed

‎articles/azure-app-configuration/reference-kubernetes-provider.md

Lines changed: 86 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -20,100 +20,107 @@ An `AzureAppConfigurationProvider` resource has the following top-level child pr
2020

2121
|Name|Description|Required|Type|
2222
|---|---|---|---|
23-
|endpoint|The endpoint of Azure App Configuration, which you would like to retrieve the key-values from|alternative|string|
24-
|connectionStringReference|The name of the Kubernetes Secret that contains Azure App Configuration connection string|alternative|string|
25-
|target|The destination of the retrieved key-values in Kubernetes|true|object|
26-
|auth|The authentication method to access Azure App Configuration|false|object|
27-
|keyValues|The settings for querying and processing key-values|false|object|
23+
|endpoint|The endpoint of Azure App Configuration, which you would like to retrieve the key-values from.|alternative|string|
24+
|connectionStringReference|The name of the Kubernetes Secret that contains Azure App Configuration connection string.|alternative|string|
25+
|target|The destination of the retrieved key-values in Kubernetes.|true|object|
26+
|auth|The authentication method to access Azure App Configuration.|false|object|
27+
|keyValues|The settings for querying and processing key-values.|false|object|
2828

2929
The `spec.target` property has the following child property.
3030

3131
|Name|Description|Required|Type|
3232
|---|---|---|---|
33-
|configMapName|The name of the ConfigMap to be created|true|string|
34-
|configMapData|The setting that specifies how the retrieved data should be populated in the generated ConfigMap|false|object|
33+
|configMapName|The name of the ConfigMap to be created.|true|string|
34+
|configMapData|The setting that specifies how the retrieved data should be populated in the generated ConfigMap.|false|object|
3535

3636
If the `spec.target.configMapData` property is not set, the generated ConfigMap will be populated with the list of key-values retrieved from Azure App Configuration, which allows the ConfigMap to be consumed as environment variables. Update this property if you wish to consume the ConfigMap as a mounted file. This property has the following child properties.
3737

3838
|Name|Description|Required|Type|
3939
|---|---|---|---|
40-
|type|The setting that indicates how the retrieved data is constructed in the generated ConfigMap. The allowed values include `default`, `json`, `yaml` and `properties`|optional|string|
41-
|key|The key name of the retrieved data when the `type` is set to `json`, `yaml` or `properties`. Set it to the file name if the ConfigMap is set up to be consumed as a mounted file|conditional|string|
40+
|type|The setting that indicates how the retrieved data is constructed in the generated ConfigMap. The allowed values include `default`, `json`, `yaml` and `properties`.|optional|string|
41+
|key|The key name of the retrieved data when the `type` is set to `json`, `yaml` or `properties`. Set it to the file name if the ConfigMap is set up to be consumed as a mounted file.|conditional|string|
4242

4343
The `spec.auth` property isn't required if the connection string of your App Configuration store is provided by setting the `spec.connectionStringReference` property. Otherwise, one of the identities, service principal, workload identity, or managed identity, will be used for authentication. The `spec.auth` has the following child properties. Only one of them should be specified. If none of them are set, the system-assigned managed identity of the virtual machine scale set will be used.
4444

4545
|Name|Description|Required|Type|
4646
|---|---|---|---|
47-
|servicePrincipalReference|The name of the Kubernetes Secret that contains the credentials of a service principal|false|string|
48-
|workloadIdentity|The settings for using workload identity|false|object|
49-
|managedIdentityClientId|The Client ID of user-assigned managed identity of virtual machine scale set|false|string|
47+
|servicePrincipalReference|The name of the Kubernetes Secret that contains the credentials of a service principal.|false|string|
48+
|workloadIdentity|The settings for using workload identity.|false|object|
49+
|managedIdentityClientId|The Client ID of user-assigned managed identity of virtual machine scale set.|false|string|
5050

5151
The `spec.auth.workloadIdentity` property has the following child property.
5252

5353
|Name|Description|Required|Type|
5454
|---|---|---|---|
55-
|managedIdentityClientId|The Client ID of the user-assigned managed identity associated with the workload identity|true|string|
55+
|managedIdentityClientId|The Client ID of the user-assigned managed identity associated with the workload identity.|true|string|
5656

5757
The `spec.keyValues` has the following child properties. The `spec.keyValues.keyVaults` property is required if any Key Vault references are expected to be downloaded.
5858

5959
|Name|Description|Required|Type|
6060
|---|---|---|---|
61-
|selectors|The list of selectors for key-value filtering|false|object array|
62-
|trimKeyPrefixes|The list of key prefixes to be trimmed|false|string array|
63-
|keyVaults|The settings for Key Vault references|conditional|object|
64-
|refresh|The settings for refreshing the key-values in ConfigMap or Secret|false|object|
61+
|selectors|The list of selectors for key-value filtering.|false|object array|
62+
|trimKeyPrefixes|The list of key prefixes to be trimmed.|false|string array|
63+
|refresh|The settings for refreshing data from Azure App Configuration. If the property is absent, data from Azure App Configuration will not be refreshed.|false|object|
64+
|keyVaults|The settings for Key Vault references.|conditional|object|
6565

6666
If the `spec.keyValues.selectors` property isn't set, all key-values with no label will be downloaded. It contains an array of *selector* objects, which have the following child properties.
6767

6868
|Name|Description|Required|Type|
6969
|---|---|---|---|
70-
|keyFilter|The key filter for querying key-values|true|string|
71-
|labelFilter|The label filter for querying key-values|false|string|
70+
|keyFilter|The key filter for querying key-values.|true|string|
71+
|labelFilter|The label filter for querying key-values.|false|string|
7272

73-
The `spec.keyValues.keyVaults` property has the following child properties.
73+
The `spec.keyValues.refresh` property has the following child properties.
7474

7575
|Name|Description|Required|Type|
7676
|---|---|---|---|
77-
|target|The destination of resolved Key Vault references in Kubernetes|true|object|
78-
|auth|The authentication method to access Key Vaults|false|object|
77+
|monitoring|The key-values monitored for change detection, aka sentinel keys. The data from Azure App Configuration will be refreshed only if at least one of the monitored key-values is changed.|true|object|
78+
|interval|The interval at which the data will be refreshed from Azure App Configuration. It must be greater than or equal to 1 second. If the property is absent, a default value of 30 seconds will be used.|false|duration string|
7979

80-
The `spec.keyValues.keyVaults.target` property has the following child property.
80+
The `spec.keyValues.refresh.monitoring.keyValues` is an array of objects, which have the following child properties.
8181

8282
|Name|Description|Required|Type|
8383
|---|---|---|---|
84-
|secretName|The name of the Kubernetes Secret to be created|true|string|
84+
|key|The key of a key-value.|true|string|
85+
|label|The label of a key-value.|false|string|
8586

86-
If the `spec.keyValues.keyVaults.auth` property isn't set, the system-assigned managed identity is used. It has the following child properties.
87+
The `spec.keyValues.keyVaults` property has the following child properties.
8788

8889
|Name|Description|Required|Type|
8990
|---|---|---|---|
90-
|servicePrincipalReference|The name of the Kubernetes Secret that contains the credentials of a service principal used for authentication with vaults that don't have individual authentication methods specified|false|string|
91-
|workloadIdentity|The settings of the workload identity used for authentication with vaults that don't have individual authentication methods specified. It has the same child properties as `spec.auth.workloadIdentity`|false|object|
92-
|managedIdentityClientId|The client ID of a user-assigned managed identity of virtual machine scale set used for authentication with vaults that don't have individual authentication methods specified|false|string|
93-
|vaults|The authentication methods for individual vaults|false|object array|
91+
|target|The destination of the retrieved secrets in Kubernetes.|true|object|
92+
|auth|The authentication method to access Key Vaults.|false|object|
93+
|refresh|The settings for refreshing data from Key Vaults. If the property is absent, data from Key Vaults will not be refreshed unless the corresponding Key Vault references are reloaded.|false|object|
9494

95-
The authentication method of each *vault* can be specified with the following properties. One of `managedIdentityClientId`, `servicePrincipalReference` or `workloadIdentity` must be provided.
95+
The `spec.keyValues.keyVaults.target` property has the following child property.
9696

9797
|Name|Description|Required|Type|
9898
|---|---|---|---|
99-
|uri|The URI of a vault|true|string|
100-
|servicePrincipalReference|The name of the Kubernetes Secret that contains the credentials of a service principal used for authentication with a vault|false|string|
101-
|workloadIdentity|The settings of the workload identity used for authentication with a vault. It has the same child properties as `spec.auth.workloadIdentity`|false|object|
102-
|managedIdentityClientId|The client ID of a user-assigned managed identity of virtual machine scale set used for authentication with a vault|false|string|
99+
|secretName|The name of the Kubernetes Secret to be created.|true|string|
103100

104-
The `spec.keyValues.refresh` property has the following child properties.
101+
If the `spec.keyValues.keyVaults.auth` property isn't set, the system-assigned managed identity is used. It has the following child properties.
105102

106103
|Name|Description|Required|Type|
107104
|---|---|---|---|
108-
|monitoring|The key-values that are monitored by the provider, provider automatically refreshes the ConfigMap or Secret if value change in any designated key-value|true|object|
109-
|interval|The interval for refreshing, default value is 30 seconds, must be greater than 1 second|false|duration string|
105+
|servicePrincipalReference|The name of the Kubernetes Secret that contains the credentials of a service principal used for authentication with vaults that don't have individual authentication methods specified.|false|string|
106+
|workloadIdentity|The settings of the workload identity used for authentication with vaults that don't have individual authentication methods specified. It has the same child properties as `spec.auth.workloadIdentity`.|false|object|
107+
|managedIdentityClientId|The client ID of a user-assigned managed identity of virtual machine scale set used for authentication with vaults that don't have individual authentication methods specified.|false|string|
108+
|vaults|The authentication methods for individual vaults.|false|object array|
110109

111-
The `spec.keyValues.refresh.monitoring.keyValues` is an array of objects, which have the following child properties.
110+
The authentication method of each *vault* can be specified with the following properties. One of `managedIdentityClientId`, `servicePrincipalReference` or `workloadIdentity` must be provided.
111+
112+
|Name|Description|Required|Type|
113+
|---|---|---|---|
114+
|uri|The URI of a vault.|true|string|
115+
|servicePrincipalReference|The name of the Kubernetes Secret that contains the credentials of a service principal used for authentication with a vault.|false|string|
116+
|workloadIdentity|The settings of the workload identity used for authentication with a vault. It has the same child properties as `spec.auth.workloadIdentity`.|false|object|
117+
|managedIdentityClientId|The client ID of a user-assigned managed identity of virtual machine scale set used for authentication with a vault.|false|string|
118+
119+
The `spec.keyValues.keyVaults.refresh` property has the following child property.
112120

113121
|Name|Description|Required|Type|
114122
|---|---|---|---|
115-
|key|The key of a key-value|true|string|
116-
|label|The label of a key-value|false|string|
123+
|interval|The interval at which the data will be refreshed from Key Vault. It must be greater than or equal to 1 minute. The Key Vault refresh is independent of the App Configuration refresh configured via `spec.keyValues.refresh`.|true|duration string|
117124

118125
## Examples
119126

@@ -286,9 +293,36 @@ spec:
286293
trimKeyPrefixes: [prefix1, prefix2]
287294
```
288295

296+
### Configuration refresh
297+
298+
When you make changes to your data in Azure App Configuration, you might want those changes to be refreshed automatically in your Kubernetes cluster. It's common to update multiple key-values, but you don't want the cluster to pick up a change midway through the update. To maintain configuration consistency, you can use a key-value to signal the completion of your update. This key-value is known as the sentinel key. The Kubernetes provider can monitor this key-value, and the ConfigMap and Secret will only be regenerated with updated data once a change is detected in the sentinel key.
299+
300+
In the following sample, a key-value named `app1_sentinel` is polled every minute, and the configuration is refreshed whenever changes are detected in the sentinel key.
301+
302+
``` yaml
303+
apiVersion: azconfig.io/v1beta1
304+
kind: AzureAppConfigurationProvider
305+
metadata:
306+
name: appconfigurationprovider-sample
307+
spec:
308+
endpoint: <your-app-configuration-store-endpoint>
309+
target:
310+
configMapName: configmap-created-by-appconfig-provider
311+
keyValues:
312+
selectors:
313+
- keyFilter: app1*
314+
labelFilter: common
315+
refresh:
316+
interval: 1m
317+
monitoring:
318+
keyValues:
319+
- key: app1_sentinel
320+
label: common
321+
```
322+
289323
### Key Vault references
290324

291-
The following sample instructs using a service principal to authenticate with a specific vault and a user-assigned managed identity for all other vaults.
325+
In the following sample, one Key Vault is authenticated with a service principal, while all other Key Vaults are authenticated with a user-assigned managed identity.
292326

293327
``` yaml
294328
apiVersion: azconfig.io/v1beta1
@@ -312,11 +346,11 @@ spec:
312346
servicePrincipalReference: <name-of-secret-containing-service-principal-credentials>
313347
```
314348

315-
### Dynamically refresh ConfigMap and Secret
349+
### Refresh of secrets from Key Vault
316350

317-
Setting the `spec.keyValues.refresh` property enables dynamic configuration data refresh in ConfigMap and Secret by monitoring designated key-values. The provider periodically polls the key-values, if there is any value change, provider triggers ConfigMap and Secret refresh in accordance with the present data in Azure App Configuration.
351+
Refreshing secrets from Key Vaults usually requires reloading the corresponding Key Vault references from Azure App Configuration. However, with the `spec.keyValues.keyVaults.refresh` property, you can refresh the secrets from Key Vault independently. This is especially useful for ensuring that your workload automatically picks up any updated secrets from Key Vault during secret rotation. Note that to load the latest version of a secret, the Key Vault reference must not be a versioned secret.
318352

319-
The following sample instructs monitoring two key-values with 1 minute polling interval.
353+
The following sample refreshes all non-versioned secrets from Key Vault every hour.
320354

321355
``` yaml
322356
apiVersion: azconfig.io/v1beta1
@@ -331,19 +365,16 @@ spec:
331365
selectors:
332366
- keyFilter: app1*
333367
labelFilter: common
334-
- keyFilter: app1*
335-
labelFilter: development
336-
refresh:
337-
interval: 1m
338-
monitoring:
339-
keyValues:
340-
- key: sentinelKey
341-
label: common
342-
- key: sentinelKey
343-
label: development
368+
keyVaults:
369+
target:
370+
secretName: secret-created-by-appconfig-provider
371+
auth:
372+
managedIdentityClientId: <your-user-assigned-managed-identity-client-id>
373+
refresh:
374+
interval: 1h
344375
```
345376

346-
### Consume ConfigMap
377+
### ConfigMap Consumption
347378

348379
Applications running in Kubernetes typically consume the ConfigMap either as environment variables or as configuration files. If the `configMapData.type` property is absent or is set to default, the ConfigMap is populated with the itemized list of data retrieved from Azure App Configuration, which can be easily consumed as environment variables. If the `configMapData.type` property is set to json, yaml or properties, data retrieved from Azure App Configuration is grouped into one item with key name specified by the `configMapData.key` property in the generated ConfigMap, which can be consumed as a mounted file.
349380

0 commit comments

Comments
 (0)