k3sや Rancher Desktopなどのローカルkubernetesクラスタ上で、プライベートレジストリのコンテナイメージを起動させるためには、イメージpull時の認証設定が必要です。
認証は以下の2段階でセットアップできます。
- docker-registryの Secretを作成
- serviceaccountから認証用secretを参照
準備：認証アカウントを取得
あらかじめ、プライベートレジストリ側で外部クラスタがアクセスするためのアカウントを作成しておきます。
たとえばGoogle Artifact Registryの場合、サービスアカウントを作成し、JSON形式のクレデンシャルファイルを取得しておきます。
コンテナ起動向けのプリセットロールはroles/artifactregistry.reader(Artifact Registry読み取り)が適しているでしょう。
docker-registryのsecretを作成
ローカルクラスタへの認証情報登録は、
kubectl create secret docker-registryという長いコマンドで実行できます。
Google Artifact Registryの設定例は以下のような書式になります。
--docker-serverオプションの制約上、複数のプライベートレジストリにアクセスする際にはそれぞれクレデンシャルのセットアップが必要です。
$ kubectl create secret docker-registry gcr-credential \
--docker-server=<REGION-docker.pkg.dev> \
--docker-username=_json_key \
--docker-email=<[email protected]> \
--docker-password="$(cat credential.json)"
オプションの概要は以下のとおりです。フィールドに入力すべき値はレジストリのサービスごとに異なります。
- docker-server: プライベートレジストリのドメイン。Artifact Registryはリポジトリのロケーションに応じてサブドメインが異なる
- docker-username: プライベートレジストリのID。GCRはJSONクレデンシャルを参照するため
_json_keyという固定値とのこと - docker-email: GCRの場合、サービスアカウントのメールアドレス
- docker-password: プライベートレジストリのパスワード。GoogleCloudの場合、JSONクレデンシャルの文字列を全投入するためファイルをcatした出力を登録
登録が成功していれば、kubectl describe secret gcr-credentialで確認でき、Data部に.dockercfgというキーでデータを保持している様子が観察できます（中身は非表示）。
旧GoogleContainerRegistryの場合
旧サービスのgcr.io(2025年に廃止)は、バックエンドにGCSを利用しています。
アクセス権限は、対応するGCSのバケット(artifacts.<PROJECT-ID>.appspot.comなど)に設定しておきます。詳細は
Container Registryのドキュメントを参照してください。
また、kubectl create secret docker-registryの--docker-serverオプションもgcr.ioドメインを指定します。
ServiceAccountから認証用secretを参照
kubectl patchコマンドでローカルクラスタのserviceaccountを更新します。
ServiceAccountはネームスペースごとに作成されるオブジェクトであることに注意が必要です。
$ kubectl patch serviceaccount default -p '{"imagePullSecrets": [{"name": "gcr-credential"}]}'
### 確認
$ kubectl get sa default -o yaml
imagePullSecretsはArray型なので、複数のsecretを登録可能です。
エディタで編集したい場合にはkubectl edit serviceaccount defaultコマンドも利用できます。
Pod起動時の設定ファイルにアカウント指定
複数のレジストリを利用している場合など、個別のPodにsecretを設定したい場合、 Create a Pod that uses your Secretのような設定も可能です。
マニフェストPod SpecのimagePullSecrets.nameに指定します。
まとめ
kubernetesのプライベートレジストリアクセスにはdocker-registry secretの登録が必要です。
MacOS上のminikubeなどは、minikube VM上で動作しているためホスト（MacOS）のdocker / kubernetesの認証設定にはアクセスできません。
Chuma Takahiro
関連記事
