Custom images

Custom images let you import existing images or build new ones directly on PAI, supporting development and training workflows.

Overview

Custom images can be added in two ways:

Import an existing image: Build the image locally or on a cloud server, push it to Alibaba Cloud Container Registry (ACR), and then register it as a PAI custom image by entering the ACR image details in the PAI console.
Build a new image: Enter the ACR image details, runtime settings, and build configuration in the PAI console. After the build completes, the image is automatically pushed to ACR and registered as a PAI custom image.

Permissions

Alibaba Cloud account (primary account): Has full permissions. No additional authorization is required.
RAM user (sub-account): Must be added to the workspace as a member and assigned a role. For details, see Manage workspaces - Members and roles.

Register an image: import an existing image

Go to AI Asset Management > Images and select a workspace. On the Custom Image tab, click Register image, select Import existing image, and register an image from Alibaba Cloud Container Registry (ACR) as a PAI custom image.

Key parameters:

Parameter	Description
Image type	Personal Edition image: Provides basic container registry services for individual developers. Personal Edition ACR images may be rate-limited. Enterprise Edition ACR images are recommended. For details, see Announcement about image upload and download restrictions of Container Registry Personal Edition. Enterprise Edition image: Hosts and distributes OCI (Open Container Initiative)-compliant artifacts — container images, Helm charts, and Operators — for enterprise customers.
Enterprise Edition instance / image namespace / image repository / image tag / custom domain	Select an existing Enterprise Edition instance, namespace, repository, image tag, and custom domain, or go to the Container Registry console to create them. Note The Enterprise Edition instance and custom domain are required only when Image type is Image (Container Registry Enterprise Edition). If a permission error appears, attach the AliyunContainerRegistryReadOnlyAccess policy to the RAM user. For details, see Manage RAM user permissions.
Visibility	Visible to creator only: The registered image is visible only to the creator and administrators in this workspace. Visible to workspace members: The registered image is visible to all members in this workspace.
Chip type	Select CPU, GPU, or PPU based on the target environment where the image will run.

Register an image: build a new image

Go to AI Asset Management > Images and select a workspace. On the Custom Image tab, click Register image and select Build new image. After the build completes, the image is automatically pushed to ACR and registered as a PAI custom image.

Key parameters:

Parameter	Description
Basic information
Image type	Only Enterprise Edition images can be built. For more information, see What is Container Registry?.
Enterprise Edition instance / image namespace / image repository / custom domain	Select an existing Enterprise Edition instance, namespace, repository, and custom domain, or go to the Container Registry console to create them. Note If a permission error appears, attach the AliyunContainerRegistryReadOnlyAccess policy to the RAM user. For details, see Manage RAM user permissions.
Visibility	Visible to creator only: The registered image is visible only to the creator and administrators in this workspace. Visible to workspace members: The registered image is visible to all members in this workspace.
Chip type	Select CPU, GPU, or PPU based on the target environment where the image will run.
Runtime settings
Runtime resources	Select the compute resources for the build job based on the resource requirements of the dependencies or Dockerfile instructions in Build configuration. For example, if the Dockerfile includes compilation steps, select a higher resource allocation.
VPC / security group	Select the VPC bound to the Enterprise Edition instance. Note If the build job needs to access the internet (for example, to pull third-party base images or install dependencies specified in Build configuration), create a public NAT gateway for the VPC, bind an elastic IP address (EIP), and configure SNAT rules. For details, see Improve internet access with a private gateway.
Build configuration
Build method	Build from existing image: Supports official images, custom images, and third-party image addresses (private registries require a username and password). You can install dependencies using pip2, pip3, yum, or apt. Build from Dockerfile: Supports Dockerfile-style instruction editing. For syntax details, see Dockerfile reference.

View image build jobs

On the Custom Image tab, click View Task to view the image build job list.
Click Details in the Actions column to view the image build job details.
In the Runtime settings section, click View Logs and View monitoring to check the logs and monitoring data for the corresponding DLC job.

View custom images

After registration, go to the Custom Image tab to view the registered image addresses. Use these images in training jobs.

In the Image address column of the image list, the VPC address of each image is shown in the format <registry-name>-vpc.<region>.cr.aliyuncs.com/<namespace>/<image>:<tag>. Use this address to reference the custom image in training jobs.

FAQ

Q: When building an image with a Dockerfile, the logs show `dial tcp xxx:443: i/o timeout`. How do I fix this?

This error means the build job can't reach the registry hosting the base image:

Check whether the image address in the FROM instruction or the Based on existing image field uses a public domain. If so, replace it with the corresponding VPC domain (public domain format: <registry>.cn-xxx.cr.aliyuncs.com; VPC domain format: <registry>-vpc.cn-xxx.cr.aliyuncs.com).
Confirm that the VPC selected in VPC / security group has been bound in the Enterprise Edition instance under Access control > VPC.
If the timeout persists, check whether the security group rules allow outbound traffic from the build job to the ACR VPC endpoint.