Build Custom Images

Custom images let you maintain your own runtime environments. When preset images do not meet your requirements for framework versions, system dependencies, Python packages, or toolchains, you can create custom images based on existing images, Dockerfiles, third-party image registries, or previously built images. After a custom image is built, you can select it for development environments, training jobs, and inference services.

Image Naming and URLs

Custom images are typically distinguished by name, version, and commit ID. An image URL consists of the image registry address, project name, image name, version, and commit ID:

<harbor_url>/<project_name>/<name>:<version>-<commit_id>

Field	Description
`harbor_url`	The image registry address, generated by the platform based on the region and cluster.
`project_name`	The image registry project, typically generated by the platform based on the tenant or project ownership.
`name`	The image name. Use lowercase letters, numbers, hyphens, or underscores, and choose a name that indicates the framework, purpose, or project.
`version`	The image version, used to manage different versions of the same image.
`commit_id`	The image tag or commit identifier, used to distinguish iterations that share the same name and version.

You can have multiple tagged versions under the same name and version. When creating a development environment, training job, or inference service, you typically select an image by name and version. If multiple tags exist for the same version, use the image URL selected and displayed on the current page.

For images used in production training or inference, or shared across a team, use a dedicated version number or commit ID to identify the source. Avoid relying only on latest for reproduction or rollback. When possible, record the image digest, code commit, and key dependency versions within the team to make issues easier to trace.

Create Custom Images

Building an image consumes instance resources. Before creating an image, confirm that build resources are available in the current region and cluster, and check image registry storage usage. If you plan to use the image across multiple clusters, configure image synchronization after creating or building it.

Before building, identify the image’s purpose, framework version, dependency versions, and target runtime cluster. For GPU workloads, also confirm that the instance hardware, CUDA version, framework version, and base image are compatible.
Use trusted sources when working with third-party or private image registries.
If registry credentials are required, grant only the minimum permissions needed to pull or import the image.

1. Go to the Create Page

Go to Images > Custom.
On the Available Images tab, click Create.

2. Configure the Settings

Basic Information

Configuration Item	Description
Region	Select the region where the image will be built.
Cluster	Select the cluster where the image will be built.
Shared Project Groups	Configure the image’s visibility scope. To share it with other Project Groups, click Add Project Group. If you do not add a Project Group, access is generally granted according to the default scope of the Project Group to which the user who starts the build belongs.
Name	The image name. Use lowercase letters, numbers, hyphens, or underscores, and choose a name that indicates the framework, purpose, or project.
Version	The image version, used to manage multiple versions of the same image. Use a stable, sortable version number and avoid spaces, slashes, or special characters.
Commit ID	The image tag or code commit identifier, used to distinguish iterations that share the same name and version. Use the first few characters of the code repository’s commit ID to make the source easier to trace.
Image Type	The image category, such as `pytorch`, `base`, `python`, or `LLM`, used to classify and manage images.
Labels	Used to search for and categorize images.
Description	Describe the image source, purpose, framework version, dependencies, or usage restrictions.

Runtime Information

Configuration Item	Description
Resource Type	Select the billing type for resources used by the build task, such as Reserved, On-demand, or Spot.
Instance	When using Reserved, select a resource pool.
Instance Type and Quantity	GPU and CPU are supported. Select the instance specifications for the build task from the instance list, and configure Count Per Node. When selecting instances, pay particular attention to Remaining Quota and Pool Available.
Resource Priority	Configure the scheduling priority after selecting instances. Instances are sorted from highest to lowest priority, and those listed first are used preferentially during scheduling.

Build Configuration

First, select a build method, then enter the corresponding build configuration. Do not put long-lived keys in Dockerfiles, regular build arguments, or installation commands. Even if you later delete a file or command, sensitive content may remain in image layers, build history, or logs.

Based on an Existing Image
Based on a Dockerfile
From a Third-Party Image Registry
Import an Existing Image

Use this method to add dependencies to a preset image or an existing custom image.

Configuration Item	Description
Base Image	Select a Preset or Custom image to use as the base image.
Dependencies	Add system and Python dependencies in one of the following ways: Add system packages in `apt`, such as `vim`. Add Python 3 dependencies and versions in `pip3`. Upload `apt.txt` and `pip.txt` files to import dependencies in batches.

apt.txt and pip.txt are text files with one dependency per line.The dependency installation method must match the base image. apt is generally used for Ubuntu system dependencies, and yum is generally used for CentOS system dependencies. pip2 and pip3 are used for Python 2 and Python 3 dependencies, respectively.

Example apt.txt:

python3=3.8.2-0ubuntu2
python3-pip=20.0.2-5ubuntu1.11
curl=7.68.0-1ubuntu2.25
wget=1.20.3-1ubuntu2.1

Example pip.txt:
requests==2.31.0 flask==2.3.3

Use this method to define the complete build logic in a Dockerfile. After selecting it, enter the Dockerfile contents and build arguments. Build arguments pass variables to the build process for use in the Dockerfile.To install apt or pip dependencies, you can:

Write the installation commands directly in the Dockerfile.
Add dependencies under Dependencies or upload apt.txt and pip.txt. After the platform returns the corresponding installation commands, copy them to the appropriate locations in the Dockerfile.

Example:

FROM ubuntu:18.04

RUN apt-get update && apt-get install -y --no-install-recommends \
    python3-pip \
    vim && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

RUN pip3 install \
    numpy==1.19.5 \
    scipy==1.5.4

RUN ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime

Copying content to a shared directory during the build is not currently supported. If the build depends on large files, private code, or model files, first decide whether to include them in the image or mount them from a Volume when the workload runs.

3. Submit the Build

