デフォルトのイメージ・プル・シークレットのセットアップ

一般に、IBM Cloud Kubernetes Service クラスターは、icr.io Kubernetes 名前空間内のすべての、IBM Cloud Container Registry default ドメインからのみ、イメージをプルできるようにセットアップされます。 他の Kubernetes ネームスペースまたはアカウントからイメージをプルする方法、プルアクセスを制限する方法、またはクラスタにデフォルトのイメージプルシークレットがない理由について、さらに詳しく知りたい場合は、以下のFAQを参照してください。

default Kubernetes 名前空間からイメージをプルするようにクラスタを設定するにはどうすればよいですか？

クラスターを作成すると、そのクラスターの IBM Cloud IAM サービス ID に、IBM Cloud Container Registry に対するリーダーの IAM サービス・アクセス役割ポリシーが与えられます。 このサービス ID の資格情報が擬人化され、有効期限のない API キーの中に含められ、API キーがクラスターのイメージ・プル・シークレットに保管されます。 そのイメージ・プル・シークレットが、Kubernetes 名前空間 default に追加され、その Kubernetes 名前空間の default サービス・アカウントのシークレットのリストに含められます。 イメージ・プル・シークレットを使用することで、デプロイメントはグローバルおよびリージョンの IBM Cloud Container Registry からイメージをプル (読み取り専用アクセス) して、コンテナーを Kubernetes の default 名前空間にデプロイできます。

• グローバル・レジストリーには、IBM 提供のパブリック・イメージが安全に保管されています。 各リージョン・レジストリーに保管されたイメージを別々に参照することなく、すべてのデプロイメントでこれらのパブリック・イメージを参照できます。
• リージョンレジストリーには、独自のプライベート Docker イメージが安全に保管されます。

default Kubernetes ネームスペースにイメージプル用の秘密がない場合はどうすればよいですか？

クラスターにログインし、kubectl get secrets -n default | grep "icr-io" を実行してイメージ・プル・シークレットを確認できます。　 icr シークレットがリストされない場合は、クラスターを作成したユーザーが、IAM で IBM Cloud Container Registry に対する必要な許可を持っていなかった可能性があります。 API キーのイメージ・プル・シークレットを使用するように既存のクラスターを更新するを参照してください。

特定の地域レジストリへのプルアクセスを制限することはできますか？

はい。サービス ID の既存の IAM ポリシーを編集して、リーダーのサービス・アクセス役割をそのリージョン・レジストリーまたはレジストリー・リソース (名前空間など) に制限できます。 レジストリーの IAM ポリシーをカスタマイズする前に IBM Cloud で IBM Cloud Container Registry IAM ポリシーを有効にしておく必要があります。

レジストリー資格情報の安全性をさらに高めたいですか? クラスター内の Kubernetes シークレット (レジストリー資格情報を保管するイメージ・プル・シークレットなど) を暗号化するために、クラスターで鍵管理サービス・プロバイダーを有効にするようにクラスター管理者に依頼してください。

Kubernetes のネームスペースで、 default 以外の画像を呼び出すことはできますか？

デフォルトではできません。 デフォルトのクラスター・セットアップを使用することで、IBM Cloud Container Registry 名前空間内に保管されている任意のイメージからのコンテナーを、クラスターの default Kubernetes 名前空間にデプロイできます。 これらのイメージを他の Kubernetes 名前空間や他の IBM Cloud アカウントで使用するためには、イメージ・プル・シークレットをコピーするか作成します。

IBM Cloud の別のアカウントから画像を引っ張ってくることはできますか？

はい。使用する IBM Cloud アカウントで API キーを作成してください。 次に、その IBM Cloud アカウントからイメージをプルする各クラスターの名前空間ごとに、API キーを入れたシークレットを作成します。 詳しくは、許可されたサービス ID の API キーを使用するこちらの例の手順に従ってください。

Docker などの非 IBM Cloud レジストリーを使用する場合は、他のプライベート・レジストリーに格納されたイメージへのアクセスを参照してください。

APIキーはサービスID用のものである必要がありますか？ アカウントのサービスIDの上限に達した場合、どうなりますか？

