全部產品
Search
文件中心

Container Registry:使用免密組件跨帳號拉取鏡像

更新時間:Aug 06, 2025

在阿里雲多帳號體系中,Container ServiceACK叢集與Container RegistryACR企業版執行個體可能由不同業務組織的不同帳號管理,需要確保網路互聯並且帳號得到授權才能實現ACK從ACR拉取容器鏡像部署工作負載。本文介紹如何使用aliyun-acr-credential-helper免密組件跨帳號拉取鏡像。

選型思路

建議您優先考慮滿足業務需求的網路連接方式和帳號授權方式,再選擇支援該授權方式的免密組件。

具體操作步驟請按照配置網路連接配置帳號授權和免密組件的流程,並完成驗證跨帳號鏡像拉取
說明

本文的跨帳號指的是不同阿里雲帳號(主帳號),而非RAM使用者(子帳號)

前提條件

  • 已為免密組件使用的RAM角色授權

  • ACK叢集已支援使用免密組件。

    • aliyun-acr-credential-helper(託管形態)

      • 1.22及以上版本的ACK託管叢集Pro版

      • 1.22及以上版本的ACK Serverless叢集

      • 1.22及以上版本的ACK Edge叢集

    • aliyun-acr-credential-helper(自行營運)

      • 1.20.0及以上版本的ACK託管叢集基礎版

      • 1.20.0及以上版本的ACK託管叢集Pro版

      • 1.20.0及以上版本的ACK專有叢集

  • Container RegistryACR執行個體類型為企業版執行個體。

    重要
    • 免密組件目前僅支援與ACR企業版及2024年09月08日及更早建立的ACR個人版配合使用。如無法使用免密組件,請參見如何使用imagePullSecrets

操作步驟

步驟一:配置網路連接

跨帳號拉取鏡像時,需要拉取鏡像的ACK叢集與鏡像所在的ACR企業版執行個體處於不同使用者賬戶下的不同VPC,並有可能處於不同地區,在拉取鏡像前需要確保雙方的網路連通和相關網域名稱可解析,有以下幾種實現方式:

  • 公網串連:即為ACR企業版執行個體配置公網端點,並為ACK叢集開啟訪問公網的能力,雙方通過公網傳輸鏡像。但通過公網傳輸安全性較低,並會產生Elastic IP Address與流量費用。

  • VPC對等串連:您可使用VPC對等串連打通兩個VPC,使ACK叢集可以訪問ACR企業版執行個體。VPC處於同一地區時,對等串連功能不收取費用,處於不同地區時收費。但使用功能需要兩個VPC共用網段,會導致VPC網段減少。並且,如果兩個VPC中已使用的網段大量重合,您需要對現存網路架構進行改造。

  • 雲企業網串連:1個雲企業網執行個體可包含1個或多個轉寄路由器,多個轉寄路由器之間可通過跨地區串連互聯,從而實現跨地區跨帳號VPC互連。

關於VPC對等串連和雲企業網串連的對比,請參見雲企業網與VPC對等串連有什麼區別?

對比項

公網串連

VPC對等串連

雲企業網串連

網路類型

公網

私網

私網

計費

Elastic IP Address計費方式產生費用。

按雲企業網計費規則產生費用。

主要特點

無需對現有網路架構進行修改,安全性方面需要考慮出入方向規則、存取控制等。

  • 鏡像通過內網傳輸,安全性較高。VPC處於同地區時不產生費用。

  • 使用該功能使兩個VPC共用網段,會導致VPC可用網段減少。如果兩個VPC中已使用的網段大量重合,您需要對現存網路架構進行改造。

  • 鏡像通過內網傳輸,安全性較高。

  • 雲企業網為高安全需求的企業生產環境設計。

