Image caching reduces image preparation time and accelerates instance startup. An image cache belongs to the current Workspace and is visible and manageable only within that Workspace.
The image cache feature is currently in public preview, and no fees are charged during the public preview period. Billing will start after the feature becomes generally available.
Prerequisites
Before you create an image cache, make sure the following conditions are met:
-
A Workspace is created, and you have entered the target Workspace.
-
The source image is pushed to an image repository in Container Registry (ACR), and the image version (Tag) and Digest are available.
Image caches are matched and reused based on the image content Digest. Overwriting an image by pushing new content to the same Tag is currently not supported, except for
latest. -
A public access whitelist or VPC access is configured in ACR for the current Workspace before the source image is pulled.
Before you create a new image cache, grant AgentCore permission to read the selected source image. This authorization is separate from the Agent execution role. If permissions are insufficient, follow the console prompt to authorize access, and then refresh the authorization status before you continue.
Configure network access in ACR before you pull the source image. The following table lists the configuration requirements for the public network and VPC pull paths:
|
Pull path |
ACR configuration |
Creation panel toggle |
|
Public network |
Configure a public access whitelist for the current Workspace |
Allow Default NIC to Access Internet, enabled by default |
|
VPC |
Configure VPC access for the current Workspace |
Allow VPC Access, disabled by default; turn it on |
The creation panel displays the public egress IP of the current Workspace. For the first whitelist configuration, open the creation panel to get this IP, configure the whitelist in ACR, and then create the image cache.
The network options in the creation panel apply only to this image pull and transfer. They are not saved as the Agent network configuration.
Create an image cache
After you complete the prerequisites, create an image cache on the Image Cache page of the target Workspace.
-
Log on to the AgentCore console.
-
Go to the Image Cache page of the target Workspace.
-
Click Create Image Cache.
-
Configure the following parameters in the creation panel.
Configuration item
Required
Description
Workspace
Yes
Read-only. Displays the current Workspace.
Region
Yes
Read-only. Displays the region of the current Workspace. The supported regions are subject to the console display.
Container image instance
Yes
Select the ACR instance that contains the source image.
Image repository
Yes
Select the source image repository. You must first select a Container image instance.
Image version
Yes
Select the target image version. You must first select an Image repository. The version list displays the image version, Digest, image size, and latest push time. You can search the list by version and refresh it.
Allow Default NIC to Access Internet
No
Enabled by default. Specifies whether this image pull and transfer can access the public network through the default network interface.
Allow VPC Access
No
Disabled by default. Specifies whether this image pull and transfer can access a VPC.
-
Click Create.
After you submit the creation request, view the image cache and its status on the Image Cache page of the Workspace. Creation usually takes a few minutes. During this period, Agents with image caching enabled can still create instances by using cold starts.
|
Status |
Meaning |
|
Creating |
The image cache is being prepared. During this period, Agents with image caching enabled can still create instances by using cold starts. |
|
Available |
The image cache is ready. New instances of Agents with image caching enabled automatically use the cache to accelerate startup. |
|
Failed |
Image cache creation failed. Agents with image caching enabled can still create instances by using cold starts. You can view the failure reason in the cache details and retry. |
View image caches
On the Image Cache page of the Workspace, you can view the image caches that you created and perform the following operations:
-
In the Search by image name or source image address box, enter a keyword to search.
-
Filter image caches by status. By default, All Statuses is selected. You can filter by Creating, Available, or Failed.
-
Refresh the list to get the latest status.
The list displays the image and version, status, Agents that use the cache, and actions. The actions include Details and Delete.
View cache details
Click Details in the list to view the cache details, including the source image, Digest, cache size, creation time, status description, and the Agents that use the cache. A Digest uniquely identifies the content of an image. If the cache status is Failed, you can view the failure reason in the status description and retry.
Use an image cache for an Agent
Image caching is configured at the Agent level. When you create or edit an Agent, select an image version and enable image caching. If a matching image cache is available, it is reused. If no matching image cache is available, an image cache is prepared together with the Agent. Preparation usually takes a few minutes, and Agent runtime instances can cold start during this period.
If permissions are insufficient when you enable image caching, the page displays an authorization reminder. You can go to complete the authorization and refresh the authorization status. If the authorization is not complete, the submission is blocked. After the authorization is complete and the status is refreshed, the reminder disappears, and you can submit the request as expected.
Enabling image caching does not rebuild existing runtime instances. The configuration applies to instances that are subsequently created, scaled out, or rebuilt for other reasons. Disabling image caching causes the platform to rebuild the related runtime instances. Do not delete the image cache until the rebuild is complete and those instances no longer use it.
Delete an image cache
You can delete an image cache only when no Agent in the current Workspace has image caching enabled for the cache, and no runtime instance still uses the cache. First disable image caching for the related Agents, and then wait for the rebuild and release to finish. An Agent count of zero alone does not mean that the cache can be deleted. Follow the deletion availability and reason displayed in the console. Start the deletion from the image cache list or the cache details, and confirm the deletion to remove the cache from the current Workspace.