Google Kubernetes Engine へのデプロイ

このガイドでは、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 するためにも使用できます。

コンソール

  1. Google Cloud コンソールで、[VM インスタンス] ページに移動します。

    [VM インスタンス] に移動

  2. 仮想マシン インスタンスのリストで、接続するインスタンスの行にある [SSH] の横の矢印をクリックします。

    インスタンス名の横にある SSH ボタン。

  3. [ブラウザ ウィンドウで開く] を選択するか、プルダウン オプションから任意の接続方法を選択します。

  4. Google Cloud コンソールで新しいターミナル ウィンドウが開きます。crictl を使用して Artifact Registry からイメージを pull します。

    crictl pull IMAGE_LOCATION:TAG

    出力は次のようになります。

    Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5

    Artifact Registry 非公開リポジトリからイメージを pull する場合は、リポジトリに対する認証を行う必要があります。アクセス トークンを使用して認証情報を提供できます。

gcloud

  1. Google Cloud CLI が最新バージョンであることを確認します。

    gcloud components update

  2. VM に接続します。

    gcloud compute ssh --project=PROJECT_ID \
 --zone=ZONE \
 VM_NAME

    以下を置き換えます。

    • PROJECT_ID: VM が含まれているプロジェクトの ID
    • ZONE: VM が存在するゾーンの名前
    • VM_NAME: VM の名前

    Google Cloud CLI のデフォルト プロパティを設定している場合、このコマンドの --project フラグと --zone フラグは省略できます。次に例を示します。

    gcloud compute ssh VM_NAME

  3. SSH 認証鍵をまだ作成していない場合は、SSH keygen によって生成されます。プロンプトが表示されたら、パスフレーズを入力するか、空白のままにします。

  4. crictl を使用して Artifact Registry からイメージを pull します。

    crictl pull IMAGE_LOCATION:TAG

  5. 出力は次のようになります。

    Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5

    Artifact Registry 非公開リポジトリからイメージを pull する場合は、リポジトリに対する認証を行う必要があります。アクセス トークンを使用して認証情報を提供できます。

非公開 Artifact Registry リポジトリからの pull

コンソール

  1. Google Cloud コンソールで、[VM インスタンス] ページに移動します。

    [VM インスタンス] に移動

  2. 仮想マシン インスタンスのリストで、接続するインスタンスの行にある [SSH] の横の矢印をクリックします。

    インスタンス名の横にある SSH ボタン。

  3. プルダウン オプションから [ブラウザ ウィンドウで開く] を選択します。

  4. 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"}

  5. 返された出力から access_token の値を引用符なしでコピーします。

  6. crictl pull --creds と、前の手順でコピーした access_token 値を使用してイメージを pull します。

    crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" IMAGE_LOCATION:TAG

    出力は次のようになります。

    Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5

gcloud

  1. Google Cloud CLI が最新バージョンであることを確認します。

    gcloud components update

  2. VM に接続します。

    gcloud compute ssh --project=PROJECT_ID \
 --zone=ZONE \
 VM_NAME

    次の変数を置き換えます。

    • PROJECT_ID: VM が含まれているプロジェクトの ID
    • ZONE: VM が存在するゾーンの名前
    • VM_NAME: VM の名前

    Google Cloud CLI のデフォルト プロパティを設定している場合、このコマンドの --project フラグと --zone フラグは省略できます。次に例を示します。

    gcloud compute ssh VM_NAME

  3. SSH 認証鍵をまだ作成していない場合は、SSH keygen によって生成されます。プロンプトが表示されたら、パスフレーズを入力するか、空白のままにします。

  4. 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"}

  5. 返された出力から access_token の値を引用符なしでコピーします。

  6. 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 デバッグのドキュメントをご覧ください。