配置流程

  1. 為ACR執行個體配置公網端點

    通過配置公網的存取控制策略,來實現遠程安全地管理和訪問ACR企業版執行個體。
  2. 為ACK叢集開啟訪問公網的能力

    為ACK叢集配置訪問外部公網資源能力,從ACR企業版執行個體拉取鏡像。
  1. 為ACR執行個體綁定VPC內網網域名稱解析

    打通ACR企業版執行個體與VPC後,才能在VPC內通過內網網域名稱訪問企業版執行個體。完成配置後需要擷取VPC ID和ACR企業版執行個體內網訪問IP地址。
  2. 擷取ACR執行個體相關網域名稱資訊和IP地址

    擷取訪問ACR企業版執行個體使用的認證服務網域名稱和IP地址、關聯OSS Bucket網域名稱和IP地址。
  3. 建立VPC對等串連並配置路由表

    需要在VPC對等串連的兩端添加指向對端的路由條目以實現ACK叢集綁定的VPC和ACR企業版執行個體綁定的VPC私網互連。ACK叢集綁定的VPC對等串連端還需要配置認證服務IP地址、關聯OSS BucketIP地址的路由條目。
  4. 為ACK叢集解析ACR執行個體網域名稱

    通過添加內網DNS解析節點池自訂資料指令碼批量修改/etc/hosts檔案等方式,為ACK叢集將ACR執行個體網域名稱解析為ACR執行個體內網訪問IP地址,從而通過VPC對等連線路由條目轉寄到ACR執行個體綁定的VPC。
  1. 為ACR執行個體綁定VPC內網網域名稱解析

    打通ACR企業版執行個體與VPC後,才能在VPC內通過內網網域名稱訪問企業版執行個體。完成配置後需要擷取VPC ID和ACR企業版執行個體內網訪問IP地址。
  2. 擷取ACR執行個體相關網域名稱資訊和IP地址

    擷取訪問ACR企業版執行個體使用的認證服務網域名稱和IP地址、關聯OSS Bucket網域名稱和IP地址。
  3. 通過CEN配置跨帳號VPC互連

    將ACR企業版執行個體綁定的VPC串連該帳號地區的轉寄路由器,將ACK叢集綁定的VPC串連該帳號地區的轉寄路由器,然後通過跨地區串連實現兩個地區間的轉寄路由器互連。
  4. 配置VPC和轉寄路由器路由表

    ACK叢集綁定的VPC和轉寄路由器還需要配置認證服務IP地址、關聯OSS BucketIP地址的路由條目。
  5. 為ACK叢集解析ACR執行個體網域名稱

    通過添加內網DNS解析節點池自訂資料指令碼批量修改/etc/hosts檔案等方式,為ACK叢集將ACR執行個體網域名稱解析為ACR執行個體內網訪問IP地址,從而通過CEN路由條目轉寄到ACR執行個體綁定的VPC。

步驟二:配置帳號授權和免密組件

以下是實現跨帳號免密拉取鏡像的三種授權方式,您可以根據情境需求選擇最適合的配置方案。

對比項

使用RRSA

使用Worker RAM角色扮演

使用RAM使用者的AK及SK

叢集類型

支援在1.22及以上版本的ACK託管叢集基礎版ACK託管叢集Pro版ACK Edge叢集ACK Serverless叢集Pro版

支援在1.20及以上版本的ACK託管叢集基礎版ACK託管叢集Pro版、和ACK專有叢集

支援在1.20及以上版本的ACK託管叢集基礎版ACK託管叢集Pro版、和ACK專有叢集

支援組件

  • aliyun-acr-credential-helper託管組件

  • aliyun-acr-credential-helper組件

    需升級到v23.02.06.1-74e2172-aliyun或以上版本。

關於以上組件差異詳情請參見免密組件對比

aliyun-acr-credential-helper組件

aliyun-acr-credential-helper組件

許可權粒度

Pod層級(細粒度)

叢集層級(中粒度)

帳號層級(粗粒度)

安全性

高,提供更精細的許可權控制和隔離,使用STS臨時憑證,無寫入程式碼AK/SK。

中,所有Pod共用許可權,存在過度授權風險。

低,存取金鑰暴露風險較大。

適用情境

適用於安全敏感型業務、需要嚴格許可權管控的生產環境。

適用於統一許可權需求的情境、有一定許可權控制需求的開發與測試環境。

適用於快速部署或者demo環境。

使用RRSA

A使用者帳號的ACK叢集中,配置特定ServiceAccount扮演具有免密拉取鏡像許可權B使用者帳號的RAM角色,使ACK叢集能夠訪問並拉取B使用者帳號的私人鏡像。