デフォルトのクラスター・セットアップでは、IBM Cloud IAM API キー資格情報をイメージ・プル・シークレットに保管するためのサービス ID が作成されます。 ただし、個別ユーザー用の API キーを作成して、それらの資格情報をイメージ・プル・シークレットに保管することもできます。 サービス ID の IAM 制限 に到達した場合、クラスターはサービス ID とイメージ・プル・シークレットなしで作成され、デフォルトでは icr.io レジストリー・ドメインからイメージをプルできません。 独自のイメージ・プル・シークレットを作成する必要がありますが、そのためには、IBM Cloud IAM サービス ID ではなく、部門 ID などの個別ユーザー用の API キーを使用します。

地域レジストリドメインとすべてのレジストリドメインのイメージプルに関する秘密事項を確認します。 どれを使えばいいの？

以前は、IBM Cloud Kubernetes Service によって、リージョンのパブリック icr.io レジストリー・ドメインごとに別々のイメージ・プル・シークレットが作成されていました。 現在は、すべてのリージョンのパブリックとプライベートのすべての icr.io レジストリー・ドメインが、クラスターの all-icr-io Kubernetes 名前空間に自動的に作成される単一の default イメージ・プル・シークレットに保管されます。

クラスターの他の Kubernetes 名前空間のワークロードでプライベート・レジストリーからコンテナー・イメージをプルする場合に、all-icr-io イメージ・プル・シークレットをその Kubernetes 名前空間にコピーするだけで済むようになりました。 その後、サービス・アカウントまたはデプロイメントに all-icr-io シークレットを指定します。 イメージのリージョン別レジストリーと一致するイメージ・プル・シークレットをコピーする必要がなくなりました。 また、認証を必要としないパブリック・レジストリーのイメージ・プル・シークレットは必要ないことに注意してください。

Kubernetes の別の名前空間で画像プル秘密をコピーまたは作成したら、完了ですか？

十分ではありません。 コンテナーが、作成したシークレットを使用してイメージをプルすることを許可されている必要があります。 イメージ・プル・シークレットを名前空間のサービス・アカウントに追加することも、各デプロイメントでシークレットを参照することもできます。 手順については、イメージ・プル・シークレットを使用したコンテナーのデプロイを参照してください。

icr.io レジストリーへのプライベート・ネットワーク接続

サービス・エンドポイントを使用するように IBM Cloud アカウントをセットアップすると、IBM Cloud Container Registry との間で行うイメージのプッシュとプルにプライベート・ネットワーク接続を使用できます。

icr.io レジストリへのプライベート接続を使用するクラスタを設定するには、何が必要ですか？

1. IBM Cloud インフラストラクチャアカウントで 仮想ルーター機能（VRF） を有効にすると、 IBM Cloud Container Registry プライベートクラウドサービスエンドポイントを使用できるようになります。 VRF を有効にするには、VRF の有効化を参照してください。 VRF が既に有効になっているかどうかを確認するには、ibmcloud account show コマンドを使用します。
2. IBM Cloud アカウントでサービス・エンドポイントを使用できるようにします。

IBM Cloud Container Registry 自動的にプライベートクラウドサービスのエンドポイントを使用します。 IBM Cloud Kubernetes Service クラスターのプライベート・クラウド・サービス・エンドポイントを有効にする必要はありません。

イメージ・プル・シークレットの更新

Kubernetes の default 名前空間にあるクラスターのイメージ・プル・シークレットを更新するには、以下のようにします。

1. クラスター ID を取得します。

   ibmcloud ks cluster ls
   

2. クラスターのサービス ID を作成し、そのサービス ID に IBM Cloud Container Registry に対するリーダーの IAM サービス・アクセス役割を割り当てるために、以下のコマンドを実行します。 また、このコマンドは、サービス ID の資格情報を擬人化する API キーを作成し、クラスター内の Kubernetes イメージ・プル・シークレットに保管します。 このイメージ・プル・シークレットは、Kubernetes 名前空間 default にあります。

   ibmcloud ks cluster pull-secret apply --cluster <cluster_name_or_ID>
   

   このコマンドを実行すると、IAM 資格情報とイメージ・プル・シークレットの作成が開始されます。これが完了するまで、しばらく時間がかかる場合があります。 イメージ・プル・シークレットが作成されるまでは、IBM Cloud Container Registry icr.io ドメインからイメージをプルするコンテナーをデプロイできません。

