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.

Customer-managed keys are used with the following services that Azure Machine Learning relies on:

Service What it’s used for
Azure Cosmos DB Stores metadata for Azure Machine Learning
Azure Cognitive Search Stores workspace metadata for Azure Machine Learning
Azure Storage Account Stores workspace metadata for Azure Machine Learning
Azure Container Instance Hosting trained models as inference endpoints
Azure Kubernetes Service Hosting trained models as inference endpoints


  • Azure Cosmos DB, Cognitive Search, and Storage Account are secured using the same key. You can use a different key for Azure Kubernetes Service and Container Instance.
  • To use a customer-managed key with Azure Cosmos DB, Cognitive Search, and Storage Account, the key is provided when you create your workspace. The key(s) used with Azure Container Instance and Kubernetes Service are provided when configuring those resources.


  • 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.


  • 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.
  • The key vault that contains your customer-managed key must be in the same Azure subscription as the Azure Machine Learning workspace.
  • OS disk of machine learning compute can't be encrypted with customer-managed key, but can be encrypted with Microsoft-managed key if the workspace is created with hbi_workspace parameter set to TRUE. For more details, see Data encryption.
  • Workspace with customer-managed key doesn't currently support v2 batch endpoint.


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.


The key vault must be in the same Azure subscription that will contain your Azure Machine Learning workspace.

Create a key


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:


The key vault that contains your customer-managed key must be in the same Azure subscription as the workspace.

  • 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{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
Create a workspace with a template
REST API Create, run, and delete Azure Machine Learning 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.


  • 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.


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


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 Azure Cosmos DB, see Configure customer-managed keys for your Azure Cosmos DB account.

Azure Container Instance


Deploying to Azure Container Instances is not available in SDK or CLI v2. Only through SDK & CLI v1.

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:

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.


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

Next steps