說明

啟用免密組件的RRSA功能需先在叢集中啟用RRSA,然後配置免密組件RRSA。若順序錯誤,需刪除免密外掛程式的Pod以啟用RRSA功能。

  1. A使用者帳號下操作,啟用ACK叢集的RRSA功能,並建立支援角色扮演許可權的RAM角色。

    1. 為ACK叢集開啟RRSA功能。

      1. 登入Container Service管理主控台,在左側導覽列選擇叢集列表

      2. 叢集列表頁面,單擊目的地組群名稱,然後在左側導覽列,選擇叢集資訊

      3. 基本資料頁簽的安全與審計地區,單擊RRSA OIDC右側的開啟image

      4. 在彈出的啟用RRSA對話方塊,單擊確定

        基本資料地區,當叢集狀態由更新中變為運行中後,表明該叢集的RRSA特性已變更完成。

      5. 叢集中RRSA功能開啟後,在基本資料頁簽的安全與審計地區,將滑鼠懸浮至RRSA OIDC右側已開啟上面,即可查看供應商的URL連結和ARN資訊。image

    2. 使用指令碼編輯信任策略,建立OIDC身份供應商的RAM角色

      • 將樣本中的<oidc_issuer_url>替換為上一步擷取的當前叢集中OIDC供應商的URL。

      • 將樣本中的<oidc_provider_arn>替換為上一步擷取的當前叢集OIDC供應商的ARN。

      {
        "Statement": [
          {
            "Action": "sts:AssumeRole",
            "Condition": {
              "StringEquals": {
                "oidc:aud": "sts.aliyuncs.com",
                "oidc:iss": "<oidc_issuer_url>",
                "oidc:sub": "system:serviceaccount:kube-system:aliyun-acr-credential-helper"
              }
            },
            "Effect": "Allow",
            "Principal": {
              "Federated": [
                "<oidc_provider_arn>"
              ]
            }
          }
        ],
        "Version": "1"
      }
    3. 為該角色添加AliyunSTSAssumeRoleAccess許可權以授予角色扮演能力,並記錄其ARN資訊。更多詳情,請參見為RAM角色授權

      1. 在角色詳情頁面的許可權管理頁簽下,單擊新增授權

      2. 新增授權面板的權限原則地區,定位並選中AliyunSTSAssumeRoleAccess權限原則,然後單擊確認新增授權

      3. 在角色詳情頁面的基本資料地區,查看並記錄該RAM角色ARN。詳細操作,請參見如何查看RAM角色的ARN?

  2. B使用者帳號下操作,建立RAM角色授予拉取私人鏡像的許可權,並允許A使用者帳號的RAM角色扮演此角色。

    1. 使用指令碼編輯信任策略,建立可信實體為阿里雲帳號的RAM角色,允許A使用者帳號進行角色扮演。

      {
        "Statement": [
          {
            "Action": "sts:AssumeRole",
            "Effect": "Allow",
            "Principal": {
              "RAM": [
                "<A使用者帳號建立角色的ARN>"
              ]
            }
          }
        ],
        "Version": "1"
      }
    2. 使用以下內容建立自訂權限原則,並將該策略為RAM角色授權,以賦予該角色擷取執行個體資訊和拉取鏡像的許可權。

      {
          "Version": "1",
          "Statement": [
              {
                  "Action": [
                      "cr:GetAuthorizationToken",
                      "cr:ListInstanceEndpoint",
                      "cr:PullRepository"
                  ],
                  "Resource": "*",
                  "Effect": "Allow"
              }
          ]
      }
    3. 為其設定RAM角色最大會話時間,設定為3600秒到43200秒之間,預設3600秒。

      建議確保該值與下文修改其配置項中的expireDuration一致,且expireDuration需不超過最大會話時間。
    4. 在角色詳情頁面的基本資料地區,查看並記錄該RAM角色ARN。

  3. A使用者帳號下操作,為ACK叢集安裝免密組件並修改其配置項。

    關於以下組件差異詳情請參見免密組件對比

    aliyun-acr-credential-helper託管組件

    1. 登入Container Service管理主控台,在左側導覽列單擊叢集列表

    2. 叢集列表頁面,單擊目的地組群名稱,然後在左側導覽列,單擊組件管理

    3. 組件管理頁面,選擇安全頁簽,找到aliyun-acr-credential-helper託管卡片,單擊安裝

    4. aliyun-acr-credential-helper參數配置對話方塊,勾選中是否開啟RRSA,然後單擊右側的添加,輸入以下參數,單擊確定

      791184c653f445f62c3387d88ad8bdcf

      關聯ACR企業版執行個體配置:

      參數

      描述

      樣本

      instanceId

      ACR執行個體ID,若要指定多個,以英文半形逗號(,)分隔。

      cri-XXXXX

      regionId

      ACR執行個體所在的RegionID。

      cn-hangzhou

      domains

      ACR執行個體所使用的網域名稱。填入的ACR執行個體的所有訪問網域名稱(公網、VPC)。若要指定個別網域名稱,多個以英文半形逗號(,)分隔。

      XXXXX-registry.cn-hangzhou.cr.aliyuncs.com

      assumeRoleARN

      ACR 執行個體所有者的 RAM 角色 ARN。輸入B使用者帳號下所建立的RAM角色的ARN。

      acs:ram::100XXXXXXXX9630:role/XXXX

      expireDuration

      跨帳號情境下臨時憑證的有效時間。輸入B使用者帳號下所建立的RAM角色的最大會話時間。

      3600

      rrsaRoleARN

      ACK叢集所有者的 RAM 角色 ARN。輸入A使用者帳號下所建立的RAM角色的ARN。

      acs:ram::128XXXXXXXXXX09011:role/XXXX

      rrsaOIDCProviderRoleARN

      ACK叢集的供應商ARN,輸入A使用者帳號下ACK叢集RRSA OIDC的供應商 ARN 資訊

      acs:ram::128XXXXXXXXXX09011:oidc-provider/ack-rrsa-c8864XXXXXXXXXXXXXXXXXX99356a636

      其他參數配置請參見組件配置

    aliyun-acr-credential-helper組件

    1. 登入Container Service管理主控台,在左側導覽列單擊叢集列表

    2. 叢集列表頁面,單擊目的地組群名稱,然後在左側導覽列,單擊組件管理

    3. 組件管理頁面,單擊安全頁簽,定位到aliyun-acr-credential-helper組件並單擊安裝。在彈框中,將tokenMode選項設定為auto,然後單擊確認

      04479cf3d9857845bf530ea2f0850a60

    4. 修改免密組件的ConfigMap配置項。

      1. 在左側導覽列,選擇組態管理 > 配置項

      2. 配置項頁面頂部的命名空間下拉式清單,選擇kube-system,然後單擊acr-configuration操作列下的YAML 編輯,參考下列樣本修改配置。

        data:
          service-account: "default"
          watch-namespace: "all"
          expiring-threshold: "15m"
          notify-email: "c*@example.com"
          acr-registry-info: |
            - instanceId: "cri-xxx"                                   # ACR執行個體ID。
              regionId: "cn-hangzhou"                                 # ACR執行個體地區ID。
              domains: "xxxxx-registry.cn-hangzhou.cr.aliyuncs.com"   # ACR執行個體訪問網域名稱。
              rrsaRoleARN: "<A使用者帳號建立角色的ARN>"
              rrsaOIDCProviderRoleARN: "<A使用者帳號ACK控制台叢集基本資料中的供應商ARN。>"
              assumeRoleARN: "<B使用者帳號建立角色的ARN>"
              expireDuration: 3600                                    # B使用者帳號中的RAM角色設定最大會話時間,預設值為3600。             
          rrsa: |
            enable: true                                              # 免密組件開啟RRSA功能。 

