Azure Fluid Relay 암호화를 위한 고객 관리형 키

2025-07-16

자체 암호화 키를 사용하여 Azure Fluid Relay 리소스의 데이터를 보호할 수 있습니다. CMK(고객 관리형 키)를 지정하는 경우 해당 키는 데이터를 암호화하는 키에 대한 액세스를 보호하고 제어하는 데 사용됩니다. CMK를 사용하면 훨씬 더 유연하게 액세스 제어를 관리할 수 있습니다.

다음 Azure 키 저장소 중 하나를 사용하여 CMK를 저장해야 합니다.

CMK를 사용하도록 설정하려면 새 Azure Fluid Relay 리소스를 만들어야 합니다. 기존 Fluid Relay 리소스의 CMK 사용/사용 안 함을 변경할 수 없습니다.

또한 Fluid Relay의 CMK는 관리 ID를 사용하며 CMK를 사용하도록 설정할 때 관리 ID를 Fluid Relay 리소스에 할당해야 합니다. Fluid Relay 리소스 CMK에는 사용자 할당 ID만 허용됩니다. For more information about managed identities, see here.

CMK를 사용하여 Fluid Relay 리소스를 구성하는 것은 아직 Azure Portal을 통해 수행할 수 없습니다.

CMK를 사용하여 Fluid Relay 리소스를 구성하는 경우 Azure Fluid Relay 서비스는 Fluid 세션 아티팩트가 저장된 Azure Storage 계정 범위에서 적절한 CMK 암호화 설정을 구성합니다. For more information about CMK in Azure Storage, see here.

Fluid Relay 리소스가 CMK를 사용하고 있는지 확인하려면 GET을 전송하여 리소스의 속성을 확인하고 encryption.customerManagedKeyEncryption의 비어 있지 않은 유효한 속성이 있는지 확인할 수 있습니다.

Prerequisites

Azure Fluid Relay 리소스에서 CMK를 구성하기 전에 다음 필수 구성 요소를 충족해야 합니다.

키는 Azure Key Vault에 저장해야 합니다.
EC 키는 WRAP 및 UNWRAP을 지원하지 않으므로 키는 EC 키가 아닌 RSA 키여야 합니다.
1단계에서 키 자격 증명 모음에 필요한 권한(GET, WRAP 및 UNWRAP)을 사용하여 사용자가 할당한 관리 ID를 만들어야 합니다. More information here. AKV의 키 권한에 GET, WRAP 및 UNWRAP를 부여합니다.
Azure Key Vault, 사용자 할당 ID 및 Fluid Relay 리소스는 동일한 지역 및 동일한 Microsoft Entra 테넌트에 있어야 합니다.
Key Vault 및 키는 Fluid Relay 리소스의 전체 수명 동안 활성 상태로 유지되어야 합니다.
- Do NOT delete or disable the key vault or the key until all associated Fluid Relay services are deleted. Otherwise, your Fluid Relay resource enters an unusable state. 이 경우 먼저 키 또는 키 자격 증명 모음을 복구해야 합니다.
특정 키 버전을 사용하여 키 URL을 제공하는 경우 해당 버전만 CMK 용도로 사용됩니다. 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. 유효한 버전을 사용하도록 리소스를 업데이트하지 않고 지정된 키 버전을 삭제하거나 사용하지 않도록 설정하면 Fluid Relay 서비스가 실패합니다.
Fluid Relay 서비스가 키 자격 증명 모음에서 키의 최신 키 버전을 자동으로 사용하도록 허용하려면 암호화 키 URL에서 키 버전을 생략할 수 있습니다. 이 설정은 Fluid Relay 서비스의 스토리지 종속성을 통해 매일 키 자격 증명 모음에서 고객 관리형 키의 새 버전을 확인하고 키를 최신 버전으로 자동으로 업데이트합니다. 그러나 Key Vault에서 키 버전을 관리하고 회전할 책임이 있습니다.
- 리소스 제한으로 인해 이 자동 업데이트 설정으로 전환하지 못할 수 있습니다. If that happens, specify a key version explicitly and perform a manual update on your Fluid Relay resource for new key versions.

CMK를 사용하여 Fluid Relay 리소스 만들기

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>"

요청 페이로드 형식:

