Snowpark Container Services: Working with an image registry and repository¶

Snowpark Container Services provides an OCIv2-compliant image registry service and a storage unit call repository to store images.

Image registry¶

The image registry service serves the OCIv2 API for storing OCI-compliant container images.

Image registry hostname¶

Each image registry in a Snowflake account has a unique hostname, which allows OCI clients (such as Docker CLI) to access an image registry using REST API calls. The general syntax for an image registry hostname is:

<orgname>-<acctname>.registry.snowflakecomputing.com

In the hostname:

<orgname>-<acctname> identifies a Snowflake account.
registry allows Snowflake to provide hostnames per account for registry customers.

The hostname is always all lowercase.

Note

A Snowflake account name (<acctname>) can have an underscore (for example, my_account), but underscores are not valid in a URL. Therefore, when using a registry hostname, you need to replace an underscore with a dash. For example, change my_account to my-account.

You can find your organization name and account name information for image repository host names in one of the following ways:

The Snowsight web interface: Use the account selector. For more information, see Getting started with Snowsight.
Execute the SHOW IMAGE REPOSITORIES command.

Image registry authentication¶

To access an image repository in your Snowflake account, users must authenticate to the image registry using their Snowflake credentials. Additionally, appropriate privileges are required to access repositories within the registry. To obtain these privileges, a user must have a role that grants access privileges to the repository.

You have the following options to authenticate your client with an image registry in your account:

Use client-provided commands: Tools like Docker offer commands to authenticate with a registry using a username and password. For instance, in Tutorial 1 (see Tutorial 1: Build and upload the image), you use the docker login command to authenticate Docker with a registry. This method is only available if your account administrator permits the user to use username/password authentication.
Use Snowflake CLI: The Snowflake CLI supports all forms of Snowflake authentication.
- For the Docker client, use the snow spcs image-registry login command to authenticate Docker with a registry.
- For any client (including Docker), Snowflake CLI also provides the option to first generate an authentication token and use it to authenticate the client. For more information, see snow spcs image-registry token.

Image repository¶

A registry is a service that serves the OCIv2 API, and a repository is a storage unit that you create within the service.

A repository is a named location in your account where you store images. This is similar to the relationship between a DBMS and a table within the DBMS. That is, a DBMS is equivalent to a registry, and a table is equivalent to a repository.

You can create one or more repositories in your Snowflake account. For example, DEV, TEST, and PROD repositories can store images during development, testing, and production. You can also create repositories that have different permissions; for example, some repositories may be read-only for some roles.

Access control is supported at the repository level; individual image-level access control is not supported.

For uploading images to an image repository, the registry service offers various authentication options and single sign-on (SSO).

Attention

Snowpark Container Services image repositories do not support Tri-Secret Secure and Periodic rekeying. This means that if your account has enabled Tri-Secret Secure or enabled periodic rekeying, while all other Snowflake data will continue to have added security, any images stored in your Snowpark Container Services image repositories will not benefit from this added security.

To create an image repository in an account with Tri-Secret Secure or periodic rekeying, you must first confirm that you understand and agree to continue without the benefit from this additional security for your image repositories. To confirm agreement, an account administrator (user with the ACCOUNTADMIN role) will need to set the account-level parameter ENABLE_TRI_SECRET_AND_REKEY_OPT_OUT_FOR_IMAGE_REPOSITORY to TRUE.

Image repository URL¶

The following is a general syntax for a Snowflake repository URL:

<registry-hostname>/<db_name>/<schema_name>/<repository_name>

For example,

myorg-myacct.registry.snowflake.com/my_db/my_schema/my_repository

To look up the repository URL in your account, use the SHOW IMAGE REPOSITORIES SQL command.

Note

Snowflake URL-encodes the $ character, which is the only non-URL character Snowflake supports in identifiers (See Identifier Requirements). Double-quoted names that contain special characters are not supported.
When you manually construct a repository URL, replace an underscore in an account name (my_acct) with a dash (my-acct).

Repository operations¶

To create and manage repositories, Snowflake supports the following repository operations:

CREATE IMAGE REPOSITORY
DROP IMAGE REPOSITORY
SHOW IMAGE REPOSITORIES

To list images stored within a Snowflake image repository, use the following command:

SHOW IMAGES IN IMAGE REPOSITORY

For an example of creating a repository and uploading an image, see Tutorial Common Setup.

Repository privileges¶

When you work with a repository, the following privilege model applies:

To create a repository in a schema, you must have the CREATE IMAGE REPOSITORY privilege on the schema.

For repository management, the following privileges (capabilities) are supported:

Privilege	Usage
READ	Enables listing and downloading images from a repository.
WRITE	Enables listing and downloading images from a repository. You can also push images in the repository.
OWNERSHIP	Enables listing and downloading images from a repository. You can also push images in the repository.
SERVICE READ	Enables a container service to list and download images from a repository. This is needed for the image building step of model serving.
SERVICE WRITE	Enables a container service to push images in the repository. This is needed for the image building step of model serving.

Guidelines and Limitations¶

Dropping images from a repository is currently not supported. You can drop a repository, but that removes all images from that repository.
Contact your account representative if you require inbound private connectivity.