使用Worker RAM角色扮演

A使用者帳號的ACK叢集中,將叢集預設的Worker RAM角色配置為扮演具有免密拉取鏡像許可權的B使用者帳號RAM角色,使ACK叢集可以訪問並拉取B使用者帳號的私人鏡像。

  1. A使用者帳號下操作,查看叢集的Worker RAM角色並授予其角色扮演許可權。

    1. 登入Container Service管理主控台,在左側導覽列選擇叢集列表

    2. 叢集列表頁面,單擊目的地組群名稱,然後在左側導覽列,選擇叢集資訊

    3. 叢集資訊頁面,單擊基本資料頁簽,然後在叢集資源地區,單擊Worker RAM 角色右側連結。

    4. 為該角色添加AliyunSTSAssumeRoleAccess許可權以授予角色扮演能力,並記錄其ARN資訊。更多詳情,請參見為RAM角色授權

      1. 在角色詳情頁面的許可權管理頁簽下,單擊新增授權

      2. 新增授權面板的權限原則地區,定位並選中AliyunSTSAssumeRoleAccess權限原則,然後單擊確認新增授權

      3. 在角色詳情頁面的基本資料地區,查看並記錄該RAM角色ARN。詳細操作,請參見如何查看RAM角色的ARN?

  2. B使用者帳號下操作,建立RAM角色並授予拉取私人鏡像的許可權,並允許A使用者帳號的ACK叢集Worker RAM角色扮演此角色。

    1. 建立可信實體為阿里雲帳號的RAM角色

    2. 使用以下內容建立自訂權限原則,並將該策略為RAM角色授權,以賦予該角色擷取執行個體資訊和拉取鏡像的許可權。

      {
          "Version": "1",
          "Statement": [
              {
                  "Action": [
                      "cr:GetAuthorizationToken",
                      "cr:ListInstanceEndpoint",
                      "cr:PullRepository"
                  ],
                  "Resource": "*",
                  "Effect": "Allow"
              }
          ]
      }
    3. 在RAM角色基本資料頁,單擊信任策略頁簽,使用以下內容編輯信任策略。允許A使用者帳號的ACK叢集的Worker RAM角色來扮演B使用者帳號RAM角色。

      {
        "Statement": [
          {
            "Action": "sts:AssumeRole",
            "Effect": "Allow",
            "Principal": {
              "RAM": [
                "<A使用者建立角色的ARN>"
              ]
            }
          }
        ],
        "Version": "1"
      }
    4. 在角色詳情頁面的基本資料地區,查看並記錄該RAM角色ARN。詳細操作,請參見如何查看RAM角色的ARN?

  3. A使用者帳號下操作,為ACK叢集安裝免密組件並修改其配置項。

    1. 登入Container Service管理主控台,在左側導覽列單擊叢集列表

    2. 叢集列表頁面,單擊目的地組群名稱,然後在左側導覽列,單擊組件管理

    3. 組件管理頁面,單擊安全頁簽,定位到aliyun-acr-credential-helper組件並單擊安裝。在彈框中,將tokenMode選項設定為workerRole,然後單擊確定

      100f8cde3395436575996fbbd290dc56

    4. 修改免密組件的ConfigMap配置項。

      1. 在左側導覽列,選擇組態管理 > 配置項

      2. 配置項頁面頂部的命名空間下拉式清單,選擇kube-system,然後單擊acr-configuration操作列下的YAML 編輯,參考下列樣本修改配置。

        data:
            service-account: "default"
            watch-namespace: "all"
            expiring-threshold: "15m"
            notify-email:"c*@example.com"
            acr-registry-info: |
              - instanceId: "cri-xxx"                                    # ACR企業版執行個體ID。
                regionId: "cn-hangzhou"                                  # ACR企業版地區ID。
                domains: "xxxxx-registry.cn-hangzhou.cr.aliyuncs.com"    # ACR企業版訪問網域名稱。
                assumeRoleARN: "<B使用者帳號建立角色的ARN>"
                expireDuration: 3600                                     # B使用者下,為RAM角色設定最大會話時間,預設值為3600。

