How to use P2P to accelerate image pulling-Container Service for Kubernetes(ACK)-阿里云帮助中心

When many nodes pull the same container image simultaneously, the registry becomes a bottleneck that slows down application rollouts. P2P acceleration distributes image data across compute nodes using their internal network bandwidth, so each node can receive image layers from peers instead of pulling from the registry independently. The first node to pull an image seeds the data for all subsequent nodes — the registry serves the image once regardless of fleet size.

This topic describes how to install and enable the ack-acr-acceleration-p2p component in a registered cluster and verify that P2P acceleration is working.

How it works

When a Pod starts, the P2P acceleration component intercepts the image pull request and redirects it through a local registry-mirror running on the node. The registry-mirror acts as a peer in the P2P network and checks whether neighboring nodes already have the required image layers cached. If they do, it downloads the layers from peers over the internal network. If no peer has the data yet, it pulls from the Container Registry Enterprise Edition instance as the origin server, then seeds the data to other peers.

Because most nodes pull the same application image during a deployment rollout, this flow means the registry serves the image only once — all subsequent node pulls are served from the P2P network.

Prerequisites

Before you begin, make sure you have:

A Container Registry Enterprise Edition instance at Standard Edition or Advanced Edition tier. For setup instructions, see Create a Container Registry Enterprise Edition instance.
A registered cluster with an external Kubernetes cluster connected to it. For setup instructions, see Create a registered cluster.

Step 1: Grant RAM permissions to the P2P component

The P2P component needs Resource Access Management (RAM) permissions to query the Container Registry instance endpoint. Grant these permissions using onectl (recommended) or the console.

Use onectl (recommended)

Install onectl on your on-premises machine. For instructions, see Use onectl to manage registered clusters.

Grant RAM permissions to the P2P component:

onectl ram-user grant --addon ack-acr-acceleration-p2p

Expected output:

Ram policy ack-one-registered-cluster-policy-ack-acr-acceleration-p2p granted to ram user ack-one-user-ce313528c3 successfully.

Use the console

Create a RAM user.

Create a custom policy with the following configuration:

{
    "Version": "1",
    "Statement": [
        {
            "Action": [
                "cr:ListInstanceEndpoint",
                "cr:GetInstanceVpcEndpoint"
            ],
            "Resource": "*",
            "Effect": "Allow"
        }
    ]
}

Attach the custom policy to the RAM user.
Create an AccessKey pair for the RAM user.

Warning
Configure AccessKey pair-based policies for network access control to restrict invocation sources to trusted network environments.
Create a Secret named alibaba-addon-secret in the kube-system namespace using the AccessKey pair:
```
kubectl -n kube-system create secret generic alibaba-addon-secret \
  --from-literal='access-key-id=<ACCESSKEY_ID>' \
  --from-literal='access-key-secret=<ACCESSKEY_SECRET>'
```
Replace <ACCESSKEY_ID> and <ACCESSKEY_SECRET> with the AccessKey pair you created in the previous step.

Step 2: Get the Container Registry instance ID

Log on to the Container Registry console.
In the top navigation bar, select the region where your instance is located.
In the left-side navigation pane, click Instances.
Click the Enterprise Edition instance you want to use.
On the Overview page, copy the instance ID shown in the upper-left corner.

Step 3: Install the P2P component

Install the ack-acr-acceleration-p2p component using onectl (recommended) or the console.

Use onectl (recommended)

Run the following command to install the component:

onectl addon install ack-acr-acceleration-p2p \
  --set region=<REGION_ID>,acrInstances=<INSTANCE_ID>,pullImageInternet=true

Required parameters

Parameter	Description
`region`	Region ID of the Container Registry Enterprise Edition instance
`acrInstances`	ID of the Container Registry Enterprise Edition instance. Separate multiple IDs with commas.

Optional parameters

Append --set flags to customize the component behavior:

Parameter	Default	Description
`pullImageInternet`	(not set)	Whether to pull images over the Internet.
`p2p.plusMode.cacheTTL`	`24h`	Retention period for data cached by registry-mirror. Adjust based on node disk size.
`p2p.plusMode.cacheHostPath`	(none)	Host path where registry-mirror stores cached data. If not set, cached data is lost when registry-mirror restarts.
`p2p.plusMode.ossInternetAccelerate`	(not set)	Use Object Storage Service (OSS) accelerated Internet connection when pulling from origin servers. Suitable for unstable cross-region or cross-border network conditions. Enable this feature in the OSS console before use.
`p2p.plusMode.downloadPattern`	(none)	Set to `source` to configure the P2P agent to pull directly from registry-mirror or the Container Registry instance. In this scenario, the P2P acceleration component is not installed.
`p2p.plusMode.nodeSelectorEnable`	(not set)	Deploy the scheduler and registry-mirror only to nodes with the `k8s.aliyun.com/p2p-plus-node=true` label.

