Get started with Artifact Registry

Beta

This feature is in Beta. To use it, a workspace admin must turn on Databricks Artifact Registry from the Previews page. See Manage Databricks previews. Databricks will announce pricing for Artifact Registry when it becomes generally available.

Use Artifact Registry to push container images with Docker and govern them in Unity Catalog.

This page shows you how to configure authentication, grant access, push an image, and discover it. For concepts and limitations, see Artifact Registry. If a command or operation fails, see Troubleshoot Artifact Registry.

Prerequisites

Before you begin, you must have:

A workspace in a region that supports Artifact Registry. See Limitations.
Databricks CLI (command-line interface) version 1.17.0 or above and the Docker CLI installed on your local machine.
An existing Unity Catalog catalog and schema that are accessible from the workspace.
The Unity Catalog privileges for your operation.

Set up Docker authentication

The Databricks CLI includes an experimental command that configures Docker to request credentials for the workspace registry. The Docker credential helper requires a workspace OAuth profile created by databricks auth login. It does not support profiles that use personal access tokens, OAuth machine-to-machine (M2M) credentials, or account-only authentication.

important

The --region value must match the region of the workspace in the selected Databricks CLI profile.

To find the region, open the account console and select Workspaces.

Create or refresh a profile for the target workspace:
Bash
```
databricks auth login --profile <profile>
```
Configure Docker authentication for the registry region:
Bash
```
databricks auth docker configure --profile <profile> --region <region>
```
Omit --profile <profile> to use your default Databricks CLI profile.

The command prints the workspace registry hostname. Use this hostname when you push an image.

Grant permissions

Artifact Registry does not create the catalog or schema. Both must already exist in Unity Catalog and be accessible from the workspace.

Artifact Registry uses Unity Catalog privileges to control image access. The following table shows the least-privilege grants for each operation. Broader management privileges can also authorize some operations.

Operation	Least-privilege grants
Push a new artifact	`USE CATALOG`, `USE SCHEMA`, and `CREATE VOLUME`
Push a new version or move a tag	`USE CATALOG`, `USE SCHEMA`, and `WRITE VOLUME`
Discover artifacts and versions	`USE CATALOG`, `USE SCHEMA`, and `READ METADATA`
Use an image in a supported workload	`USE CATALOG`, `USE SCHEMA`, and `READ VOLUME`

Operation	Least-privilege grants
Push a new artifact	`USE CATALOG`, `USE SCHEMA`, and `CREATE VOLUME`
Push a new version or move a tag	`USE CATALOG`, `USE SCHEMA`, and `WRITE VOLUME`
Discover artifacts and versions	`USE CATALOG`, `USE SCHEMA`, and `READ METADATA`
Use an image in a supported workload	`USE CATALOG`, `USE SCHEMA`, and `READ VOLUME`

For a schema dedicated to Artifact Registry, an administrator can grant the privileges at the schema level. Schema-level privileges apply to every matching object in the schema, including objects created later. Use separate schemas for publishers that should not be able to modify each other's artifacts. Grant each principal only the privileges required for its operations. Replace the example values and remove unneeded privilege statements before you run the following statements:

SQL
GRANT USE CATALOG ON CATALOG <catalog> TO `<principal>`;
GRANT USE SCHEMA ON SCHEMA <catalog>.<schema> TO `<principal>`;
GRANT CREATE VOLUME ON SCHEMA <catalog>.<schema> TO `<principal>`;
GRANT WRITE VOLUME ON SCHEMA <catalog>.<schema> TO `<principal>`;
GRANT READ METADATA ON SCHEMA <catalog>.<schema> TO `<principal>`;
GRANT READ VOLUME ON SCHEMA <catalog>.<schema> TO `<principal>`;

For details about CREATE VOLUME, WRITE VOLUME, READ METADATA, and READ VOLUME, see Unity Catalog privileges reference. For other grant methods, see Show, grant, and revoke privileges.

Push an image

Use the workspace registry hostname with the image's catalog.schema.artifact:tag name.

Get the registry hostname

Use the registry hostname printed by databricks auth docker configure. If you need to construct it manually, use the numeric workspace ID and workspace region. To find the workspace ID, see Workspace instance names, URLs, and IDs.

Use the following hostname:

Text
<workspace-id>.container.<region>.gcp.databricks.com

The <region> value is the workspace region that you passed to databricks auth docker configure.

Artifact name requirements

important

Artifact names must be fully qualified Unity Catalog names in the format <catalog>.<schema>.<artifact>. Do not use slashes within the name. See The Unity Catalog object hierarchy.

The <artifact> segment can contain up to 255 characters. Use only lowercase letters, numbers, underscores, and hyphens. It must start and end with a letter or number. Use no more than two consecutive underscores, and do not place an underscore next to a hyphen.

Tag and push the image

warning

Do not include credentials or other sensitive data in an image. Check the image before you push it. Artifact versions are immutable, and delete requests are not supported. If you push sensitive data, rotate or revoke it immediately and ask an administrator to restrict any READ VOLUME grants that apply to the affected artifact. Stop using the affected digest and every tag that resolves to it, then see the information to include when you request help.

Tag a local image for Artifact Registry:

Bash
docker tag <local-image>:<local-tag> \
  <registry-hostname>/<catalog>.<schema>.<artifact>:<tag>

Push the image:

Bash
docker push <registry-hostname>/<catalog>.<schema>.<artifact>:<tag>

Discover images and versions

Use the Software Artifacts API to list artifacts in a catalog and schema and then list the versions of an artifact.

note

Dedicated Databricks CLI commands for listing and managing Artifact Registry images are not available. Use databricks api to call the Software Artifacts API.

The following examples use the profile that you configured for Docker authentication. Omit --profile <profile> if it is your default Databricks CLI profile.

List artifacts

To list artifacts, run the following command:

Bash
databricks api get --profile <profile> \
  "/api/2.1/unity-catalog/software-artifacts?parent=schemas/<catalog>.<schema>"

The response includes the artifact name and owner. If the response includes next_page_token, pass its value in the page_token query parameter to retrieve the next page, for example, &page_token=<next_page_token>.

List versions

To list versions for an artifact, run the following command:

Bash
databricks api get --profile <profile> \
  "/api/2.1/unity-catalog/software-artifacts/<catalog>.<schema>.<artifact>/versions"

The response includes the image digest, tags, and image_acceleration_details.status for each version. For response limits, see Limitations.

Check image acceleration status

Read image_acceleration_details.status from the artifact version response:

Status	Meaning
`SUCCESS`	Image acceleration completed successfully.
`UNSPECIFIED`	No successful image acceleration result has been recorded. This status does not identify a failure.

Prerequisites​

Set up Docker authentication​

Grant permissions​

Push an image​

Get the registry hostname​

Artifact name requirements​

Tag and push the image​

Discover images and versions​

List artifacts​

List versions​

Check image acceleration status​

Additional resources​