使用RAM使用者的AK及SK

A使用者帳號的ACK叢集中,免密組件儲存B使用者帳號RAM使用者的AK和SK以拉取B使用者帳號的私人鏡像。儘管這種方法配置簡單,但由於AK和SK以明文形式儲存,存在泄露的風險。

  1. B使用者帳號下操作,建立一個RAM使用者並確保該RAM使用者擁有cr.*的相關許可權。

    1. 建立RAM使用者

    2. 使用以下內容建立自訂權限原則,並將該策略為RAM使用者授權,授予其擷取執行個體資訊和拉取鏡像的許可權。

      {
          "Version": "1",
          "Statement": [
              {
                  "Action": [
                      "cr:GetAuthorizationToken",
                      "cr:ListInstanceEndpoint",
                      "cr:PullRepository"
                  ],
                  "Resource": "*",
                  "Effect": "Allow"
              }
          ]
      }
    3. 查看RAM使用者的AccessKey資訊並記錄。

  2. A使用者帳號下操作,為ACK叢集安裝免密組件並修改其配置項。

    1. 登入Container Service管理主控台,在左側導覽列單擊叢集列表

    2. 叢集列表頁面,單擊目的地組群名稱,然後在左側導覽列,選擇叢集資訊

    3. 叢集列表頁面,單擊目的地組群名稱,然後在左側導覽列,單擊組件管理

    4. 組件管理頁面,單擊安全頁簽,定位到aliyun-acr-credential-helper組件並單擊安裝。在彈框中,將tokenMode選項設定為auto,然後單擊確認

      04479cf3d9857845bf530ea2f0850a60

    5. 修改免密組件的ConfigMap配置項。

      1. 在左側導覽列,選擇組態管理 > 配置項

      2. 配置項頁面頂部的命名空間下拉式清單,選擇kube-system,然後單擊acr-configuration操作列下的YAML 編輯,參考下列樣本修改配置。

      3. data:
            service-account: "default"
            watch-namespace: "all"
            expiring-threshold: "15m"
            notify-email:"c*@example.com"
            acr-registry-info: |
              - instanceId: ""                        # ACR企業版執行個體ID。             
                regionId: "cn-hangzhou"               # ACR企業版地區ID。    
                customAccessKey: "xxxxx"              # B帳號下RAM使用者的AccessKey ID。
                customAccessKeySecret: "xxxxxx"       # B帳號下RAM使用者的AccessKey Secret。 