3. クラスター内にイメージ・プル・シークレットが作成されていることを確認します。

   kubectl get secrets | grep icr-io
   

   出力例

   all-icr-io           kubernetes.io/dockerconfigjson        1         16d
   

4. ドメイン名からイメージをプルするようコンテナー・デプロイメントicr.ioを更新します。

5. オプション: ファイアウォールがある場合は、使用するドメインでレジストリー・サブネットへのアウトバウンド・ネットワーク・トラフィックを許可してください。

6. 以下のいずれかのオプションを使用して、セットアップを完了します。

   • default 以外の Kubernetes 名前空間にイメージをプルしたり、他の IBM Cloud アカウントからイメージをプルしたりする場合は、別のイメージ・プル・シークレットをコピーまたは作成します。
   • イメージ・プル・シークレットのアクセスを特定のレジストリー・リソース (名前空間やリージョンなど) に制限する場合は、以下のようにします。
     1. IBM Cloud に対する IBM Cloud Container Registry IAM ポリシーが有効になっていることを確認します。
     2. サービス ID の IBM Cloud IAM ポリシーを編集するか、別のイメージ・プル・シークレットを作成します。

既存のイメージ・プル・シークレットのコピー

イメージ・プル・シークレットをクラスター内の他の名前空間にコピーできます (default Kubernetes 名前空間用に自動的に作成されたイメージ・プル・シークレットなど)。 例えば、特定の名前空間へのアクセスを制限するために、または他の IBM Cloud アカウントからイメージをプルするために、この名前空間で別の IBM Cloud IAM API キー資格情報を使用する必要がある場合は、代わりに、イメージ・プル・シークレットを作成します。

1. クラスター内に存在する Kubernetes 名前空間をリストするか、使用する名前空間を作成します。

   kubectl get namespaces
   

   出力例

   default          Active    79d
   ibm-cert-store   Active    79d
   ibm-system       Active    79d
   kube-public      Active    79d
   kube-system      Active    79d
   

   名前空間を作成する

   kubectl create namespace <namespace_name>
   

2. IBM Cloud Container Registry の Kubernetes 名前空間 default にある既存のイメージ・プル・シークレットをリストします。

   kubectl get secrets -n default | grep icr-io
   

   出力例

   all-icr-io          kubernetes.io/dockerconfigjson        1         16d
   

3. all-icr-io イメージ・プル・シークレットを default 名前空間から任意の名前空間にコピーします。 新しいイメージ・プル・シークレットの名前は <namespace_name>-icr-<region>-io です。

   kubectl get secret all-icr-io -n default -o yaml | sed 's/default/<new-namespace>/g' | kubectl create -n <new-namespace> -f -   
   

4. シークレットが正常に作成されたことを確認します。

   kubectl get secrets -n <namespace_name> | grep icr-io
   

5. コンテナーをデプロイするために、各デプロイメントにイメージ・プル・シークレットを追加します。または、名前空間のサービス・アカウントにイメージ・プル・シークレットを追加して、その名前空間のすべてのデプロイメントでレジストリーからイメージをプルできるようにします。

異なる IAM API キー資格情報を使用したイメージ・プル・シークレットの作成

IBM Cloud の IAM アクセス・ポリシーをユーザーまたはサービス ID に割り当てて、特定のレジストリー・イメージ名前空間または操作 (push や pull など) にアクセス権を制限できます。 次に、API キーを作成して、これらのレジストリー資格情報をクラスターのイメージ・プル・シークレットに保管します。

例えば、他の IBM Cloud アカウント内のイメージにアクセスするには、そのアカウント内のユーザーまたはサービス ID の IBM Cloud Container Registry 資格情報を保管する API キーを作成します。 次に、クラスターのアカウント内で、それぞれのクラスターとクラスター名前空間のイメージ・プル・シークレットにその API キー資格情報を保存します。