{
    "___location": "<the region you selected for Fluid Relay resource>",
    "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
            “<User assigned identity resource ID>": {}
        }
    },
    "properties": {
       "encryption": {
            "customerManagedKeyEncryption": {
                "keyEncryptionKeyIdentity": {
                    "identityType": "UserAssigned",
                    "userAssignedIdentityResourceId":  "<User assigned identity resource ID>"
                },
                "keyEncryptionKeyUrl": "<key identifier>"
            }
        }
    }
}

예 userAssignedIdentities 및 userAssignedIdentityResourceId: /subscriptions/ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/testGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/testUserAssignedIdentity

예 keyEncryptionKeyUrl: https://test-key-vault.vault.azure.net/keys/testKey/testKeyVersionGuid

Notes:

Identity.type은 UserAssigned여야 합니다. Fluid Relay 리소스에 할당된 관리 ID의 ID 유형입니다.
Properties.encryption.customerManagedKeyEncryption.keyEncryptionKeyIdentity.identityType은 UserAssigned여야 합니다. CMK에 사용해야 하는 관리 ID의 ID 유형입니다.
Identity.userAssignedIdentities에서 둘 이상을 지정할 수 있지만 지정된 Fluid Relay 리소스에 할당된 하나의 사용자 ID만 CMK가 암호화를 위해 키 자격 증명 모음에 액세스하는 데 사용됩니다.
Properties.encryption.customerManagedKeyEncryption.keyEncryptionKeyIdentity.userAssignedIdentityResourceId는 CMK에 사용해야 하는 사용자 할당 ID의 리소스 ID입니다. Identity.userAssignedIdentities의 ID 중 하나여야 합니다(CMK에 사용하기 전에 ID를 Fluid Relay 리소스에 할당해야 함). 또한 키에 필요한 권한이 있어야 합니다(keyEncryptionKeyUrl에서 제공).
Properties.encryption.customerManagedKeyEncryption.keyEncryptionKeyUrl은 CMK에 사용되는 키 식별자입니다.

먼저 Azure Fluid Relay 모듈을 설치해야 합니다.

Install-Module Az.FluidRelay

그리고 모든 필수 구성 요소 단계를 완료해야 합니다.

CMK를 사용하도록 설정된 Fluid Relay 서비스를 만드는 예제:

New-AzFluidRelayServer -Name <Fluid Relay Service name> -ResourceGroup <resource group name> -SubscriptionId "<subscription id>" -Location "<region>" -KeyEncryptionKeyIdentityType UserAssigned -KeyEncryptionKeyIdentityUserAssignedIdentityResourceId "<user assigned resource id>" -CustomerManagedKeyEncryptionKeyUrl "<key URL>" -UserAssignedIdentity "<user assigned resource id>"

For more information about the command, see New-AzFluidRelayServer

Notes:

The KeyEncryptionKeyIdentityTypemust beUserAssigned since SystemAssigned identity is not supported for CMK. CMK(Customer-Managed Key) 암호화에 사용할 ID 형식을 나타냅니다.
While multiple identities can be specified in the UserAssignedIdentity argument, only the identity defined in KeyEncryptionKeyIdentityUserAssignedIdentityResourceId is used to access the Key Vault for CMK encryption.
The KeyEncryptionKeyIdentityUserAssignedIdentityResourceId field should be set to the resource ID of the user-assigned identity intended for CMK access.
- 이 ID는 이미 필드에 나열 UserAssignedIdentity 되어 있어야 합니다.
- 또한 에 지정된 CustomerManagedKeyEncryptionKeyUrl키에 필요한 권한이 필요합니다.
CustomerManagedKeyEncryptionKeyUrl is the key identifier used for CMK.

To create Fluid Relay with CMK enabled using Azure CLI, you need to install fluid-relay extension first. See instructions.

And make sure you complete all the prerequisite steps.

CMK를 사용하도록 설정된 Fluid Relay 서비스를 만드는 예제:

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 "<key URL>" --___location <___location> --sku <standard or basic>

명령에 대한 자세한 내용은 az fluid-relay server create를 참조하세요.

Notes:

