Skip to content

Commit 08ace54

Browse files
YunhoYunho
authored andcommitted
update CMK doc to include azure cli command example
1 parent aefdc30 commit 08ace54

File tree

1 file changed

+56
-2
lines changed

1 file changed

+56
-2
lines changed

articles/azure-fluid-relay/concepts/customer-managed-keys.md

Lines changed: 56 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,9 +31,13 @@ Before configuring CMK on your Azure Fluid Relay resource, the following prerequ
3131
- Keys must be RSA key and not EC key since EC key doesn’t support WRAP and UNWRAP.
3232
- A user assigned managed identity must be created with necessary permission (GET, WRAP and UNWRAP) to the key vault in step 1. More information [here](../../active-directory/managed-identities-azure-resources/tutorial-windows-vm-access-nonaad.md). Please grant GET, WRAP and UNWRAP under Key Permissions in AKV.
3333
- Azure Key Vault, user assigned identity, and the Fluid Relay resource must be in the same region and in the same Microsoft Entra tenant.
34+
- If you provide the key URL with a specific key version, **only that version** will be used for CMK purposes.
35+
If you later add a new key version, you must **manually** update the key URL in the CMK settings of the Fluid Relay resource to make the new version effective.
36+
The Fluid Relay service will fail if the specified key version is deleted or disabled without updating the resource to use a valid version.
3437

3538
## Create a Fluid Relay resource with CMK
3639

40+
### [REST API](#tab/rest)
3741
```
3842
PUT https://management.azure.com/subscriptions/<subscription ID>/resourceGroups/<resource group name> /providers/Microsoft.FluidRelay/fluidRelayServers/< Fluid Relay resource name>?api-version=2022-06-01 @"<path to request payload>"
3943
```
@@ -73,7 +77,32 @@ Notes:
7377
- Properties.encryption.customerManagedKeyEncryption.keyEncryptionKeyIdentity.identityType must be UserAssigned. It is the identity type of the managed identity that should be used for CMK.
7478
- Although you can specify more than one in Identity.userAssignedIdentities, only one user identity assigned to Fluid Relay resource specified will be used for CMK access the key vault for encryption.
7579
- Properties.encryption.customerManagedKeyEncryption.keyEncryptionKeyIdentity.userAssignedIdentityResourceId is the resource ID of the user assigned identity that should be used for CMK. Notice that it should be one of the identities in Identity.userAssignedIdentities (You must assign the identity to Fluid Relay resource before it can use it for CMK). Also, it should have necessary permissions on the key (provided by keyEncryptionKeyUrl).
76-
- Properties.encryption.customerManagedKeyEncryption.keyEncryptionKeyUrl is the key identifier used for CMK.
80+
- Properties.encryption.customerManagedKeyEncryption.keyEncryptionKeyUrl is the key identifier used for CMK.
81+
82+
### [Azure CLI](#tab/azure-cli)
83+
To create Fluid Relay with CMK enabled using Azure CLI, you need to install [fluid-relay](/cli/azure/fluid-relay) extension first. See [instructions](/cli/azure/azure-cli-extensions-overview).
84+
85+
And make sure you complete all the prerequsite steps.
86+
87+
```azurecli
88+
az fluid-relay server create --server-name <Fluid Relay Service name> --resource-group <resource group name> --identity '{"type":"UserAssigned","user-assigned-identities":{"<user assigned resource id>":{}}}' --key-identity '{"identity-type":"UserAssigned","user-assigned-identities":"<user assigned resource id>"}' --key-url "https://akv-cuseuap-cmktest-02.vault.azure.net/keys/key-rsa-4096/81b15c848e874aabb6f13839b43b16fc" --location <location> --sku <standard or basic>
89+
```
90+
91+
For more information about the command, see [az fluid-relay server create](/cli/azure/fluid-relay/server?view=azure-cli-latest#az-fluid-relay-server-create)
92+
93+
**Notes:**
94+
95+
- Some arguments must be provided in **stringified JSON** format.
96+
- The `type` field under `identity` **must be** `UserAssigned`. This specifies the identity type of the managed identity assigned to the Fluid Relay resource.
97+
- The `identity-type` field under `key-identity` **must also be** `UserAssigned`. This indicates the identity type to be used for Customer-Managed Key (CMK) encryption.
98+
- While multiple identities can be specified in the `identity` argument, **only** the identity defined in `key-identity` will be used to access the Key Vault for CMK encryption.
99+
- The `user-assigned-identities` field under `key-identity` should be set to the **resource ID** of the user-assigned identity intended for CMK access.
100+
- This identity must already be listed in the `identity` field.
101+
- It must also be assigned to the Fluid Relay resource **before** it can be used for CMK.
102+
- Additionally, it needs the necessary permissions on the key specified in `key-url`.
103+
- `key-url` is the **key identifier** used for CMK.
104+
105+
---
77106

78107
## Update CMK settings of an existing Fluid Relay resource
79108

@@ -82,8 +111,15 @@ You can update the following CMK settings on existing Fluid Relay resource:
82111
- Change the key encryption key identifier (key URL).
83112
- Change the key version of the key encryption key.
84113

85-
Note that you cannot disable CMK on existing Fluid Relay resource once it is enabled.
114+
Note that you cannot disable CMK on existing Fluid Relay resource once it is enabled.
115+
116+
Before updating the key encryption key (by identifier or version), ensure that the previous key version is still enabled and has not expired in your key vault. Otherwise, the update operation will fail.
117+
118+
When using the update command, you may specify only the parameters that have changed—unchanged arguments can be omitted.
86119

120+
All updates must satisfy the prerequisites described above.
121+
122+
### [REST API](#tab/rest)
87123
Request URL:
88124

89125
```
@@ -104,6 +140,24 @@ Request payload example for updating key encryption key URL:
104140
}
105141
```
106142

143+
### [Azure CLI](#tab/azure-cli)
144+
145+
Update encryption key URL
146+
```azurecli
147+
az fluid-relay server update --server-name <Fluid Relay Service name> --resource-group <resource group> --key-url <new key URL>
148+
```
149+
150+
Updating `identity` and `key-identity` follows the same format as when creating the resource. However, during an update, you only need to provide the parts that have changed.
151+
152+
Update assigned identity for CMK
153+
```azurecli
154+
az fluid-relay server update --server-name <Fluid Relay Service name> --resource-group <resource group> --key-identity '{"user-assigned-identities":"<new user assigned resource id>"}'
155+
```
156+
157+
For more information about the command, see [az fluid-relay server update](/cli/azure/fluid-relay/server?view=azure-cli-latest#az-fluid-relay-server-update)
158+
159+
---
160+
107161
## See also
108162

109163
- [Overview of Azure Fluid Relay architecture](architecture.md)

0 commit comments

Comments
 (0)