以下のステップでは、IBM Cloud の IAM サービス ID の資格情報を保管する API キーを作成します。 サービス ID を使用する代わりに、IBM Cloud に対する IBM Cloud Container Registry IAM サービス・アクセス・ポリシーを割り当てたユーザー ID の API キーを作成することもできます。 ただし、そのユーザー ID は部門 ID にしてください。あるいは、その特定のユーザーがいなくなってもクラスターがレジストリーにアクセスできるように計画しておいてください。

1. クラスター内に存在する Kubernetes 名前空間をリストするか、レジストリー・イメージからコンテナーをデプロイする場所として使用する名前空間を作成します。

   kubectl get namespaces
   

   出力例

   default          Active    79d
   ibm-cert-store   Active    79d
   ibm-system       Active    79d
   kube-public      Active    79d
   kube-system      Active    79d
   

   名前空間を作成する

   kubectl create namespace <namespace_name>
   

2. イメージ・プル・シークレットの IAM ポリシーと API キー資格情報のために使用するクラスターの IBM Cloud IAM サービス ID を作成します。 サービス ID には、後からサービス ID を特定できるように、必ず説明を付けておいてください。例えば、クラスター名と名前空間名の両方を記載してください。

   ibmcloud iam service-id-create <cluster_name>-<namespace>-id --description "Service ID for IBM Cloud Container Registry in Kubernetes cluster <cluster_name> namespace <namespace>"
   

3. IBM Cloud へのアクセス権を与えるカスタム IBM Cloud Container Registry IAM ポリシーを、クラスター・サービス ID に対して作成します。

   ibmcloud iam service-policy-create <cluster_service_ID> --roles <service_access_role> --service-name container-registry [--region <IAM_region>] [--resource-type namespace --resource <registry_namespace>]
   

   cluster_service_ID

   必須。 Kubernetes クラスター用に以前に作成した <cluster_name>-<kube_namespace>-id サービス ID に置き換えます。

   --service-name container-registry

   必須。 container-registry を入力して、IAM ポリシーの対象を IBM Cloud Container Registry にします。

   --roles <service_access_role>

   必須。 サービス ID のアクセス権限の範囲にする IBM Cloud Container Registry に対するサービス・アクセス役割を入力します。 指定できる値は、Reader、Writer、Manager です。

   --region <IAM_region>

   オプション。 アクセス・ポリシーの有効範囲を特定の IAM リージョンに制限する場合は、コンマ区切りリスト形式でリージョンを入力します。 指定可能な値は global およびローカル・レジストリーのリージョンです。

   --resource-type namespace --resource <registry_namespace>

   オプション。 特定の IBM Cloud Container Registry 名前空間 内のイメージのみにアクセスを制限する場合は、リソース・タイプとして namespace を入力し、<registry_namespace> を指定します。 レジストリーの名前空間をリストするには、ibmcloud cr namespaces を実行します。

4. サービス ID の API キーを作成します。 APIキーにサービスIDと同様の名前を付け、以前に作成したサービスIDを含めます <cluster_name>-<kube_namespace>-id. 必ず、後でキーを思い出せるように説明を付けてください。

   ibmcloud iam service-api-key-create <cluster_name>-<namespace>-key <cluster_name>-<namespace>-id --description "API key for service ID <service_id> in Kubernetes cluster <cluster_name> namespace <namespace>"
   

5. 前のコマンドの出力から API キーの値を取得します。

   Please preserve the API key! It can't be retrieved after it's created.
   
   Name          <cluster_name>-<kube_namespace>-key   
   Description   key_for_registry_for_serviceid_for_kubernetes_cluster_multizone_namespace_test   
   Bound To      crn:v1:bluemix:public:iam-identity::a/1bb222bb2b33333ddd3d3333ee4ee444::serviceid:ServiceId-ff55555f-5fff-6666-g6g6-777777h7h7hh   
   Created At    2019-02-01T19:06+0000   
   API Key       i-8i88ii8jjjj9jjj99kkkkkkkkk_k9-llllll11mmm1   
   Locked        false   
   UUID          ApiKey-222nn2n2-o3o3-3o3o-4p44-oo444o44o4o4   
   