These arguments must be provided in stringified JSON format.
- identity, key-identity
The type field under identitymust beUserAssigned. Fluid Relay 리소스에 할당된 관리 ID의 ID 유형을 지정합니다.
identity-type 아래 key-identity 필드도 있어야UserAssigned 합니다. CMK(Customer-Managed Key) 암호화에 사용할 ID 형식을 나타냅니다.
While multiple identities can be specified in the identity argument, only the identity defined in key-identity is used to access the Key Vault for CMK encryption.
The user-assigned-identities field under key-identity should be set to the resource ID of the user-assigned identity intended for CMK access.
- 이 ID는 이미 필드에 나열 identity 되어 있어야 합니다.
- 또한 에 지정된 key-url키에 필요한 권한이 필요합니다.
key-url is the key identifier used for CMK.

기존 Fluid Relay 리소스의 CMK 설정 업데이트

기존 Fluid Relay 리소스에서 다음 CMK 설정을 업데이트할 수 있습니다.

키 암호화 키에 액세스하는 데 사용되는 ID를 변경합니다.
키 암호화 키 식별자(키 URL)를 변경합니다.
키 암호화 키의 키 버전을 변경합니다.

CMK를 사용하도록 설정한 후에는 기존 Fluid Relay 리소스에서 CMK를 사용하지 않도록 설정할 수 없습니다.

키 암호화 키(식별자 또는 버전별)를 업데이트하기 전에 이전 키 버전이 계속 사용하도록 설정되어 있고 키 자격 증명 모음에서 만료되지 않았는지 확인합니다. 그렇지 않으면 업데이트 작업이 실패합니다.

업데이트 명령을 사용하는 경우 변경된 매개 변수만 지정할 수 있습니다. 변경되지 않은 인수는 생략할 수 있습니다.

All updates must satisfy the prerequisites described in this page.

Request URL:

PATCH https://management.azure.com/subscriptions/<subscription id>/resourceGroups/<resource group name>/providers/Microsoft.FluidRelay/fluidRelayServers/<fluid relay server name>?api-version=2022-06-01 @"path to request payload"

키 암호화 키 URL을 업데이트하기 위한 요청 페이로드 예제:

{
    "properties": {
       "encryption": {
            "customerManagedKeyEncryption": {
                "keyEncryptionKeyUrl": "https://test_key_vault.vault.azure.net/keys/testKey /xxxxxxxxxxxxxxxx"
            }
        }
    }
}

먼저 Azure Fluid Relay 모듈을 설치해야 합니다.

Install-Module Az.FluidRelay

업데이트하는 동안 변경해야 하는 매개 변수만 제공해야 합니다.

암호화 키 URL 업데이트

Update-AzFluidRelayServer -Name <Fluid Relay Service name> -ResourceGroup <resource group name> -SubscriptionId "<subscription id>" -CustomerManagedKeyEncryptionKeyUrl "<new key URL>"

CMK에 대한 할당된 ID 업데이트

Update-AzFluidRelayServer -Name <Fluid Relay Service name> -ResourceGroup <resource group name> -SubscriptionId "<subscription id>" -KeyEncryptionKeyIdentityUserAssignedIdentityResourceId "<new user assigned resource id>"

For more information about the command, see Update-AzFluidRelayServer

암호화 키 URL 업데이트

az fluid-relay server update --server-name <Fluid Relay Service name> --resource-group <resource group> --key-url <new key URL>

리소스를 만들 때와 동일한 형식을 업데이트 identity 하고 key-identity 따릅니다. 그러나 업데이트 중에는 변경해야 하는 매개 변수만 제공해야 합니다.

CMK에 대한 할당된 ID 업데이트

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>"}'

명령에 대한 자세한 내용은 az fluid-relay 서버 업데이트를 참조하세요.

Troubleshooting

오류: CMK를 구성할 때 예기치 않은 오류가 발생했습니다.

구성이 필수 구성 요소 섹션에 나열된 모든 요구 사항을 충족하는지 확인합니다.
Azure Key Vault에서 방화벽 규칙을 사용하도록 설정했는지 확인합니다. 그렇다면 "신뢰할 수 있는 Microsoft 서비스가 이 방화벽을 무시하도록 허용" 옵션을 켭니다. Key Vault 방화벽 사용 신뢰할 수 있는 서비스만 참조
기존 Fluid Relay 리소스의 경우 키 또는 특정 키 버전(CMK 설정에 지정된 경우)이 계속 사용하도록 설정되어 있고 Key Vault에서 만료되지 않았는지 확인합니다.