Skip to content

Files

Latest commit

alexbuckgitalexbuckgit
[BULK UPDATE] DocuTune - Apply event-tier1-build-2022 ms.custom tag t…
May 23, 2022
55762f7 · May 23, 2022

History

History
158 lines (111 loc) · 10.9 KB

how-to-setup-customer-managed-keys.md

File metadata and controls

158 lines (111 loc) · 10.9 KB
title titleSuffix description services ms.service ms.subservice ms.custom ms.topic ms.author author ms.reviewer ms.date
Use customer-managed keys
Azure Machine Learning
Learn how to improve data security with Azure Machine Learning by using customer-managed keys.
machine-learning
machine-learning
enterprise-readiness
event-tier1-build-2022
conceptual
jhirono
jhirono
larryfr
03/17/2022

Use customer-managed keys with Azure Machine Learning

In the customer-managed keys concepts article, you learned about the encryption capabilities that Azure Machine Learning provides. Now learn how to use customer-managed keys with Azure Machine Learning.

[!INCLUDE machine-learning-customer-managed-keys.md]

Prerequisites

  • An Azure subscription.

  • The following Azure resource providers must be registered:

    Resource provider Why it's needed
    Microsoft.MachineLearningServices Creating the Azure Machine Learning workspace.
    Microsoft.Storage Azure Storage Account is used as the default storage for the workspace.
    Microsoft.KeyVault Azure Key Vault is used by the workspace to store secrets.
    Microsoft.DocumentDB/databaseAccounts Azure Cosmos DB instance that logs metadata for the workspace.
    Microsoft.Search/searchServices Azure Search provides indexing capabilities for the workspace.

    For information on registering resource providers, see Resolve errors for resource provider registration.

Limitations

  • The customer-managed key for resources the workspace depends on can’t be updated after workspace creation.
  • Resources managed by Microsoft in your subscription can’t transfer ownership to you.
  • You can't delete Microsoft-managed resources used for customer-managed keys without also deleting your workspace.

Important

When using a customer-managed key, the costs for your subscription will be higher because of the additional resources in your subscription. To estimate the cost, use the Azure pricing calculator.

Create Azure Key Vault

To create the key vault, see Create a key vault. When creating Azure Key Vault, you must enable soft delete and purge protection.

Create a key

Tip

If you have problems creating the key, it may be caused by Azure role-based access controls that have been applied in your subscription. Make sure that the security principal (user, managed identity, service principal, etc.) you are using to create the key has been assigned the Contributor role for the key vault instance. You must also configure an Access policy in key vault that grants the security principal Create, Get, Delete, and Purge authorization.

If you plan to use a user-assigned managed identity for your workspace, the managed identity must also be assigned these roles and access policies.

For more information, see the following articles:

  1. From the Azure portal, select the key vault instance. Then select Keys from the left.

  2. Select + Generate/import from the top of the page. Use the following values to create a key:

    • Set Options to Generate.
    • Enter a Name for the key. The name should be something that identifies what the planned use is. For example, my-cosmos-key.
    • Set Key type to RSA.
    • We recommend selecting at least 3072 for the RSA key size.
    • Leave Enabled set to yes.

    Optionally you can set an activation date, expiration date, and tags.

  3. Select Create to create the key.

Allow Azure Cosmos DB to access the key

  1. To configure the key vault, select it in the Azure portal and then select Access polices from the left menu.
  2. To create permissions for Azure Cosmos DB, select + Create at the top of the page. Under Key permissions, select Get, Unwrap Key, and Wrap key permissions.
  3. Under Principal, search for Azure Cosmos DB and then select it. The principal ID for this entry is a232010e-820c-4083-83bb-3ace5fc29d0b for all regions other than Azure Government. For Azure Government, the principal ID is 57506a73-e302-42a9-b869-6f12d9ec29e9.
  4. Select Review + Create, and then select Create.

Create a workspace that uses a customer-managed key

Create an Azure Machine Learning workspace. When creating the workspace, you must select the Azure Key Vault and the key. Depending on how you create the workspace, you specify these resources in different ways:

  • Azure portal: Select the key vault and key from a dropdown input box when configuring the workspace.

  • SDK, REST API, and Azure Resource Manager templates: Provide the Azure Resource Manager ID of the key vault and the URL for the key. To get these values, use the Azure CLI and the following commands:

    # Replace `mykv` with your key vault name.
# Replace `mykey` with the name of your key.

# Get the Azure Resource Manager ID of the key vault
az keyvault show --name mykv --query id
# Get the URL for the key
az keyvault key show --vault-name mykv -n mykey --query key.kid

    The key vault ID value will be similar to /subscriptions/{GUID}/resourceGroups/{resource-group-name}/providers/Microsoft.KeyVault/vaults/mykv. The URL for the key will be similar to https://mykv.vault.azure.net/keys/mykey/{GUID}.

For examples of creating the workspace with a customer-managed key, see the following articles:

Creation method Article
CLI Create a workspace with Azure CLI
Azure portal/
Python SDK		 Create and manage a workspace
Azure Resource Manager
template		 Create a workspace with a template
REST API Create, run, and delete Azure ML resources with REST

Once the workspace has been created, you'll notice that Azure resource group is created in your subscription. This group is in addition to the resource group for your workspace. This resource group will contain the Microsoft-managed resources that your key is used with. The resource group will be named using the formula of <Azure Machine Learning workspace resource group name><GUID>. It will contain an Azure Cosmos DB instance, Azure Storage Account, and Azure Cognitive Search.

Tip

  • The Request Units for the Azure Cosmos DB instance automatically scale as needed.
  • If your Azure Machine Learning workspace uses a private endpoint, this resource group will also contain a Microsoft-managed Azure Virtual Network. This VNet is used to secure communications between the managed services and the workspace. You cannot provide your own VNet for use with the Microsoft-managed resources. You also cannot modify the virtual network. For example, you cannot change the IP address range that it uses.

Important

If your subscription does not have enough quota for these services, a failure will occur.

Warning

Don't delete the resource group that contains this Azure Cosmos DB instance, or any of the resources automatically created in this group. If you need to delete the resource group or Microsoft-managed services in it, you must delete the Azure Machine Learning workspace that uses it. The resource group resources are deleted when the associated workspace is deleted.

For more information on customer-managed keys with Cosmos DB, see Configure customer-managed keys for your Azure Cosmos DB account.

Azure Container Instance

When deploying a trained model to an Azure Container instance (ACI), you can encrypt the deployed resource using a customer-managed key. For information on generating a key, see Encrypt data with a customer-managed key.

To use the key when deploying a model to Azure Container Instance, create a new deployment configuration using AciWebservice.deploy_configuration(). Provide the key information using the following parameters:

  • cmk_vault_base_url: The URL of the key vault that contains the key.
  • cmk_key_name: The name of the key.
  • cmk_key_version: The version of the key.

For more information on creating and using a deployment configuration, see the following articles:

For more information on using a customer-managed key with ACI, see Encrypt data with a customer-managed key.

Azure Kubernetes Service

You may encrypt a deployed Azure Kubernetes Service resource using customer-managed keys at any time. For more information, see Bring your own keys with Azure Kubernetes Service.

This process allows you to encrypt both the Data and the OS Disk of the deployed virtual machines in the Kubernetes cluster.

Important

This process only works with AKS K8s version 1.17 or higher.

Next steps