このガイドでは、Artifact Registry からイメージを pull して Google Kubernetes Engine にデプロイする方法について説明します。自己ホスト型またはサードパーティの Kubernetes サービスにデプロイする場合は、Artifact Registry からイメージを pull する前に、 Google Cloud への認証を構成する必要があります。 Google Cloudの外部にある Kubernetes ワークロードから Google Cloud に認証を行うには、Kubernetes で Workload Identity 連携を構成するをご覧ください。
Google Kubernetes Engine は、Docker リポジトリから直接イメージを pull できます。一部のバージョンには、Artifact Registry Docker リポジトリからイメージを pull するための事前構成済みのサポートが含まれています。
要件
このセクションでは、GKE と統合するための要件について説明します。
権限
GKE は、ノードプールまたはクラスタを作成する際に次のデフォルトを使用します。
- Compute Engine のデフォルトのサービス アカウントがノードの ID となっています。
-
組織のポリシーの構成によっては、デフォルトのサービス アカウントにプロジェクトに対する編集者のロールが自動的に付与される場合があります。
iam.automaticIamGrantsForDefaultServiceAccounts
組織ポリシー制約を適用して、自動的なロール付与を無効にすることを強くおすすめします。2024 年 5 月 3 日以降に組織を作成した場合、この制約はデフォルトで適用されます。自動ロール付与を無効にする場合、デフォルトのサービス アカウントに付与するロールを決定し、これらのロールを付与する必要があります。
デフォルトのサービス アカウントにすでに編集者ロールが設定されている場合は、編集者ロールを権限の低いロールに置き換えることをおすすめします。サービス アカウントのロールを安全に変更するには、Policy Simulator を使用して変更の影響を確認してから、適切なロールを付与または取り消す操作を行います。
- デフォルトのサービス アカウントで作成したノードには、Compute Engine のデフォルトのアクセス スコープ(ストレージへの読み取り専用アクセス権を含む)が設定されています。既存のノードではアクセス スコープを変更できません。
基本編集者ロールの付与を無効にしている場合は、Compute Engine のデフォルトのサービス アカウントに Artifact Registry の読み取りロール(roles/artifactregistry.reader
)を付与します。
これらのデフォルトを使用し、Compute Engine のデフォルトのサービス アカウントに Artifact Registry 読み取りロール(roles/artifactregistry.reader
)を付与すると、GKE は同じ Google Cloud プロジェクトの Artifact Registry リポジトリからイメージを pull できます。ノードからイメージを push する場合、プロジェクト間でイメージを pull または push する場合、ユーザー指定のサービス アカウントを使用する場合、またはデフォルト設定でサポートされていない他の要件がある場合は、アクセスの構成についてアクセス制御のドキュメントをご覧ください。
「permission denied」エラーが発生した場合は、4xx エラーをご覧ください。
GKE バージョン
次の表に、同じプロジェクトの Docker リポジトリからコンテナを pull するためのデフォルト権限を持つクラスタを作成するために必要な GKE バージョンの最小要件を示します。
バージョン | 必要最小限のパッチ |
---|---|
1.14 | 1.14.10-gke.22 |
1.15 | 1.15.9-gke.8 |
GKE のバージョンが最小バージョンより前のものである場合は、GKE がイメージを pull できるように Kubernetes imagePullSecrets を構成する必要があります。
GKE が Artifact Registry とは異なるプロジェクトにある場合は、GKE ノードが使用するサービス アカウントに Artifact Registry 権限を付与します。デフォルトでは、ノードは Compute Engine のデフォルトのサービス アカウントを使用します。
イメージを実行する
次のコマンドを使用して、Google Kubernetes Engine クラスタで Artifact Registry イメージを実行できます。
kubectl run [NAME] --image=LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
ここで
-
LOCATION
は、リポジトリのリージョンまたはマルチリージョンのロケーションです。 PROJECT
は、 Google Cloud コンソールのプロジェクト ID です。プロジェクト ID にコロン(:
)が含まれている場合は、ドメインをスコープとするプロジェクトをご覧ください。REPOSITORY
は、イメージが保存されるリポジトリの名前です。IMAGE
は、リポジトリ内のイメージの名前です。TAG
は、pull するイメージ バージョンのタグです。
Kubernetes コマンドの詳細については、kubectl の概要をご覧ください。
containerd ノードイメージのトラブルシューティング
GKE ノード バージョン 1.19 以降、Linux ノードのデフォルト ノードイメージは、Docker(cos
)バリアントを含む Container-Optimized OS から、Containerd(cos_containerd
)バリアントが含まれている Container-Optimized OS に代わっています。
Docker バイナリは、containerd をランタイムとして使用する Linux ノードで使用できますが、使用しないことをおすすめします。Docker では、Kubernetes が containerd ノードで実行するコンテナを管理しません。このため、Docker コマンドや Docker API を使用して、実行中の Kubernetes コンテナの表示や操作を行うことはできません。
Linux ノードでのデバッグやトラブルシューティングのため、Kubernetes コンテナ ランタイム用にビルドされたポータブル コマンドライン ツール crictl
を使用して、containerd と対話できます。crictl
は、コンテナやイメージの表示、ログの読み取り、コンテナでのコマンドの実行などの一般的な機能をサポートします。
詳細については、crictl ユーザーガイドと containerd に関する GKE のドキュメントをご覧ください。
Windows Server ノードの場合、containerd デーモンは containerd
という名前の Windows サービスとして実行されます。ログは C:\etc\kubernetes\logs\containerd.log
ディレクトリに格納され、ログ エクスプローラの LOG NAME: "container-runtime"
に表示されます。
公開 Artifact Registry リポジトリからの pull
containerd ノードを含む GKE クラスタにイメージをデプロイしたら、SSH を使用して VM インスタンスに接続し、crictl
コマンドを実行してトラブルシューティングを行うことができます。
公開 Artifact Registry リポジトリでは認証は必要ありません。crictl
は、限定公開 Artifact Registry リポジトリのイメージを pull するためにも使用できます。
コンソール
Google Cloud コンソールで、[VM インスタンス] ページに移動します。
仮想マシン インスタンスのリストで、接続するインスタンスの行にある [SSH] の横の矢印をクリックします。
[ブラウザ ウィンドウで開く] を選択するか、プルダウン オプションから任意の接続方法を選択します。
Google Cloud コンソールで新しいターミナル ウィンドウが開きます。
crictl
を使用して Artifact Registry からイメージを pull します。crictl pull IMAGE_LOCATION:TAG
出力は次のようになります。
Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5
Artifact Registry 非公開リポジトリからイメージを pull する場合は、リポジトリに対する認証を行う必要があります。アクセス トークンを使用して認証情報を提供できます。
gcloud
Google Cloud CLI が最新バージョンであることを確認します。
gcloud components update
VM に接続します。
gcloud compute ssh --project=PROJECT_ID \ --zone=ZONE \ VM_NAME
以下を置き換えます。
PROJECT_ID
: VM が含まれているプロジェクトの IDZONE
: VM が存在するゾーンの名前VM_NAME
: VM の名前
Google Cloud CLI のデフォルト プロパティを設定している場合、このコマンドの
--project
フラグと--zone
フラグは省略できます。次に例を示します。gcloud compute ssh VM_NAME
SSH 認証鍵をまだ作成していない場合は、SSH keygen によって生成されます。プロンプトが表示されたら、パスフレーズを入力するか、空白のままにします。
crictl
を使用して Artifact Registry からイメージを pull します。crictl pull IMAGE_LOCATION:TAG
出力は次のようになります。
Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5
Artifact Registry 非公開リポジトリからイメージを pull する場合は、リポジトリに対する認証を行う必要があります。アクセス トークンを使用して認証情報を提供できます。
非公開 Artifact Registry リポジトリからの pull
コンソール
Google Cloud コンソールで、[VM インスタンス] ページに移動します。
仮想マシン インスタンスのリストで、接続するインスタンスの行にある [SSH] の横の矢印をクリックします。
プルダウン オプションから [ブラウザ ウィンドウで開く] を選択します。
Google Cloud コンソールで新しいターミナル ウィンドウが開きます。
curl
を使用して Compute Engine サービス アカウントのアクセス トークンを生成します。curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" -H "Metadata-Flavor: Google"
出力は、次の例のようになります。
"access_token":"ya29.c.KpkBCQgdwv6LrZ2tjrCpG6snWwPMX29LzMeUmAV_Hq_XaxUurfXcCfGZfASGh_KbdmUYTvkuV3sh-WaSBplEskdP6Tc HDsTv4B9hMyvoL4M9HrzKHuKTa1ZGj_3iQ1lwq_dAMxAPGjxEVKexatwN2KP0EAWyb6R55Cuu8ItgLf9f4pm9lC5zH4Qo0fkxPUsnCGRBe4AYxEpN6T sh","expires_in":3526,"token_type":"Bearer"}
返された出力から
access_token
の値を引用符なしでコピーします。crictl pull --creds
と、前の手順でコピーしたaccess_token
値を使用してイメージを pull します。crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" IMAGE_LOCATION:TAG
出力は次のようになります。
Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5
gcloud
Google Cloud CLI が最新バージョンであることを確認します。
gcloud components update
VM に接続します。
gcloud compute ssh --project=PROJECT_ID \ --zone=ZONE \ VM_NAME
次の変数を置き換えます。
PROJECT_ID
: VM が含まれているプロジェクトの IDZONE
: VM が存在するゾーンの名前VM_NAME
: VM の名前
Google Cloud CLI のデフォルト プロパティを設定している場合、このコマンドの
--project
フラグと--zone
フラグは省略できます。次に例を示します。gcloud compute ssh VM_NAME
SSH 認証鍵をまだ作成していない場合は、SSH keygen によって生成されます。プロンプトが表示されたら、パスフレーズを入力するか、空白のままにします。
curl
を使用して Compute Engine サービス アカウントのアクセス トークンを生成します。curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" -H "Metadata-Flavor: Google"
出力は次のようになります。
"access_token":"ya29.c.KpkBCQgdwv6LrZ2tjrCpG6snWwPMX29LzMeUmAV_Hq_XaxUurfXcCfGZfASGh_KbdmUYTvkuV3sh-WaSBplEskdP6Tc HDsTv4B9hMyvoL4M9HrzKHuKTa1ZGj_3iQ1lwq_dAMxAPGjxEVKexatwN2KP0EAWyb6R55Cuu8ItgLf9f4pm9lC5zH4Qo0fkxPUsnCGRBe4AYxEpN6T sh","expires_in":3526,"token_type":"Bearer"}
返された出力から
access_token
の値を引用符なしでコピーします。crictl pull --creds
と、前の手順でコピーしたaccess_token
値を使用してイメージを pull します。crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" IMAGE_LOCATION:TAG
出力は次のようになります。
Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5
crictl
を使用すると、デベロッパーは Kubernetes コンポーネントを設定せずにランタイムをデバッグできます。コマンドの一覧については、crictl
のドキュメントと Kubernetes デバッグのドキュメントをご覧ください。