6. クラスター名前空間に API キーの資格情報を保管するためのイメージ・プル・シークレットを作成します。 各クラスターの各名前空間で、イメージをプルする icr.io ドメインごとに、この手順を繰り返します。

   kubectl --namespace <namespace> create secret docker-registry <secret_name> --docker-server=<registry_URL> --docker-username=iamapikey --docker-password=<api_key_value> --docker-email=<docker_email>
   

   --namespace <namespace>

   必須。 サービス ID 名に使用したクラスターの Kubernetes 名前空間を指定します。

   <secret_name>

   必須。 イメージ・プル・シークレットの名前を入力します。

   --docker-server <registry_URL>

   必須。 レジストリーの名前空間がセットアップされているイメージ・レジストリーの URL を設定します。 使用可能なドメインについては、ローカルのリージョンを参照してください。

   --docker-username iamapikey

   必須。 プライベート・レジストリーにログインするためのユーザー名を入力します。 IBM Cloud Container Registry を使用する場合は、iamapikey を入力します。

   --docker-password <token_value>

   必須。 前に取得した API Keyの値を入力します。

   --docker-email <docker-email>

   必須。 Docker E メール・アドレスがある場合は、その値を入力します。 ない場合は、a@b.c のような架空の E メール・アドレスを入力します。 この E メールは、Kubernetes シークレットの作成には必要ですが、作成後は使用されません。

7. シークレットが正常に作成されたことを確認します。 <namespace> を、イメージ・プル・シークレットを作成した namespace に置き換えます。

   kubectl get secrets --namespace <namespace>
   

8. コンテナーをデプロイする際に、名前空間内の任意のポッドでそのイメージ・プル・シークレットを使用できるよう、イメージ・プル・シークレットを Kubernetes サービス・アカウントに追加します。

他のプライベート・レジストリー内に保管されているイメージへのアクセス

プライベート・レジストリーが既にある場合は、そのレジストリーの資格情報を Kubernetes イメージ・プル・シークレットに保管し、構成ファイルからそのシークレットを参照する必要があります。

始める前に

1. クラスターを作成します。
2. アカウントにログインします。 該当する場合は、適切なリソース・グループをターゲットにします。 クラスターのコンテキストを設定します。

イメージ・プル・シークレットを作成するには、以下のようにします。

1. プライベート・レジストリーの資格情報を保管する Kubernetes シークレットを作成します。

   kubectl --namespace <namespace> create secret docker-registry <secret_name>  --docker-server=<registry_URL> --docker-username=<docker_username> --docker-password=<docker_password> --docker-email=<docker_email>
   

   --namespace <namespace>

   必須。 シークレットを使用してコンテナーをデプロイする、クラスターの Kubernetes 名前空間。 クラスター内に存在する名前空間をリストするには、kubectl get namespaces を実行します。

   <secret_name>

   必須。 イメージ・プル・シークレットに使用する名前。

   --docker-server <registry_URL>

   必須。 プライベート・イメージが保管されているレジストリーの URL。

   --docker-username <docker_username>

   必須。 プライベート・レジストリーにログインするためのユーザー名。

   --docker-password <token_value>

   必須。 プライベート・レジストリーにログインするためのパスワード (トークン値など)。

   --docker-email <docker-email>

   必須。 Docker E メール・アドレスがある場合は、その値を入力します。 ない場合は、a@b.c などの架空の E メール・アドレスを入力します。 この E メールは、Kubernetes シークレットの作成には必要ですが、作成後は使用されません。

2. シークレットが正常に作成されたことを確認します。 <namespace> を、イメージ・プル・シークレットを作成した名前空間の名前で置き換えます。

   kubectl get secrets --namespace <namespace>
   

3. イメージ・プル・シークレットを参照するポッドを作成します。

選択した名前空間の Kubernetes サービス・アカウントにイメージ・プル・シークレットを保管する

すべての Kubernetes 名前空間に、default という名前の Kubernetes サービス・アカウントがあります。 名前空間内で、イメージ・プル・シークレットをこのサービス・アカウントに追加すると、レジストリーからイメージをプルするためのアクセス権限をポッドに付与できます。 サービス・アカウントを指定しないデプロイメントでは、この Kubernetes 名前空間の default サービス・アカウントが自動的に使用されます。

