すべてのプロダクト
Search
ドキュメントセンター

:コンポーネントを使用したパスワードなしのコンテナイメージプル

最終更新日:Jun 26, 2025

aliyun-acr-credential-helper コンポーネントを使用すると、Container Registry Personal Edition および Enterprise Edition のインスタンスから自己管理型 Kubernetes クラスターに、パスワードなしでプライベートイメージをプルできます。このトピックでは、2 つのシナリオで aliyun-acr-credential-helper を使用してパスワードなしでプライベートイメージをプルする方法について説明します。

前提条件

登録済みクラスターが作成され、外部 Kubernetes クラスターが登録済みクラスターに接続されています。詳細については、「ACK コンソールで登録済みクラスターを作成する」をご参照ください。

使用上の注意

aliyun-acr-credential-helper コンポーネントは、ACK クラスタの kube-system 名前空間にある acr-configuration ConfigMap から構成を読み取り、プライベートイメージをプルします。 aliyun-acr-credential-helper コンポーネントを構成すると、コンポーネントはクラスター内に Secret を生成し、acr-configuration ConfigMap で指定したサービスアカウントに Secret を関連付けます。デフォルトでは、このサービスアカウントを使用するすべてのポッドは、生成された Secret を使用してパスワードなしでイメージをプルします。

重要

Helm チャートなどのアプリケーションをデプロイするためにサービスアカウントを作成する場合、サービスアカウントが aliyun-acr-credential-helper によって生成されたシークレットに関連付けられるまでに一定の時間がかかります。イメージをプルする前に、Webhook 機能を使用してシークレットをサービスアカウントに挿入することをお勧めします。

次の表に、aliyun-acr-credential-helper コンポーネントを使用してパスワードなしでプライベートイメージをプルする場合の制限事項を示します。

パラメーター

説明

ミラーリング

  • 現在の RAM ユーザーが所有する Container Registry インスタンスからプライベートイメージをプルできます。

  • また、権限付与または別の RAM ユーザーの AccessKey ペアを使用して、アカウント間でプライベートイメージをプルすることもできます。

  • Container Registry Enterprise Edition および Container Registry Personal Edition のインスタンスからイメージをプルする必要があるシナリオで、プライベートイメージをプルできます。

クラスターと Kubernetes のバージョン

  • クラスターの Kubernetes バージョンは 1.11.2 以降である必要があります。

  • クラスターの複数の名前空間からパスワードなしでイメージをプルできます。

注意事項

項目

注意事項

imagePullSecrets

  • Deployment などの Kubernetes リソースのテンプレートで imagePullSecret を指定すると、aliyun-acr-credential-helper コンポーネントは無効になります。コンポーネントを使用するには、imagePullSecret を指定しないでください。

  • aliyun-acr-credential-helper コンポーネントは、ACK クラスタのすべての名前空間にあるデフォルトのサービスアカウントの imagePullSecrets フィールドを、新しいシークレットを既存の構成ファイルに追加することで更新します。これらのサービスアカウントは、対応する kube-system 名前空間内の acr-configuration ConfigMap の service-account フィールドの変更に基づいて自動的に変更されます。

ServiceAccount

  • Deployment などの Kubernetes リソースがカスタムサービスアカウントを使用する場合、aliyun-acr-credential-helper コンポーネントの構成ファイルの service-account パラメーターを変更する必要があります。これにより、コンポーネントはカスタムサービスアカウントを使用してイメージをプルする権限を与えられます。

  • クラスターにサービスアカウントを作成した後、imagePullSecrets パラメーターの値に acr-credential で始まるシークレットが含まれているかどうかを確認します。含まれている場合、サービスアカウントはシークレットに関連付けられており、サービスアカウントを使用するアプリケーションはシークレットを使用してイメージをプルできます。認証エラーのため、サービスアカウントの作成直後に、サービスアカウントを使用するアプリケーションがイメージのプルに失敗する場合があります。

リージョン

プルするプライベートイメージが ACK クラスタのリージョンにあるかどうかを確認します。

デフォルトでは、ACK クラスタのリージョンにある Container Registry インスタンスからのみプライベートイメージをプルできます。リージョンをまたいでイメージをプルする場合は、このトピックの「シナリオ 2: リージョンをまたいでイメージをプルする」セクションをご参照ください。

YAML 形式

kube-system 名前空間の acr-configuration ConfigMap を変更する場合は、このトピックの例と同じインデントを使用してください。このトピックで提供されている YAML コンテンツをエディターに貼り付け、対応する値を置き換えてから、構成を適用することをお勧めします。これにより、ConfigMap の形式が有効になります。

自己管理型クラスターで aliyun-acr-credential-helper コンポーネントを構成する

ステップ 1: Aliyun-acr-credential-helper に RAM 権限を付与する

onectl を使用する

  1. オンプレミスマシンに onectl をインストールします。詳細については、「onectl を使用して登録済みクラスターを管理する」をご参照ください。

  2. 次のコマンドを実行して、aliyun-acr-credential-helper に RAM 権限を付与します。

    onectl ram-user grant --addon aliyun-acr-credential-helper

    予期される出力:

    Ram policy ack-one-registered-cluster-policy-aliyun-acr-credential-helper granted to ram user ack-one-user-ce313528c3 successfully.

