Container Registry Enterprise Edition stores and distributes custom Open Container Initiative (OCI) artifacts alongside container images and Helm charts. This guide walks through pushing a local file as a custom OCI artifact to a Container Registry Enterprise Edition instance and pulling it back with the ORAS (OCI Registry As Storage) client.
Prerequisites
Before you begin, ensure that you have:
The ORAS client installed on your local machine. See Installation
Internet access enabled or a virtual private cloud (VPC) access control list (ACL) configured for your Container Registry Enterprise Edition instance. This guide uses Internet access. See Configure access over the Internet
The logon password for your Container Registry Enterprise Edition instance. If you've forgotten it, reset it by reconfiguring access credentials. See Configure access credentials for a Container Registry Enterprise Edition instance
Push a custom OCI artifact
Step 1: Set environment variables
Set your registry details as environment variables. All subsequent commands reference these variables, so you only need to update them once.
REGISTRY=<instance-name>-registry.cn-<region>.cr.aliyuncs.com
NAMESPACE=<namespace>
REPO=<image-repository>
TAG=<artifact-version>
IMAGE=$REGISTRY/$NAMESPACE/$REPO:$TAGReplace the placeholders with your actual values:
| Placeholder | Description | Example |
|---|---|---|
<instance-name> | Name of your Enterprise Edition instance | my-registry |
<region> | Region where the instance is deployed | hangzhou |
<namespace> | Namespace in your instance | my-namespace |
<image-repository> | Image repository name | my-artifacts |
<artifact-version> | Version tag for the artifact | v1.0 |
Step 2: Log in to the instance
oras login --username=<username> $REGISTRYEnter your logon password when prompted. A successful login displays:
login succeededStep 3: Create a local artifact
Create a sample file to use as the artifact:
echo "hello world" > artifact.txtStep 4: Push the artifact
Push the file to your instance using the $IMAGE variable set earlier:
oras push $IMAGE \
--manifest-config /dev/null:application/vnd.customized.artifact.config \
./artifact.txtThe --manifest-config flag sets the artifact media type to application/vnd.customized.artifact.config, which distinguishes this custom artifact from a standard container image (which uses application/vnd.oci.image.config.v1+json). The ./artifact.txt argument specifies the local file to upload.
A successful push produces output similar to:
Uploading a948904f2f0f artifact.txt
Uploaded a948904f2f0f artifact.txt
Pushed [registry] <instance-name>-registry.cn-<region>.cr.aliyuncs.com/<namespace>/<image-repository>:<artifact-version>
Digest: sha256:...Pull a custom OCI artifact
Step 1: Set environment variables
If you're in a new shell session, set the environment variables again:
REGISTRY=<instance-name>-registry.cn-<region>.cr.aliyuncs.com
NAMESPACE=<namespace>
REPO=<image-repository>
TAG=<artifact-version>
IMAGE=$REGISTRY/$NAMESPACE/$REPO:$TAGStep 2: Log in to the instance
oras login --username=<username> $REGISTRYStep 3: Pull the artifact
Delete the local copy first to confirm the pull retrieves the file from the registry:
rm -f artifact.txt
oras pull $IMAGEStep 4: Verify the artifact
cat artifact.txtIf the pull succeeded, the output is:
hello world