After configuring the settings, click Create to submit the build task. After submission, you can check the build status and logs in Image Build Task List. When the build succeeds, the image appears in Available Images.

Save an Image from a Development Environment

You can also save a development environment as a custom image. This is useful when you have installed software and debugged dependencies in a development environment and want to preserve the current container file system as a reusable image.

1. Confirm What to Save

Before saving an image, confirm that the dependencies, tools, and configuration you want to reuse have been written to the container file system. Saving an image does not back up mounted Volumes or process memory. Code, models, data, and training results that exist only on mounted Volumes remain in their original storage; mount that storage again when you use the image later. Before saving, remove credentials, temporary tokens, and other sensitive content that should not be included in the image. For environments that require long-term maintenance, keep a Dockerfile or dependency list as well instead of relying only on a one-time save.

2. Submit the Image Save

Keep the development environment running. Use the Save Image entry on the development environment page, enter the image name, version, and build information, and submit the request. The development environment might be temporarily unavailable while the image is being saved. We recommend saving when no interactive work is in progress. Do not stop, delete, or reschedule the source environment, or make extensive dependency changes at the same time. For the specific entry and steps, see Use a JupyterLab Development Environment or Use a VSCS Development Environment.

3. Verify the Save Result

After submitting, confirm that the build succeeded in Image Build Task List. If saving fails, review the build logs and first check the container size, build resources, dependency files, and source environment status. After a successful save, verify key dependencies in a new development environment or a small workload rather than checking them only in the original environment.

View Build Results

After submitting a build task, check its status in Image Build Task List. If a build fails, first review the errors in the build logs, then use the scheduling information to determine whether the cause is dependency installation, the Dockerfile, image pulling, resource scheduling, or synchronization settings.

Action	Description
Build Logs	View the image build logs. If the build fails, use the logs to locate issues with dependency installation, the Dockerfile, image pulling, or command execution.
Build Configuration	View the build task configuration, including the base image, Dockerfile, dependencies, build arguments, and resource settings.
Update Configuration	Modify the build task configuration. Before updating, confirm that the image is not being built; wait until the build succeeds, fails, or stops. Updates generally have the following effects: Name, Version, Build Region, and Build Cluster usually cannot be changed. Changing build-related fields such as the build method, base image, Dockerfile, build arguments, dependencies, synchronization settings, commit ID, instance settings, or resource pool may trigger a rebuild. Changing only metadata such as the description, image type, framework version, Python / CUDA / NCCL versions, chip type, labels, or Project Groups usually does not require a rebuild. Images created by saving a development environment or synchronizing an image registry may allow metadata updates only.
View Image	Open the image generated by the completed build. The image might not be available to view if the build has not succeeded.
Clone	Create a new build task based on the current task configuration. This is useful for reusing the base image, dependencies, and build arguments.
Stop	Stop an ongoing build task. The image will no longer be built after the task stops. Whether an image is already available depends on the current build result. Stopping the build does not necessarily undo images already created or external changes.
Delete	Delete a build task record that is no longer needed. Before deleting it, confirm that you no longer need to view its build logs or configuration.

Frequently Asked Questions

What should I do if a build task stays queued for a long time?

Check the build resources, resource pool availability, remaining user quota, and scheduling information. If the build is waiting for resources, do not repeatedly submit tasks with the same name and version.

What should I check first when a build fails?

First review the errors in Build Logs, then use the scheduling information to identify the failure stage. Common causes include dependency installation failures, an incorrect Dockerfile path, a failure to pull the base image, command execution errors, or insufficient build resources.

What should I do if apt or pip installation fails?

Check the package name, version, installation source, and compatibility with the base environment. To pin dependency versions, declare them in the Dockerfile or a dependency file to avoid pulling incompatible versions during the build.

What should I do if the Dockerfile cannot find a file?

Check the build inputs, working directory, and file reference paths. Files referenced by the Dockerfile must be in the current build context.

What should I do if importing an external image fails?

Check the source registry address, authentication information, network access, and target registry errors. Grant private registry credentials only the minimum permissions needed to pull or import images.

What should I do if I cannot find the image in the target workload after a successful build?

Return to Available Images and confirm that the image’s region, target cluster URL, shared Project Groups, and filters are as expected. For cross-cluster use, also confirm that image synchronization has completed.

If you need to submit the issue to the technical support team, provide the image name and version, region and cluster, build task ID, failure stage, and redacted error logs. Do not send repository account credentials, passwords, or tokens.

Next Steps

Manage Custom Images

Get Started

Resources

Development & Training

Models & Inference

Operations & Governance

Best Practices

Developer Access

FAQ

Build Custom Images

Image Naming and URLs

Create Custom Images

1. Go to the Create Page

2. Configure the Settings

Basic Information

Runtime Information

Build Configuration

3. Submit the Build

Save an Image from a Development Environment

1. Confirm What to Save

2. Submit the Image Save

3. Verify the Save Result

View Build Results

Frequently Asked Questions

Next Steps

​Image Naming and URLs

​Create Custom Images

​1. Go to the Create Page

​2. Configure the Settings

​Basic Information

​Runtime Information

​Build Configuration

​3. Submit the Build

​Save an Image from a Development Environment

​1. Confirm What to Save

​2. Submit the Image Save

​3. Verify the Save Result

​View Build Results

​Frequently Asked Questions

​Next Steps

Image Naming and URLs

Create Custom Images

1. Go to the Create Page

2. Configure the Settings

Basic Information

Runtime Information

Build Configuration

3. Submit the Build

Save an Image from a Development Environment

1. Confirm What to Save

2. Submit the Image Save

3. Verify the Save Result

View Build Results

Frequently Asked Questions

Next Steps