コンソールを使用する

外部クラスターにコンポーネントをインストールする前に、AccessKey ペアを設定して、外部クラスターに Alibaba Cloud リソースにアクセスするための権限を付与する必要があります。 AccessKey ペアを設定する前に、RAM ユーザーを作成し、Alibaba Cloud リソースにアクセスするための権限を RAM ユーザーに付与します。

  1. RAM ユーザーを作成する

  2. カスタムポリシーを作成する。例:

    {
        "Version": "1",
        "Statement": [
            {
                "Action": [
                    "cr:GetAuthorizationToken",
                    "cr:ListInstanceEndpoint",
                    "cr:PullRepository"
                ],
                "Resource": [
                    "*"
                ],
                "Effect": "Allow"
            }
        ]
    }
  3. カスタムポリシーを RAM ユーザーにアタッチする

  4. RAM ユーザーの AccessKey ペアを作成する

    警告

    AccessKey のセキュリティを強化するために、ネットワークアクセス制御用の AccessKey ペアベースのポリシーを構成し、AccessKey の呼び出し元を信頼できるネットワーク環境に制限することをお勧めします。

  5. AccessKey ペアを使用して、登録済みクラスターに alibaba-addon-secret という名前の Secret を作成します。

    aliyun-acr-credential-helper コンポーネントをインストールすると、システムは AccessKey ペアを自動的に使用してクラウドリソースにアクセスします。

    kubectl -n kube-system create secret generic alibaba-addon-secret --from-literal='access-key-id=<your access key id>' --from-literal='access-key-secret=<your access key secret>'
    説明

    <your access key id><your access key secret> は、前の手順で取得した AccessKey ペアに置き換えます。

ステップ 2: Aliyun-acr-credential-helper を更新して構成する

パスワードなしでイメージをプルするために使用する前に、aliyun-acr-credential-helper をインストールして構成する必要があります。

onectl を使用する

次のコマンドを実行して、aliyun-acr-credential-helper をインストールします。

onectl addon install aliyun-acr-credential-helper

予期される出力:

Addon aliyun-acr-credential-helper, version **** installed.

aliyun-acr-credential-helper がすでにインストールされている場合は、aliyun-acr-credential-helper が最新バージョンであることを確認してください。次のコマンドを実行して、aliyun-acr-credential-helper を最新バージョンに更新できます。

onectl addon upgrade aliyun-acr-credential-helper

予期される出力:

Addon aliyun-acr-credential-helper upgraded to version ****.

コンソールを使用する

aliyun-acr-credential-helper コンポーネントをインストールした場合は、コンポーネントが最新バージョンであることを確認してください。そうでない場合は、コンポーネントを更新します。コンポーネントの更新はビジネスに影響しません。詳細については、「コンポーネントを管理する」をご参照ください。 aliyun-acr-credential-helper コンポーネントの詳細については、「aliyun-acr-credential-helper」をご参照ください。

重要

aliyun-acr-credential-helper コンポーネントが最新バージョンに更新されると、コンポーネントが依存する RAM ロールが変更されます。コンポーネントは、コンポーネントが依存する RAM ロールを指定できるように tokenMode パラメーターを提供します。コンポーネントが依存する RAM ロールの変更による影響の詳細については、「[製品の変更] aliyun-acr-credential-helper が依存する権限を取り消す」をご参照ください。

aliyun-acr-credential-helper コンポーネントが最新バージョンに更新されると、コンポーネントが依存する RAM ロールが変更されます。コンポーネントは、コンポーネントが依存する RAM ロールを指定できるように tokenMode パラメーターを提供します。コンポーネントが依存する RAM ロールの変更による影響の詳細については、「[製品の変更] aliyun-acr-credential-helper が依存する権限を取り消す」をご参照ください。

  1. ACK コンソール にログインします。左側のナビゲーションウィンドウで、[クラスター] をクリックします。

  2. [クラスター] ページで、管理するクラスターを見つけ、その名前をクリックします。左側のウィンドウで、[操作] > [アドオン] を選択します。

  3. [アドオン] ページで、[セキュリティ] タブをクリックし、aliyun-acr-credential-helper を見つけて、[インストール] をクリックします。

  4. [パラメーター] ページで、tokenMode パラメーターにデフォルト値 auto を使用し、[OK] をクリックします。

    ACK マネージドクラスターを最新バージョンに更新した後、aliyun-acr-credential-helper コンポーネントは tokenMode パラメーターを提供します。コンポーネントのインストール後にパラメーターを変更できます。コンポーネントが変更されると、システムはコンポーネントのポッドを再作成します。表に記載されている古いクラスターは、2023 年 4 月 3 日より前に作成されたクラスターを指し、新しいクラスターは、2023 年 4 月 3 日以降に作成されたクラスターを指します。次の表に、tokenMode パラメーターの有効な値を示します。

    tokenMode

    説明

    auto

    managedRole モードを使用するかどうかを自動的に決定します。これがデフォルト値です。システムは、新しいクラスターには managedRole モードを、古いクラスターには workerRole モードを使用します。

    managedRole

    managedRole モードを使用します。

    workerRole

    workerRole モードを使用します。

