Manage Azure Machine Learning registries
Azure Machine Learning entities can be grouped into two broad categories:
- Assets such as models, environments, components, and datasets are durable entities that are workspace agnostic. For example, a model can be registered with any workspace and deployed to any endpoint.
- Resources such as compute, job, and endpoints are transient entities that are workspace specific. For example, an online endpoint has a scoring URI that is unique to a specific instance in a specific workspace. Similarly, a job runs for a known duration and generates logs and metrics each time it's run.
Assets lend themselves to being stored in a central repository and used in different workspaces, possibly in different regions. Resources are workspace specific.
Azure Machine Learning registries enable you to create and use those assets in different workspaces. Registries support multi-region replication for low latency access to assets, so you can use assets in workspaces located in different Azure regions. Creating a registry provisions Azure resources required to facilitate replication. First, Azure blob storage accounts in each supported region. Second, a single Azure Container Registry with replication enabled to each supported region.
Before following the steps in this article, make sure you have the following prerequisites:
The CLI examples in this article assume that you are using the Bash (or compatible) shell. For example, from a Linux system or Windows Subsystem for Linux.
An Azure Machine Learning workspace. If you don't have one, use the steps in the Install, set up, and use the CLI (v2) to create one.
If you are using an older version of the
ml extension for CLI, you may need to update it to the latest version before working with this feature. To update the latest version, use the following command:
az extension update -n ml
For more information, see Install, set up, and use the CLI (v2).
Prepare to create registry
You need to decide the following information carefully before proceeding to create a registry:
Choose a name
Consider the following factors before picking a name.
- Registries are meant to facilitate sharing of ML assets across teams within your organization across all workspaces. Choose a name that is reflective of the sharing scope. The name should help identify your group, division or organization.
- Registry name is unique with your organization (Microsoft Entra tenant). It's recommended to prefix your team or organization name and avoid generic names.
- Registry names can't be changed once created because they're used in IDs of models, environments and components that are referenced in code.
- Length can be 2-32 characters.
- Alphanumerics, underscore, hyphen are allowed. No other special characters. No spaces - registry names are part of model, environment, and component IDs that can be referenced in code.
- Name can contain underscore or hyphen but can't start with an underscore or hyphen. Needs to start with an alphanumeric.
Choose Azure regions
Registries enable sharing of assets across workspaces. To do so, a registry replicates content across multiple Azure regions. You need to define the list of regions that a registry supports when creating the registry. Create a list of all regions in which you have workspaces today and plan to add in near future. This list is a good set of regions to start with. When creating a registry, you define a primary region and a set of additional regions. The primary region can't be changed after registry creation, but the additional regions can be updated at a later point.
Make sure you're the "Owner" or "Contributor" of the subscription or resource group in which you plan to create the registry. If you don't have one of these built-in roles, review the section on permissions toward the end of this article.
Create a registry
Create the YAML definition and name it
The primary location is listed twice in the YAML file. In the following example,
eastus is listed first as the primary location (
location item) and also in the
name: DemoRegistry1 tags: description: Basic registry with one primary region and to additional regions foo: bar location: eastus replication_locations: - location: eastus - location: eastus2 - location: westus
For more information on the structure of the YAML file, see the registry YAML reference article.
You typically see display names of Azure regions such as 'East US' in the Azure Portal but the registry creation YAML needs names of regions without spaces and lower case letters. Use
az account list-locations -o table to find the mapping of region display names to the name of the region that can be specified in YAML.
Run the registry create command.
az ml registry create --file registry.yml
Specify storage account type and SKU (optional)
Specifying the Azure Storage Account type and SKU is only available from the Azure CLI.
Azure storage offers several types of storage accounts with different features and pricing. For more information, see the Types of storage accounts article. Once you identify the optimal storage account SKU that best suites your needs, find the value for the appropriate SKU type. In the YAML file, use your selected SKU type as the value of the
storage_account_type field. This field is under each
location in the
Next, decide if you want to use an Azure Blob storage account or Azure Data Lake Storage Gen2. To create Azure Data Lake Storage Gen2, set
true. To create Azure Blob Storage, set
storage_account_hns field is under each
location in the
hns portion of
storage_account_hns refers to the hierarchical namespace capability of Azure Data Lake Storage Gen2 accounts.
The following example YAML file demonstrates this advanced storage configuration:
name: DemoRegistry2 tags: description: Registry with additional configuration for storage accounts foo: bar location: eastus replication_locations: - location: eastus storage_config: storage_account_hns: False storage_account_type: Standard_LRS - location: eastus2 storage_config: storage_account_hns: False storage_account_type: Standard_LRS - location: westus storage_config: storage_account_hns: False storage_account_type: Standard_LRS
Add users to the registry
Decide if you want to allow users to only use assets (models, environments and components) from the registry or both use and create assets in the registry. Review steps to assign a role if you aren't familiar how to manage permissions using Azure role-based access control.
Allow users to use assets from the registry
To let a user only read assets, you can grant the user the built-in Reader role. If you don't want to use the built-in role, create a custom role with the following permissions
|Microsoft.MachineLearningServices/registries/read||Allows the user to list registries and get registry metadata|
|Microsoft.MachineLearningServices/registries/assets/read||Allows the user to browse assets and use the assets in a workspace|
Allow users to create and use assets from the registry
To let the user both read and create or delete assets, grant the following write permission in addition to the above read permissions.
|Microsoft.MachineLearningServices/registries/assets/write||Create assets in registries|
|Microsoft.MachineLearningServices/registries/assets/delete||Delete assets in registries|
The built-in Contributor and Owner roles allow users to create, update and delete registries. You must create a custom role if you want the user to create and use assets from the registry, but not create or update registries. Review custom roles to learn how to create custom roles from permissions.
Allow users to create and manage registries
To let users create, update and delete registries, grant them the built-in Contributor or Owner role. If you don't want to use built in roles, create a custom role with the following permissions, in addition to all the above permissions to read, create and delete assets in registry.
|Microsoft.MachineLearningServices/registries/write||Allows the user to create or update registries|
|Microsoft.MachineLearningServices/registries/delete||Allows the user to delete registries|