1. default サービス・アカウントにイメージ・プル・シークレットが既に存在しているかどうかを確認します。

   kubectl describe serviceaccount default -n <namespace_name>
   

   <none> が イメージ・プル・シークレット エントリーに表示される場合、イメージ・プル・シークレットは存在しません。

2. イメージ・プル・シークレットを default サービス・アカウントに追加します。

   • イメージ・プル・シークレットが定義されていない場合に、イメージ・プル・シークレットを追加するコマンドの例。

     kubectl patch -n <namespace_name> serviceaccount/default -p '{"imagePullSecrets":[{"name": "<image_pull_secret_name>"}]}'
     

   • イメージ・プル・シークレットが既に定義されている場合に、イメージ・プル・シークレットを追加するコマンドの例。

     kubectl patch -n <namespace_name> serviceaccount/default --type='json' -p='[{"op":"add","path":"/imagePullSecrets/-","value":{"name":"<image_pull_secret_name>"}}]'
     

3. イメージ・プル・シークレットが default サービス・アカウントに追加されたことを確認します。

   kubectl describe serviceaccount default -n <namespace_name>
   

   出力例

   Name:                default
   Namespace:           <namespace_name>
   Labels:              <none>
   Annotations:         <none>
   Image pull secrets:  <image_pull_secret_name>
   Mountable secrets:   default-token-sh2dx
   Tokens:              default-token-sh2dx
   Events:              <none>
   

   イメージ・プル・シークレットで <secret> (not found) が示される場合は、kubectl get secrets -n namespace を実行して、サービス・アカウントと同じ名前空間にイメージ・プル・シークレットが存在することを確認します。

4. レジストリー内のmypod.yamlイメージからコンテナーをデプロイするために、 という名前のポッド構成ファイルを作成します。

   apiVersion: v1
   kind: Pod
   metadata:
     name: mypod
   spec:
     containers:
       - name: mypod-container
         image: <region>.icr.io/<namespace>/<image>:<tag>
   

5. mypod.yaml 構成ファイルを適用して、クラスターにポッドを作成します。

   kubectl apply -f mypod.yaml
   

containerd カスタム・レジストリー構成を更新する daemonset の例

YAML ファイルの例を使用して、すべてのワーカー・ノードで実行されるデーモン・セットを定義し、containerd レジストリー・ホスト構成を設定または更新し、対応する containerd レジストリー・パスにマウントします。

この例では、dockerhub の以下のレジストリー・ホスト構成を設定します。 このレジストリー・ホスト構成は既に提供されており、ワーカー・プロビジョニング・フェーズ中に自動的に構成されます。 init コンテナは、デプロイ後、およびワーカーノードのリロードまたは再起動後に、すべてのワーカーノード上で hosts.toml を初期化します。

server = "https://docker.io"
[host."https://registry-1.docker.io"]
capabilities = ["pull", "resolve"]

YAML ファイルの例:

apiVersion: apps/v1
kind: DaemonSet
metadata:
labels:
    name: containerd-dockerhub-registry-config
name: containerd-dockerhub-registry-config
namespace: kube-system
spec:
selector:
    matchLabels:
    name: containerd-dockerhub-registry-config
template:
    metadata:
    labels:
        name: containerd-dockerhub-registry-config
    spec:
    initContainers:
    - image: alpine:3.13.6
        name: containerd-dockerhub-registry-config
        command:
        - /bin/sh
        - -c
        - |
            #!/bin/sh
            set -uo pipefail
            cat << EOF > /etc/containerd/certs.d/docker.io/hosts.toml
            server = "https://docker.io"
            [host."https://registry-1.docker.io"]
            capabilities = ["pull", "resolve"]
            EOF
        volumeMounts:
        - mountPath: /etc/containerd/certs.d/docker.io/
        name: dockerhub-registry-config
    containers:
    - name: pause
        image: "us.icr.io/armada-master/pause:3.5"
        imagePullPolicy: IfNotPresent
    volumes:
    - name: dockerhub-registry-config
        hostPath:
        path: /etc/containerd/certs.d/docker.io/

containerd レジストリー・ホスト構成の更新について詳しくは、 containerd の資料を参照してください。