シナリオ 1: Container Registry Enterprise Edition および Container Registry Personal Edition インスタンスからプライベートイメージをプルする

ACK では、Container Registry Enterprise Edition と Personal Edition から同時に、Container Registry Enterprise Edition から個別に、または Container Registry Personal Edition から個別にプライベートイメージをプルできます。ビジネス要件に基づいて acr-configuration ConfigMap を変更します。詳細については、「コンポーネントを構成する」をご参照ください。例:

  • Enterprise Edition

    apiVersion:v1
    kind:ConfigMap
    metadata:
      name:acr-configuration
      namespace:kube-system
      selfLink:/api/v1/namespaces/kube-system/configmaps/acr-configuration
    data:
      acr-api-version:"2018-12-01"
      acr-registry-info:|-
        -instanceId:"cri-xxx" # コンソールでのデフォルトパラメーターは #-instanceId です。シャープ記号(#) を削除して、このパラメーターを構成する必要があります。
        regionId:"cn-hangzhou"
      expiring-threshold:15m
      service-account:default
      watch-namespace:all
  • Personal Edition

    apiVersion:v1
    kind:ConfigMap
    metadata:
      name:acr-configuration
      namespace:kube-system
      selfLink:/api/v1/namespaces/kube-system/configmaps/acr-configuration
    data:
      acr-api-version:"2018-12-01"
      acr-registry-info:|-
        -instanceId:"" # コンソールでのデフォルトパラメーターは #-instanceId です。シャープ記号(#) を削除して、デフォルト値を保持する必要があります。
         regionId:"cn-hangzhou"
      expiring-threshold:15m
      service-account:default
      watch-namespace:all

次のいずれかの方法を使用して、acr-configuration ConfigMap を構成できます。

コンソールを使用する

  1. ACK コンソール にログインします。左側のナビゲーションウィンドウで、[クラスター] をクリックします。

  2. [クラスター] ページで、管理するクラスターの名前をクリックし、左側のナビゲーションウィンドウで [構成] > [ConfigMap] を選択します。

  3. [ConfigMap] ページの上部にある [名前空間] ドロップダウンリストから kube-system を選択します。次に、acr-configuration ConfigMap を見つけて、パラメーターを構成します。

    acr-configuration ConfigMap が存在しない場合は、ConfigMap を作成します。詳細については、「ConfigMap を作成する」をご参照ください。 ConfigMap の更新方法については、「ConfigMap を管理する」をご参照ください。

    • [操作] 列の [編集] をクリックして、ConfigMap のキーと値を構成します。

    • [操作] 列の [YAML を編集] をクリックして、ConfigMap のキーと値を構成します。

kubectl を使用する

  1. 次のコマンドを実行して、acr-configuration ConfigMap の編集ページに移動します。

    kubectl edit cm acr-configuration -n kube-system
  2. 要件に基づいて、acr-configuration ConfigMap のパラメーターを構成します。

シナリオ 2: リージョンをまたいでイメージをプルする

Container Registry インスタンスから登録済みクラスターにイメージをプルする場合、Container Registry インスタンスと登録済みクラスターが異なるリージョンにデプロイされている場合は、acr-configuration ConfigMap を変更する必要があります。

たとえば、中国 (北京) リージョンと中国 (杭州) リージョンにデプロイされている Container Registry インスタンスから同時にイメージをプルする場合は、次のコードブロックに基づいて acr-configuration ConfigMap を変更します。詳細については、「コンポーネントを構成する」をご参照ください。

data:
    service-account: "default"
    watch-namespace: "all"
    expiring-threshold: "15m"
    notify-email: "**@aliyuncs.com"
    acr-registry-info: |
      - instanceId: ""
        regionId: cn-beijing
      - instanceId: ""
        regionId: cn-hangzhou            

次のいずれかの方法を使用して、acr-configuration ConfigMap を構成できます。

コンソールを使用する

  1. ACK コンソール にログインします。左側のナビゲーションウィンドウで、[クラスター] をクリックします。

  2. [クラスター] ページで、管理するクラスターの名前をクリックし、左側のナビゲーションウィンドウで [構成] [>] ConfigMap を選択します。

  3. [ConfigMap] ページの上部にある [名前空間] ドロップダウンリストから kube-system を選択します。次に、acr-configuration ConfigMap を見つけて、パラメーターを構成します。

    acr-configuration ConfigMap が存在しない場合は、ConfigMap を作成します。詳細については、「ConfigMap を作成する」をご参照ください。 ConfigMap の更新方法については、「ConfigMap を管理する」をご参照ください。

    • [操作] 列の [編集] をクリックして、ConfigMap のキーと値を構成します。

    • [操作] 列の [YAML を編集] をクリックして、ConfigMap のキーと値を構成します。

kubectl を使用する

  1. 次のコマンドを実行して、acr-configuration ConfigMap の編集ページに移動します。

    kubectl edit cm acr-configuration -n kube-system
  2. 要件に基づいて、acr-configuration ConfigMap のパラメーターを構成します。