步驟三:驗證跨帳號鏡像拉取

說明

驗證過程僅作為樣本。詳細操作,請參見鏡像構建建立工作負載

  1. B使用者帳號的ACR企業版執行個體中,按需擷取容器鏡像的公網地址專用網路地址。

    image

  2. A使用者帳號的ACK叢集中,選擇工作負載 > 無狀態,使用該容器鏡像建立工作負載。

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: nginx-deployment-basic
      labels:
        app: nginx
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: nginx
      template:
        metadata:
          labels:
            app: nginx
        spec:
          containers:
          - name: nginx
            image: ******.cn-hangzhou.cr.aliyuncs.com/instance/instancetest:v1 # 指定B使用者帳號的ACR鏡像地址 
            ports:
            - containerPort: 80
  3. 若工作負載的Pod事件中出現Successfully pulled image "XXX" in XXXs (XXXs including waiting). Image size: XXX bytes.資訊,說明使用免密組件跨帳號拉取鏡像成功。

    ecb56ef14d98a537ebe64f6bd9fd883d

常見問題

如何解決100網段IP衝突問題

在配置路由規則時,認證網域名稱和OSS網域名稱解析的IP地址都屬於100網段。如果您的內網中也使用了該網段的IP,可能會導致訪問Container Registry企業版時與認證網域名稱和OSS網域名稱發生衝突。為了避免這種衝突,您使用以下步驟來解決100網段的衝突問題。

認證網域名稱網段衝突

您可以通過開啟執行個體接管認證網域名稱功能,只需訪問執行個體網域名稱解決認證網域名稱網段衝突問題。

  1. 登入Container Registry控制台

  2. 在頂部功能表列,選擇所需地區。

  3. 執行個體列表頁面單擊目標企業版執行個體。

  4. 在企業版執行個體管理頁面左側導覽列選擇倉庫管理 > 網域名稱管理 ,在網域名稱管理頁面開啟執行個體接管認證網域名稱開關。

    重要

    執行個體接管認證網域名稱功能,您需要提交工單為企業版執行個體添加白名單後才能使用。

  5. 確認開啟執行個體接管認證網域名稱單擊確定

OSS網域名稱網段衝突

您可以通過PrivateLink私網訪問OSS資源,然後將原目標的OSS網域名稱CNAME指向PrivateLink的網域名稱。