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

Use P2P acceleration in a registered cluster to distribute image pulls across nodes over the internal network, reducing registry load and application deployment time.

How it works

When a Pod starts, the P2P component intercepts the image pull request and redirects it through a local registry-mirror on the node. The registry-mirror acts as a peer and checks whether neighbors have the required layers cached. If so, it downloads them over the internal network. Otherwise, it pulls from the Container Registry Enterprise Edition instance as the origin, then seeds the data to peers.

During a rollout, most nodes pull the same image, so the registry serves it only once — subsequent pulls come from the P2P network.

Prerequisites

Make sure you have:

A Container Registry Enterprise Edition instance at Standard or Advanced Edition tier.
A registered cluster with an external Kubernetes cluster connected.

Step 1: Grant RAM permissions to the P2P add-on

The P2P add-on requires Resource Access Management (RAM) permissions to query the Container Registry instance endpoint. Grant them with onectl (recommended) or the console.

Use onectl (recommended)

Install onectl on your on-premises machine. 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 this policy:

{
    "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 access to trusted networks.
Create a Secret named alibaba-addon-secret in the kube-system namespace with 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 from 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 of your instance.
In the left-side navigation pane, click Instances.
Click your Enterprise Edition instance.
On the Overview page, copy the instance ID from the upper-left corner.

Step 3: Install the P2P component

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

Use onectl (recommended)

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`	Container Registry Enterprise Edition instance ID. Separate multiple IDs with commas.

Optional parameters

Append --set flags to customize component behavior:

Parameter	Default	Description
`pullImageInternet`	(not set)	Whether to pull add-on images over the Internet.
`p2p.plusMode.cacheTTL`	`24h`	Retention period for registry-mirror cache. Adjust based on node disk size.
`p2p.plusMode.cacheHostPath`	(none)	Host path for registry-mirror cache. If not set, cache is lost on restart.
`p2p.plusMode.ossInternetAccelerate`	(not set)	Use Object Storage Service (OSS) accelerated Internet for origin server pulls. Suitable for unstable cross-region or cross-border connections. Enable in the OSS console first.
`p2p.plusMode.downloadPattern`	(none)	Set to `source` to pull directly from registry-mirror or the Container Registry instance without P2P acceleration.
`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 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) Set the ratelimit parameter for total download and upload bandwidth. Default: 512 MB/s.
```
p2p:
  # Total net rate limit (MBytes/s) for uploading and downloading
  ratelimit: "512M"
```
Click OK.

Step 4: Enable P2P acceleration

Add the label k8s.aliyun.com/image-accelerate-mode: p2p to a workload or namespace.

Method	Scope	When to use
Label a workload	Specific Deployments or Pods	Selectively accelerate individual workloads
Label a namespace	All eligible workloads in the namespace	Accelerate all workloads without modifying YAML files

Add the label to a workload

Edit the Deployment:
```
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

Once enabled, 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 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 registry domain. Errors in standard credentials also cause P2P pull failures.

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 k8s.aliyun.com/image-accelerate-mode: p2p annotation and the rewritten image endpoint confirm that P2P acceleration is active.

Next steps

Modify component parameters

Update component parameters with 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.