Expected output:

Addon ack-acr-acceleration-p2p, version **** installed.

Use the console

Log on to the ACK console. In the left-side navigation pane, choose Marketplace > Marketplace.
On the App Catalog page, search for ack-acr-acceleration-p2p and click the result.
Click Deploy in the upper-right corner.
In the Deploy panel, select the target Cluster and Namespace, click Next, and select the latest chart version.
On the Parameters page, set acrInstances to the Container Registry Enterprise Edition instance ID. Separate multiple IDs with commas.

The P2P component uses port 65001 on nodes by default. If that port is occupied, change it with the p2p.port parameter.
```
# [Required]
# ID of ACR EE instances, support multi, e.g. "cri-xxx,cri-yyy"
acrInstances: ""
p2p:
  ...
  # Port of P2P Agent in host network
  port: 65001
```
(Optional) Adjust the ratelimit parameter to set the total bandwidth limit for downloads and uploads. The default is 512 MB/s.
```
p2p:
  # Total net rate limit (MBytes/s) for uploading and downloading
  ratelimit: "512M"
```
Click OK.

Step 4: Enable P2P acceleration

Enable P2P acceleration by adding the label k8s.aliyun.com/image-accelerate-mode: p2p to a workload or a namespace.

Method	Scope	When to use
Add label to a workload	Specific Deployments or Pods	Apply acceleration selectively to individual workloads
Add label to a namespace	All eligible workloads in the namespace	Apply acceleration broadly without modifying individual YAML files

Add the label to a workload

Open the Deployment for editing:
```
kubectl edit deploy <DEPLOYMENT_NAME>
```

Add the k8s.aliyun.com/image-accelerate-mode: p2p label to the pod template metadata:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: test
  labels:
    app: nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        # Enable P2P acceleration
        k8s.aliyun.com/image-accelerate-mode: p2p
        app: nginx
    spec:
      imagePullSecrets:
      - name: test-registry
      containers:
      - image: test-registry-vpc.cn-hangzhou.cr.aliyuncs.com/docker-builder/nginx:latest
        name: test
        command: ["sleep", "3600"]

Add the label to a namespace

kubectl label namespaces <YOUR-NAMESPACE> k8s.aliyun.com/image-accelerate-mode=p2p

Step 5: Verify P2P acceleration

After enabling P2P acceleration, the component automatically injects P2P annotations, a P2P image endpoint, and image pull credentials into each Pod at scheduling time.

Important

The component skips injection if the Pod's YAML does not reference an image from the Container Registry Enterprise Edition instance, or if the image pull Secret for the original endpoint is missing.
P2P credentials differ from standard credentials only in the image registry domain name. If the standard credentials contain errors, P2P image pulls will also fail.

Check the injected values by inspecting a Pod:

kubectl get po <POD_NAME> -o yaml

Expected output (relevant fields):

apiVersion: v1
kind: Pod
metadata:
  annotations:
    # Injected P2P annotation
    k8s.aliyun.com/image-accelerate-mode: p2p
    k8s.aliyun.com/p2p-config: '...'
spec:
  containers:
  # Image endpoint rewritten to P2P address
  - image: test-registry.distributed.cn-hangzhou.cr.aliyuncs.com:65001/docker-builder/nginx:latest
  imagePullSecrets:
  - name: test-registry
  # P2P pull credential injected
  - name: acr-credential-test-registry-p2p

The presence of the k8s.aliyun.com/image-accelerate-mode: p2p annotation and the rewritten image endpoint confirms that P2P acceleration is active for this Pod.

What's next

Modify component parameters

Update a running component with new parameters using onectl. For example, extend the cache TTL to 72 hours:

onectl addon upgrade ack-acr-acceleration-p2p --set p2p.plusMode.cacheTTL=72h

Uninstall the component

Use onectl:

onectl addon uninstall ack-acr-acceleration-p2p

Expected output:

Addon ack-acr-acceleration-p2p uninstalled.

Use the console:

Log on to the ACK console. In the left-side navigation pane, click Clusters.
Click the cluster name, then choose Applications > Helm.
Find ack-acr-acceleration-p2p and click Delete in the Actions column.
In the Delete dialog box, click OK.