GKE のエフェメラルコンテナと IAM・RBAC の二重認可 (Part 2: デバッグコンテナの権限と棚卸し)

エフェメラルコンテナは、実行中の Pod に後から追加できる一時的なコンテナです。 本記事は、GKE でエフェメラルコンテナを使うときの権限を、RBAC と IAM の二重認可の観点から確認する全 2 部構成の Part 2 です。

Part 1 では、次の 2 点をご紹介しました。

  • RBAC の権限がなくても IAM だけでエフェメラルコンテナを追加でき、追加の操作は container.pods.update で認可される。この権限は Kubernetes Engine Developer にも含まれる
  • kubectl auth can-i --as には IAM による許可が反映されない

Part 2 では、Workload Identity Federation for GKE (以降、Workload Identity) を使っている Pod にエフェメラルコンテナを追加したときに、デバッグコンテナがどの Google Cloud の権限で動くのかを確認します。 あわせて、エフェメラルコンテナを追加できる主体の棚卸しと、監査ログでの確認方法を整理します。

検証環境

検証環境は Part 1 と同じです。

  • GKE Standard クラスタ (zonal)、バージョン 1.36.4-gke.2046003 (Regular チャンネル)
  • GKE Autopilot クラスタ、同じバージョン
  • kubectl v1.35.3
  • デバッグ用イメージ nicolaka/netshoot:v0.16 (実際の検証ではダイジェストで固定しています)

Workload Identity の確認は、Standard と Autopilot の両方で行いました。 監査ログの節では、Part 1 で IAM のサービスアカウント debugger@<PROJECT_ID>.iam.gserviceaccount.com に RBAC や IAM の権限を付与してエフェメラルコンテナを追加したときの記録を使います。

デバッグコンテナは Pod の Google Cloud の権限で動く

まずは、Workload Identity を使っている Pod にエフェメラルコンテナを追加したときの、Google Cloud 側の権限を確認します。 Workload Identity Federation for GKE について では、IAM の許可ポリシーの例として次のように説明されています。

たとえば、database-reader Kubernetes ServiceAccount を使用するすべての Pod に、Cloud Storage バケットの読み取り権限を付与できます。

権限の付与先は Kubernetes の ServiceAccount (を使う Pod) で、Pod の中のコンテナ単位ではありません。 では、後から追加したエフェメラルコンテナはどう扱われるのでしょうか。

検証では、Namespace wi-test に ServiceAccount wi-app を使う Pod app を作成し、テスト用のバケットに対する Storage Object Viewer (roles/storage.objectViewer) を wi-app に付与しました。

$ gcloud storage buckets add-iam-policy-binding gs://<BUCKET> \
    --role=roles/storage.objectViewer \
    --member=principal://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/<PROJECT_ID>.svc.id.goog/subject/ns/wi-test/sa/wi-app

この Pod に kubectl debug でエフェメラルコンテナを追加し、コンテナの中からバケットのオブジェクトの一覧取得と読み取りを試しました。 比較のため、IAM の権限を付与していない default ServiceAccount の Pod でも同じことを試しています。

対象の Pod ServiceAccount バケットへのアクセス
wi-test/app wi-app (Storage Object Viewer を付与) 一覧取得と読み取りに成功
dbg/app-root default (付与なし) 403 で拒否

結果は Standard と Autopilot で同じでした。 エフェメラルコンテナは、追加先の Pod の ServiceAccount に付与された Google Cloud の権限で動いていることがわかります。

Workload Identity では、Pod からのトークンのリクエストを GKE メタデータサーバが受け取り、Kubernetes API サーバにそのワークロードを表すトークンを要求したうえで、有効期間の短いアクセストークンに交換して返します。 エフェメラルコンテナは Pod のネットワーク名前空間を共有しているので、メタデータサーバから見ると Pod 本体のコンテナと区別がつかないのだと考えられます。

Part 1 で確認したとおり、Kubernetes Engine Developer にはエフェメラルコンテナの追加を認可する container.pods.update が含まれています。 そのため、プロジェクトでこのロールを持っていれば、そのプロジェクトのクラスタで Workload Identity を使っている Pod の Google Cloud の権限も使えることになります。 ただし、これはエフェメラルコンテナに限った話ではありません。 Kubernetes Engine Developer には container.pods.exec も含まれているので、kubectl exec でアプリのコンテナの中でコマンドを実行すれば、同様に Pod の ServiceAccount に付与された Google Cloud の権限を使えます。 エフェメラルコンテナの場合は、アプリのイメージにツールが入っていなくても、デバッグ用のツールを含むイメージを持ち込める点が異なります。 本番の Pod をデバッグできる権限は、その Pod の ServiceAccount が持つ Google Cloud の権限も使える権限として扱っておくのがよさそうです。

ちなみに、Pod の egress を kube-dns だけに絞る NetworkPolicy を適用した Pod では、エフェメラルコンテナからメタデータサーバへの通信もタイムアウトしました。 NetworkPolicy は Pod を単位に通信を制御するため、後から追加したエフェメラルコンテナにも、もとからあるアプリのコンテナと同じように適用されることになります。

権限の棚卸しと監査ログ

Part 1 とここまでの結果をふまえて、「エフェメラルコンテナを追加できるのは誰か」を確認するときのポイントを整理しておきます。

RBAC と IAM の両方を確認する

確認する対象は次の 2 つです。

  • RBAC: pods/ephemeralcontainers に対する patch または update を許可している Role / ClusterRole (ワイルドカードを含むもの) と、そのバインディング
  • IAM: container.pods.update を含むロール (Kubernetes Engine Admin、Kubernetes Engine Developer、Editor、カスタムロール) の付与先。フォルダや組織で付与されたロールも対象になります

RBAC で update も対象にしているのは、kubectl debug が使う PATCH のほかに、PUT でもエフェメラルコンテナを追加できるためです。

IAM 側は、Policy Analyzer (Analyze allow policies) を使うと、特定の権限を持つプリンシパルを洗い出せます。

Namespace 単位で絞りたい場合は、開発者への IAM の付与をクラスタに接続するための Kubernetes Engine Cluster Viewer 程度にとどめ、エフェメラルコンテナの追加は RBAC で Namespace ごとに付与する、という分担が考えられます。 Part 1 のステップ 2 では、IAM は Cluster Viewer だけにして RBAC の Role でエフェメラルコンテナの追加を許可した構成で、kubectl debug を使えることを確認しています。

監査ログで RBAC と IAM のどちらで許可されたかを確認する

エフェメラルコンテナの追加は、Cloud Audit Logs の管理アクティビティ監査ログに記録されます。 kubectl debug による追加は、メソッド名 io.k8s.core.v1.pods.ephemeralcontainers.patch で記録されていました。 PUT で追加した場合は今回確認していませんが、メソッド名の付け方からすると io.k8s.core.v1.pods.ephemeralcontainers.update になると考えられるので、両方を対象にしておいたほうが良さそうです。

protoPayload.methodName="io.k8s.core.v1.pods.ephemeralcontainers.patch" OR protoPayload.methodName="io.k8s.core.v1.pods.ephemeralcontainers.update"

ログエントリの labels には認可の判断とその理由が記録されていて、RBAC と IAM のどちらで許可されたのかを区別できました。 次は、Part 1 の検証で IAM の権限だけでエフェメラルコンテナを追加したときのログエントリの抜粋です。

{
  "protoPayload": {
    "methodName": "io.k8s.core.v1.pods.ephemeralcontainers.patch",
    "resourceName": "core/v1/namespaces/rbac-test/pods/target/ephemeralcontainers"
  },
  "labels": {
    "authorization.k8s.io/decision": "allow",
    "authorization.k8s.io/reason": "access granted by IAM permissions."
  }
}

RBAC で許可された場合は、authorization.k8s.io/reason が次のようになっていました。

RBAC: allowed by RoleBinding "ephemeral-debugger/rbac-test" of Role "ephemeral-debugger" to User "debugger@<PROJECT_ID>.iam.gserviceaccount.com"

Part 1 で紹介したとおり、kubectl auth can-i --as では IAM 経由の許可を確認できませんが、監査ログでは RBAC と IAM のどちらで許可されたかが区別して記録されています。 エフェメラルコンテナの追加をアラートの対象にしたり、定期的に棚卸ししたりする際の手がかりにできそうです。

まとめ

Part 2 では、エフェメラルコンテナとして追加したデバッグコンテナが使える Google Cloud の権限と、権限の棚卸しや監査ログでの確認方法をご紹介しました。

  • エフェメラルコンテナは、追加先の Pod の Workload Identity の権限で動く。kubectl exec でも同じ権限を使える
  • NetworkPolicy は、後から追加したエフェメラルコンテナにも適用される
  • エフェメラルコンテナを追加できる主体は、RBAC (pods/ephemeralcontainers の patch と update) と IAM (container.pods.update) の両方で棚卸しする
  • 監査ログの authorization.k8s.io/reason で、RBAC と IAM のどちらで許可されたかを区別できる

2 回にわたって、GKE でエフェメラルコンテナを使うときの権限を、IAM と RBAC の二重認可の観点から確認してきました。 エフェメラルコンテナを追加できる権限は、クラスタの中だけでなく、Pod が持つ Google Cloud の権限にもつながっています。 あらかじめ権限の付与先と監査ログの見方を押さえておけば、安心して活用できるのではないでしょうか。 お読み頂いた方のお役に立てば幸いです。

GKE のエフェメラルコンテナと IAM・RBAC の二重認可 (Part 1: 必要な権限とその確認方法)

エフェメラルコンテナは、実行中の Pod に後から追加できる一時的なコンテナです。 kubectl debug コマンドと組み合わせると、distroless のようにシェルやツールを含まないイメージで動いているアプリケーションでも、Pod を作り直さずに中から調査できます。

GKE では、クラスタ内の操作を Kubernetes の RBAC だけでなく IAM でも認可しています。 そのため、ある Pod にエフェメラルコンテナを追加できるのが誰なのかは、RBAC の設定だけを見ていても判断できません。

今回は、GKE のクラスタで RBAC と IAM の権限を切り替えながら kubectl debug を実行し、権限まわりで気をつけておきたい点を確認しました。 内容が多くなったので、全 2 部構成でご紹介する予定です。

  • Part 1 (本記事): エフェメラルコンテナの利用に必要な権限と、その確認方法
  • Part 2: 追加したデバッグコンテナが使える Google Cloud の権限と、権限の棚卸しや監査ログでの確認

Part 1 では、エフェメラルコンテナの追加が RBAC と IAM のどちらで許可されるのかと、その権限を kubectl auth can-i で確認するときの注意点の 2 つを取り上げます。

検証環境

検証には次の環境を使いました。

  • GKE Standard クラスタ (zonal)、バージョン 1.36.4-gke.2046003 (Regular チャンネル)
  • GKE Autopilot クラスタ、同じバージョン
  • kubectl v1.35.3
  • デバッグ用イメージ nicolaka/netshoot:v0.16 (実際の検証ではダイジェストで固定しています)

本記事の内容は、Autopilot クラスタについての補足を除いて Standard クラスタで確認しています。

権限を切り替える対象として、IAM のサービスアカウント debugger@<PROJECT_ID>.iam.gserviceaccount.com を用意しました。 開発者のユーザーアカウントの代わりに、このサービスアカウントのアクセストークンを kubeconfig に設定し、Namespace rbac-test の Pod target に kubectl debug でエフェメラルコンテナを追加していきます。 IAM では最初に Kubernetes Engine Cluster Viewer (roles/container.clusterViewer) だけを付与し、そこから次の 5 つのステップで権限を切り替えました。

ステップ RBAC IAM エフェメラルコンテナの追加
1 なし Cluster Viewer のみ 拒否
2 Role を付与 Cluster Viewer のみ 成功
3 なし Kubernetes Engine Developer を追加 成功
4 なし カスタムロール (container.pods.update なし) 拒否
5 なし カスタムロール (container.pods.update あり) 成功

ステップ 4 と 5 では Kubernetes Engine Developer を外し、カスタムロールに container.clusters.get、container.pods.get、container.pods.list、container.pods.attach、container.pods.getLogs を含めたうえで、container.pods.update の有無だけを変えています。

(1) IAM の付与だけでエフェメラルコンテナを追加できる

まずは、RBAC と IAM のどちらで許可されていればエフェメラルコンテナを追加できるのかを確認します。 GKE の Access control には、IAM と RBAC の関係について次のように書かれています。

IAM and Kubernetes RBAC work together to help manage access to your cluster. RBAC controls access on a cluster and namespace level, while IAM works on the project level. An entity must have sufficient permissions at either level to work with resources in your cluster.

どちらか一方のレベルで十分な権限があれば、クラスタ内のリソースを操作できる、と読めます。 ちなみに 日本語版 では「エンティティには、いずれのレベルでも、クラスタ内のリソースを操作するための十分な権限が必要です。」と訳されていて、両方のレベルで権限が必要とも読めてしまうので、英語版とあわせて確認しておくと安心です。

実際、権限が足りないときのエラーメッセージにも、IAM と RBAC のどちらかがあればよいことが示されています。 次はステップ 4 で kubectl debug を実行したときの出力です。

$ kubectl debug target -n rbac-test --container=no-update --profile=general --image=nicolaka/netshoot:v0.16 -- sh -c "echo hello"
Error from server (Forbidden): pods "target" is forbidden: User "debugger@<PROJECT_ID>.iam.gserviceaccount.com" cannot patch resource "pods/ephemeralcontainers" in API group "" in the namespace "rbac-test": requires one of ["container.pods.update"] permission(s) in Cloud IAM or a Kubernetes RBAC role with verb "patch" for resource "pods/ephemeralcontainers".

Kubernetes の組み込みロールには含まれない

RBAC の側から見ていきます。 Kubernetes には edit や admin といった組み込みの ClusterRole がありますが、これらには pods/ephemeralcontainers が含まれていません。 Kubernetes 1.36 の bootstrap policy の定義 を見ても、edit には pods/exec や pods/attach への書き込み権限がある一方で、pods/ephemeralcontainers は登場しません。

検証クラスタでも、pods/ephemeralcontainers を明示的に含む ClusterRole は見つかりませんでした。

$ kubectl get clusterrole -o json | jq -r '.items[] | select(any(.rules[]?; (.resources // []) | index("pods/ephemeralcontainers"))) | .metadata.name'
$

ワイルドカードで全リソースを許可している cluster-admin などを除くと、RBAC でエフェメラルコンテナの追加を許可するには Role を自分で用意する必要があります。 ステップ 2 では、次の Role を RoleBinding で付与しました。

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: ephemeral-debugger
  namespace: rbac-test
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get"]
- apiGroups: [""]
  resources: ["pods/ephemeralcontainers"]
  verbs: ["patch"]
- apiGroups: [""]
  resources: ["pods/log"]
  verbs: ["get"]

この Role だけで、-i を付けない kubectl debug によるエフェメラルコンテナの追加ができました。

IAM では container.pods.update で許可される

続いて、ステップ 3 で RoleBinding を削除し、IAM で Kubernetes Engine Developer (roles/container.developer) を付与しました。 RBAC の権限がない状態でも、エフェメラルコンテナを追加できました。

# 管理者のアカウントで実行
$ kubectl get rolebinding -n rbac-test
No resources found in rbac-test namespace.

# debugger のサービスアカウントで実行
$ kubectl debug target -n rbac-test --container=iam-only --profile=general --image=nicolaka/netshoot:v0.16 -i -- sh -c "echo hello-from-iam-only"
...
hello-from-iam-only

どの IAM 権限で許可されているのかを切り分けるため、ステップ 4 と 5 ではカスタムロールで container.pods.update の有無だけを変えて比較しました。 container.pods.update を含まないカスタムロールでは先ほどのエラーで拒否され、含むカスタムロールでは追加できました。 エラーメッセージのとおり、エフェメラルコンテナの追加に対応する IAM の権限は container.pods.update です。

プロジェクトで付与できる container.pods.* の権限を一覧してみても、エフェメラルコンテナに対応する個別の権限は見当たりませんでした。

$ gcloud iam list-testable-permissions //cloudresourcemanager.googleapis.com/projects/<PROJECT_ID> \
    --filter="name:container.pods." --format="value(name)"
container.pods.attach
container.pods.create
container.pods.delete
container.pods.evict
container.pods.exec
container.pods.get
container.pods.getLogs
container.pods.getStatus
container.pods.initialize
container.pods.list
container.pods.portForward
container.pods.proxy
container.pods.update
container.pods.updateStatus

つまり IAM では、「エフェメラルコンテナの追加だけを許可して、Pod へのその他の更新は許可しない」という付与の仕方はできないことになります。 RBAC では pods の update と pods/ephemeralcontainers の patch を別々に付与できるので、ここは IAM と RBAC で粒度が異なる点です。

container.pods.update を含む事前定義ロールを gcloud iam roles describe で確認すると、次のようになっていました。

ロール container.pods.update
Kubernetes Engine Admin (roles/container.admin) あり
Kubernetes Engine Developer (roles/container.developer) あり
Editor (roles/editor) あり
Kubernetes Engine Viewer (roles/container.viewer) なし
Kubernetes Engine Cluster Viewer (roles/container.clusterViewer) なし
Viewer (roles/viewer) なし

また、Access control には IAM のロールの適用範囲について次の記述があります。

An IAM role grants privileges across all clusters in the project, or all clusters in all child projects if the role is applied at the folder level.

Kubernetes Engine Developer は開発者に広く付与されていることも多いのではないでしょうか。 プロジェクトでこのロールを持っていれば、IAM の認可としては、そのプロジェクトのすべてのクラスタで Namespace を問わずエフェメラルコンテナの追加が許可されることになります (実際に追加できるかどうかは、認可のあとに評価される Pod Security Admission や Binary Authorization などのアドミッション制御にも依ります)。 RBAC の組み込みロールでは edit や admin にも含まれていない一方、IAM では開発者向けのロールに含まれている、という点には注意が必要です。

ちなみに、Autopilot クラスタでは kube-system Namespace の Pod へのエフェメラルコンテナの追加は、クラスタを作成した管理者のアカウントでも拒否されました。 Autopilot が管理する Namespace については、IAM の権限とは別に保護されているようです。

kubectl debug -i には list と watch も必要

ステップ 2 の Role で、-i (標準入力をつなぐオプション) を付けて kubectl debug を実行したところ、コマンドが戻ってこなくなりました。 -v=6 でリクエストを確認すると、エフェメラルコンテナの追加 (PATCH) 自体は成功しており、その後に Pod の状態を待つための watch と list が拒否されていました (出力は整形しています)。

GET   /api/v1/namespaces/rbac-test/pods/target                                          200 OK
PATCH /api/v1/namespaces/rbac-test/pods/target/ephemeralcontainers                      200 OK
GET   /api/v1/namespaces/rbac-test/pods?fieldSelector=metadata.name=target&watch=true   403 Forbidden
GET   /api/v1/namespaces/rbac-test/pods?fieldSelector=metadata.name=target&limit=500    403 Forbidden

kubectl はこの list と watch を再試行し続けるので、エフェメラルコンテナは追加済みなのにコマンドが終わらない、という状態になります。 Role に pods の list と watch を加えるとコマンドは戻るようになりましたが、今度は pods/attach の権限がないため、アタッチせずにログの表示にフォールバックしました。

warning: couldn't attach to pod/target, falling back to streaming logs: pods "target" is forbidden: User "debugger@<PROJECT_ID>.iam.gserviceaccount.com" cannot create resource "pods/attach" in API group "" in the namespace "rbac-test": requires one of ["container.pods.attach"] permission(s) in Cloud IAM or a Kubernetes RBAC role with verb "create" for resource "pods/attach".
hello-from-rbac-listwatch

kubectl debug -it で対話的に使う前提で、ステップ 2 の Role を次の構成にしたところ、上記の権限エラーは出なくなりました。

rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "list", "watch"]
- apiGroups: [""]
  resources: ["pods/ephemeralcontainers"]
  verbs: ["patch"]
- apiGroups: [""]
  resources: ["pods/attach"]
  verbs: ["create"]
- apiGroups: [""]
  resources: ["pods/log"]
  verbs: ["get"]

このうち pods/log の get は、kubectl v1.35.3 のソース を見る限り、アタッチに失敗したときや、アタッチする前にデバッグコンテナが終了していたときにログを表示するために使われます。 アタッチできる場合には使われないようなので、必須ではなさそうです。

IAM の場合は、Kubernetes Engine Developer に container.pods.list と container.pods.attach も含まれているため、この問題は起きませんでした。

(2) kubectl auth can-i --as には IAM の許可が反映されない

権限の確認には kubectl auth can-i がよく使われます。 ここでは、管理者が --as で他のユーザーになりすまして確認する方法と、ユーザー本人の認証情報で確認する方法を、ステップ 2 (RBAC のみ) とステップ 3 (IAM のみ) で比べました。

確認方法 ステップ 2 (RBAC のみ) ステップ 3 (IAM のみ)
本人の認証情報で kubectl auth can-i yes yes
管理者が --as を付けて kubectl auth can-i yes no

ステップ 3 の出力は次のとおりです。

# debugger のサービスアカウントで実行
$ kubectl auth can-i patch pods --subresource=ephemeralcontainers -n rbac-test
yes

# 管理者のアカウントで実行
$ kubectl auth can-i patch pods --subresource=ephemeralcontainers -n rbac-test \
    --as=debugger@<PROJECT_ID>.iam.gserviceaccount.com
no

IAM だけで許可されている状態では、本人の認証情報で確認すると yes になる一方で、--as で確認すると no になりました。

この挙動は、GKE の Role-based access control にも書かれています。

When you run the command kubectl auth can-i without the --as flag, Identity and Access Management (IAM) performs the authorization. Whereas, when you append the --as flag, Kubernetes RBAC performs the authorization.

ただし、ステップ 2 では本人の認証情報でも yes になっているので、--as を付けない場合も RBAC の許可は反映されています。

このセクションには理由までは書かれていませんが、なりすましの仕組みの違いによるものと考えられます。 kubectl の --as は、API サーバが認可に使うユーザー名を差し替えるだけで、送る認証情報は管理者のもののままです。 一方、今回「本人の認証情報」として使ったのは、gcloud auth print-access-token --impersonate-service-account で取得したサービスアカウントのトークンで、GKE にはサービスアカウント本人としてリクエストが届きます。

そのため、管理者が --as で「このユーザーはエフェメラルコンテナを追加できない」と確認しても、IAM で Kubernetes Engine Developer が付与されていれば実際には追加できる、ということが起こりえます。 サービスアカウントであれば Google Cloud のレベルでなりすまして確認できますが、ユーザーアカウントにはなりすませないため、IAM 側の付与状況は IAM ポリシーのほうで確認する必要があります。

サブリソースは --subresource で指定する

ちなみに、kubectl auth can-i patch pods/ephemeralcontainers のようにスラッシュでつなげて書くと、意図した確認になりません。 kubectl auth can-i の引数は VERB [TYPE | TYPE/NAME | NONRESOURCEURL] という形式なので、pods/ephemeralcontainers は「ephemeralcontainers という名前の Pod」と解釈されます。 実際、ステップ 2 の状態でスラッシュの形式で確認すると、pods に対する patch の権限を確認した結果として no が返りました。

$ kubectl auth can-i patch pods/ephemeralcontainers -n rbac-test
no - requires one of ["container.pods.update"] permission(s) in Cloud IAM or a Kubernetes RBAC role with verb "patch" for resource "pods".

サブリソースを確認するときは、--subresource=ephemeralcontainers で指定しましょう。

まとめ

Part 1 では、GKE でエフェメラルコンテナを追加する権限について、IAM と RBAC の二重認可の観点から実機検証の結果をご紹介しました。

  • RBAC の権限がなくても IAM だけでエフェメラルコンテナを追加でき、追加の操作は container.pods.update で認可される。この権限は Kubernetes Engine Developer にも含まれる
  • kubectl auth can-i --as には IAM による許可が反映されない

kubectl debug は障害調査で頼りになるコマンドですが、「誰が使えるのか」は RBAC と IAM の両方を見ないと把握できません。

次回の Part 2 では、Workload Identity Federation for GKE を使っている Pod にエフェメラルコンテナを追加したときに、デバッグコンテナがどの Google Cloud の権限で動くのかを確認します。 あわせて、エフェメラルコンテナを追加できる主体の棚卸しと、監査ログで RBAC と IAM のどちらで許可されたかを確認する方法もご紹介する予定です。

ComputeClass を用いた GKE Standard のノードプール拡張 (Part 3: カスタム Autopilot ComputeClass)

前回の Part 2 では、組み込みの autopilot ComputeClass で Standard クラスタに Autopilot 管理のノードを立て、gk3- プレフィックスや taint、Pod への mutation、DaemonSet の除外といった、「ノードの管理を Google に任せた場合」の挙動を確かめました。

では、組み込み版の ComputeClass と同じ内容を、ユーザ定義の ComputeClass で書いた場合、同じ結果が得られるでしょうか。 spec を見る限り、組み込み autopilot は podFamily: general-purpose の priority と autopilot.enabled: true を持つ、ごく普通の ComputeClass に見えます。 ということは、「同じ内容をカスタム ComputeClass で定義すれば、組み込み版と同じ結果が得られる」ことが期待できそうです。

連載の最終回となる Part 3 では、この組み込みとカスタムの ComputeClass の違いを、実機で確かめた様子をご紹介します。

検証条件

クラスタは Part 1, 2 と同じ、asia-northeast1-a の 1.36.0-gke.4447000 zonal Standard クラスタです (詳細は Part 1 の「検証環境」を参照ください)。

本記事で apply するワークロードは、いずれも 1 コンテナ / 1 Pod (Deployment は replicas: 1) で、resources は requests / limits とも cpu 500m / memory 512Mi に揃えています。 Part 2 の Job (組み込み autopilot ComputeClass、同じ requests / 1 Pod) と autoscaler 視点では同水準の compute 要求となっており、ワークロード視点ではおおよその条件を揃えました (Job / Deployment というコントローラ種別や、実行時点のクラスタ状態など、正確に揃っていない条件もあることはご承知おきください)。 Part 1, 2 と同様、計測値はあくまで参考程度とお考えください。

machineFamily を指定するカスタム Autopilot ComputeClass

最初は、autopilot.enabled: true に machineFamily: n2 を組み合わせるパターンです。 Part 1 の basic-n2 と同じマシンファミリー指定に、autopilot.enabled: true を加えた構成といえます。

apiVersion: cloud.google.com/v1
kind: ComputeClass
metadata:
  name: ap-n2-custom
spec:
  autopilot:
    enabled: true
  priorities:
  - machineFamily: n2
    spot: true
  - machineFamily: n2
    spot: false
  whenUnsatisfiable: ScaleUpAnyway

apply 後に立ち上がったノードを確認します。

$ kubectl get nodes -L cloud.google.com/compute-class,cloud.google.com/machine-family,cloud.google.com/gke-spot
NAME                                                  ...   COMPUTE-CLASS   MACHINE-FAMILY   GKE-SPOT
gk3-gke-cc-poc-nap-n2-standard-2-spot-c0d1a47b-hldx   ...   ap-n2-custom    n2               true

ノード VM 名は gk3- プレフィックスで、MACHINE-FAMILY は n2、priority 1 のとおり spot です。 autopilot.enabled: true を加えても、priority に書いた machineFamily: n2 はそのまま尊重されています。 ノードラベルにも gke-image-streaming: true / gke-gcfs: true / autopilot-managed-node: true など、Part 2 で見た Autopilot 共通の要素が同様に付与されていました。 「Autopilot 化の付加要素は一式付くが、マシンの選出は設定したとおりの挙動が観測できる」という結果となっています。

ところで、この spec には Part 1 で使った nodePoolAutoCreation.enabled: true を書いていません。 それでもプールが自動作成されたのは、spec に補完が入るためです。 apply 後の spec を kubectl get computeclass -o yaml で取得すると、autopilot.enabled: true の ComputeClass には nodePoolAutoCreation.enabled: true と autoscalingPolicy (組み込み版と同じ値) が自動で補完されていました (この補完は、後述のスケールダウンの考察に関わってきます)。

課金モデルの整理 (Part 2) に照らすと、machineFamily を指定した priority rule なので、node-based billing が適用される構成になるはずです。

一方、細部には Part 2 の組み込み版と違う点もありました。 Pod への mutation は、ephemeral-storage: 1Gi の追加が requests のみで、requests / limits の両方に追加された組み込み版とは異なる状態となっていました。

podFamily を指定するカスタム Autopilot ComputeClass

次は、組み込み版と同じ podFamily: general-purpose を priority に書くパターンを試してみます。 カスタム ComputeClass での podFamily は 1.35.2-gke.1485000 以降で使えるようになった、比較的新しい書き方です (Part 2 のバージョン要件を参照)。

論理的には、組み込み autopilot と同じ指定のはずです。

apiVersion: cloud.google.com/v1
kind: ComputeClass
metadata:
  name: ap-podfamily-custom
spec:
  autopilot:
    enabled: true
  priorities:
  - podFamily: general-purpose
  whenUnsatisfiable: ScaleUpAnyway

ワークロードは同じ基準条件 (replicas: 1 / requests / limits とも cpu 500m / memory 512Mi) です。 apply 後、Pod は 122 秒で Pending → Running になりました。

$ kubectl get nodes -L cloud.google.com/compute-class,cloud.google.com/machine-family
NAME                                                  ...   COMPUTE-CLASS         MACHINE-FAMILY
gk3-gke-cc-poc-nap-e2-medium-wsvb82l4-dfa0c313-7psd   ...   ap-podfamily-custom   e2

調達されたノードは e2-medium です。 Part 2 で組み込み autopilot が引いたのと同じマシンタイプで、gk3- プレフィックスも、taint が 2 つであることも、gke-max-pods-per-node: 32 も、ephemeral-storage: 1Gi が requests / limits の両方に付く mutation も、組み込み版と同じでした。 機種と付加要素を見る限り、これも「組み込みと同じ内容を書けばカスタムでも同じ結果が得られる」ように見えます。

e2-medium は fallback ではないのか

Part 1 の検証では、whenUnsatisfiable: ScaleUpAnyway の fallback で default の E2 シリーズが起動しました。 今回のカスタム ComputeClass も ScaleUpAnyway で、起動したのは e2-medium です。 「podFamily を満たせず、fallback の結果としてたまたま E2 が調達されただけ」という可能性は考えられるでしょうか。

そこで、whenUnsatisfiable: DoNotScaleUp に変えた variant (便宜的に ap-podfamily-dnsup と呼びます) を用意してみました。 DoNotScaleUp なら、priority を満たせない場合 Pod は Pending のまま残り、fallback は起こらないはずです。 結果、この variant でも Pod は Pending のまま滞留することなく e2-medium のノードにスケジュールされました。 乗った先は既存ノードではなく、この variant 用に自動作成された新規プール (nap-e2-medium-y9n2qnz4) のノードで、ノードの compute-class ラベルも ap-podfamily-dnsup となっていました。

ただし、この推論は「DoNotScaleUp が仕様どおり動いている」ことを前提にしています。 こちらも確認のため、満たせない priority (存在しない machineType) だけを持つ DoNotScaleUp の ComputeClass を作り、基準条件のワークロードを deploy して 300 秒観察したところ、Pod は一貫して Pending のままでした。 (対照条件を揃えるため、この ComputeClass にも autopilot.enabled: true を入れています)

## POLL: wait until >=1 pods (-l app=pending-control-app) reach Running (timeout 300s)
[t+0015s] pending-control-app-...=Pending;
[t+0150s] pending-control-app-...=Pending;
[t+0285s] pending-control-app-...=Pending;
## RESULT: TIMEOUT at t+300s

DoNotScaleUp は仕様どおり Pending を維持するようです。 その DoNotScaleUp の下でも e2-medium が立った以上、autoscaler は「podFamily: general-purpose という priority を e2-medium で満たせる」と判断している、つまり fallback ではないと考えられます。 podFamily はハードウェアを指名しない priority rule なので、requests に見合う小さなマシンが正規の選択肢として選ばれているようです。

マシンの調達ロジックが同じ、付加要素も同じ、そして fallback でもない、ということで、ここまでに見てきた内容では組み込み版とカスタム版に違いが見られません。

Pod の最小サイズはどうか

今度は、Part 2 の mutation 検証で使った、最小値以下の requests (cpu: 10m / memory: 16Mi、limits なし) の probe Pod をもう一度使います。 組み込み autopilot 経由では、requests は 50m / 52Mi に引き上げられるのでした。 同じ probe を、カスタムの ap-podfamily-custom を nodeSelector に指定して deploy します。

{
  "limits": {
    "ephemeral-storage": "1Gi"
  },
  "requests": {
    "cpu": "500m",
    "ephemeral-storage": "1Gi",
    "memory": "512Mi"
  }
}

結果、request の値は 500m / 512Mi となりました。 組み込み版の 10 倍の CPU、およそ 10 倍のメモリが、最小値として強制されています。 マシンの調達ロジックもラベルも同じに見えていた両者ですが、Pod の最小サイズという点では異なる結果となりました。

この差異が生まれた要因について、公式ドキュメントに記載があります。 Resource requests in Autopilot の最小値の表は、「デフォルトとして登録されていないカスタム Autopilot ComputeClass の podFamily priority rule を使う Pod」を独立したカテゴリとして扱い、その最小値を CPU 0.5 vCPU / メモリ 0.5 GiB と定めています。 組み込み ComputeClass (bursting 対応クラスタで 50m / 52 MiB) とは別の区分です。 今回の観測値 (500m / 512Mi = 0.5 vCPU / 0.5 GiB) は、この記載と一致しています。

ちなみに、本記事の基準ワークロードをそのまま使っている限り、この差は見えませんでした。 基準の cpu 500m / memory 512Mi は、偶然ですがこのカテゴリの最小値と同じ値で、mutation が働いても値が変わらないためです (最小値以下の probe を投げてはじめて、両者の違いが表面化しました)。

なお、autopilot なしの ComputeClass (Part 1 と同じ basic-n2) に同じ probe を投げても、mutation は一切かかりませんでした (requests は 10m / 16Mi のまま、ephemeral-storage の追加もなし)。 公式ドキュメントの書きぶりから見ても、最小値の強制は Autopilot 系に固有と見て良さそうです。

デフォルト登録すると何が変わるか

GKE には、Pod が ComputeClass を明示的に選ばなかった場合に適用されるデフォルト ComputeClass を、namespace 単位またはクラスタ単位で設定する仕組みがあります (Apply ComputeClasses to Pods by default)。 さきほどはデフォルトとしての登録がないカスタム ComputeClass の挙動を観測しましたが、同じカスタム ComputeClass をデフォルトとして登録すれば、振る舞いが変わるでしょうか。

まずは、namespace 単位のデフォルト設定を試してみましょう。 namespace に cloud.google.com/default-compute-class=ap-podfamily-custom のラベルを付け、その namespace に nodeSelector を書いていない Pod を deploy します。

Pod の spec を確認すると、ComputeClass の nodeSelector が自動で注入されていました。

$ kubectl get pod -l app=probe-default-ns -o jsonpath='{.items[0].spec.nodeSelector}'
{"cloud.google.com/compute-class":"ap-podfamily-custom"}

そして、最小値以下の probe (10m / 16Mi) に対する mutation は、50m / 52Mi でした。 明示的な nodeSelector で選んだときは 500m / 512Mi に引き上げられた、同じ ap-podfamily-custom です。 ComputeClass の spec には一切手を加えていません。 それでも、デフォルトとして選ばせただけで、この試行では Pod の最小値が組み込み版と同じ扱いになりました。

公式の最小値の表に明記されている区分は「組み込み / クラスタ単位のデフォルト」と「それ以外のカスタム」で、namespace 単位のデフォルトがどちらに属するかは明記されていないようですが、挙動を見る限り、namespace 単位でも「デフォルト側」の扱いになるようです。

次に、クラスタ単位のデフォルトも試してみましょう。 こちらは gcloud container clusters update --enable-default-compute-class でフラグを有効にし、default という名前の ComputeClass (spec は ap-podfamily-custom と同一) を作る方式です。 ラベルのない namespace に nodeSelector なしの Pod を deploy したところ、基準サイズの Deployment は新規の gk3- プールに乗り、probe の mutation はやはり 50m / 52Mi 側でした。

ただし、Pod spec の書き換えられ方が namespace 単位のときと異なります。 前掲の Apply ComputeClasses to Pods by default には、次の記載があります。

If the namespace has a default ComputeClass, GKE modifies the Pod specification to select that ComputeClass.

If the namespace doesn't have a default ComputeClass, the cluster-level default class applies. GKE doesn't modify the Pod specification.

実機で見ると、確かに nodeSelector は注入されていませんでした。 一方で toleration (autopilot-managed-node と kubernetes.io/arch) は注入されており、最小値の mutation も前述のとおり働いているため、「spec を変更しない」という記載の対象は、あくまで ComputeClass の選択機構 (nodeSelector) の話で、Autopilot 系の mutation や toleration は別経路、と考えられそうです。 また、デフォルト ComputeClass 用に立ったプールのノードには compute-class の taint がなく、taint は autopilot-managed-node の 1 つだけでした。 nodeSelector で縛られない Pod が Autopilot 管理ノードに乗れていたのは、この taint 構成と注入された toleration の組み合わせによるものです。

nodeSelector がない、ということは、配置制約の緩さにつながります。 検証中の何度かの試行では、mutation を受けて 50m / 52Mi になった probe が、Autopilot 管理ノードではなく既存の default-pool (通常の Standard ノード) にスケジュールされました。 Pod を ComputeClass のノードに拘束するものが spec 上にないため、既存ノードに収まるならそちらに置かれることも仕組み上ありえます。 「デフォルト ComputeClass を設定したから、対象 Pod はすべて Autopilot 管理ノードで動くはずだ」と考えていると、想定と異なる挙動になってしまう可能性があります。

なお、デフォルト経由で立ったマシンタイプは試行によって異なりました (e2-medium のときもあれば、ek-standard-8 のときもある)。 ek は Part 2 で触れた Autopilot 専用のマシンシリーズで、今回の一連の検証では、このデフォルト登録の試行にだけ現れています。 podFamily がマシンを固定しない、という定義どおりの挙動が実機からも観測できました。

補足: 何をもって「カスタム」ComputeClass を識別しているか

ここまでの結果では、明示的な nodeSelector で選んだカスタム ComputeClass は 500m / 512Mi、デフォルト登録して選ばせた同じクラスは 50m / 52Mi と、扱いが分かれました。 GKE は何を見てこの判定を行っているのでしょうか。 spec の内容が組み込み版と一致していれば、組み込みの ComputeClass と同じ扱いになるのでしょうか。

組み込み autopilot の spec をフィールド単位で完全に複製した ComputeClass を作って確かめてみましょう。 ComputeClass 名は autopilot / gke で始められない予約プレフィックスの制約があるため、名前は ap-podfamily-clone としました。 activeMigration も description の文字列も、組み込み版と bit-exact に揃えた構成です。

結果、立ったノードは e2-medium で、機種の面では違いが出ませんでしたが、probe に対する mutation は 500m / 512Mi のままでした。 どうやら (spec を完全に写しても) 明示的な nodeSelector で選ぶ限りは、カスタム ComputeClass として扱われているようです。 よって、「spec の内容さえ組み込み版と一致していれば組み込み扱いになる」ということではないようです。

となると、先ほどの試行で変更した、登録の有無と選択経路 (デフォルト経由か、明示の nodeSelector か) のいずれか (あるいは両方) が、50m / 52Mi 側に倒した要因と考えられます。 これを確認するため、今度は「デフォルト登録済みのクラスを明示的な nodeSelector で選ぶ」probe を、クラスタを立て直して追試しました (この追試のみ、GKE 1.36.0-gke.4681000 での観測です)。

結果は、登録の単位によって割れました。

  • namespace デフォルトに登録した ap-podfamily-custom を明示的な nodeSelector で選ぶと、登録した namespace の中からでも、ラベルのない別の namespace からでも 500m / 512Mi (カスタム側) になる
  • クラスタ単位デフォルトとして登録した default クラス (spec は同一) を明示の nodeSelector で選ぶと、50m / 52Mi (デフォルト側) になる
  • 対照として同時に再現した「nodeSelector を書かずにデフォルト経由で選ばせた Pod」は、どちらの登録でも 50m / 52Mi になる

とくに namespace デフォルトのパターンでは、注入された Pod と明示的に指定した Pod とで、出来上がった spec の nodeSelector は同一でした。 それでも扱いが分かれたということは、GKE は「自分が注入したかどうか」を Pod spec の形とは別のところで区別していることになります。

よって、カスタム ComputeClass は次のような法則で扱いが変わると考えられます:

  • クラスタ単位のデフォルト登録は、クラスそのものをデフォルト側に移す (明示の nodeSelector で選んでも 50m / 52Mi)
  • namespace 単位のデフォルト登録は、クラスの扱いを変えず、namespace デフォルトの注入で選ばれた Pod だけがデフォルト側で扱われる

公式ドキュメントの最小値の表を見ると、クラス側の区分 (「組み込み / クラスタ単位のデフォルト」と「それ以外のカスタム」) は、確かにこの実測と整合しています。 その区分に載らない namespace デフォルトだけが、クラスではなく Pod ごとの選ばれ方で挙動を変えているようです。 GKE の区別は spec の内容ではなく、クラスの区分 (組み込みまたはクラスタ単位デフォルトか、それ以外か) と、後者における Pod ごとの選ばれ方 (namespace デフォルトの注入か、明示の nodeSelector か) にある、ということが今回の検証で観測できました。 (なお、クラスタ単位デフォルトは「default という名前の ComputeClass + クラスタ側のフラグ」の組でしか構成できないため、名前とフラグのどちらが効いているのかまでは切り分けていません)

手動削除とスケールダウン

別の観点として、運用面の挙動も確かめておきます。 まず、カスタム Autopilot ComputeClass が作ったノードプールの手動削除です。 Part 2 で組み込み版のプールが HTTP 400 で拒否されることを見ましたが、カスタム版はどうでしょうか。

$ gcloud container node-pools delete nap-e2-medium-wsvb82l4 \
    --cluster=gke-cc-poc --zone=asia-northeast1-a --quiet
ERROR: (gcloud.container.node-pools.delete) ResponseError:
code=400, message=Autopilot node pools cannot be accessed or modified.

ap-podfamily-custom のプール (e2-medium) も、ap-n2-custom のプール (n2-standard-2 spot) も、組み込み版と同じエラーで拒否されました。 autopilotConfig.enabled: true を持つノードプールは、由来が組み込みかカスタムかを問わず Google の管理下にあるということです。

今度は、スケールダウンの所要時間を計測しました。 workload 削除と同時に計測を始めたカスタム Autopilot のプールは、約 7.7 〜 8.7 分で一覧から消えました (組み込み版のプールは Job 削除の直後から数えて約 7.0 〜 7.2 分)。 今回の計測した限りでは、組み込みの ComputeClass であるかカスタム ComputeClass であるかによって明確な差はないように見えました。 また、サンプル数が少ないため確かなことは言えませんが、Part 1 の Standard 系 (5.6 分〜 15.3 分) よりはばらつきが少ないように見えます。

補足: リソースの削除順序

今回の検証で、ComputeClass をノードプールの削除より先に消してしまったケースが 1 つあり、そのプールの定義だけは 30 分以上一覧に残り続けました。 ノードが稼働していなければ課金対象にはならないため、さほど気にする必要はないかもしれませんが、「workload の削除 → プールの消滅確認 → ComputeClass の削除」という順序で片付けるのが無難と言えそうです。

シリーズ全体の差分整理

3 部にわたって観察した内容を、ComputeClass の系統ごとの差分として一覧にします。

観点 Standard 系 (autopilot なし / Part 1) Autopilot 系: 組み込み / クラスタ単位デフォルト Autopilot 系: その他のカスタム
ノード VM 名のプレフィックス gke-...-nap-... gk3-...-nap-... gk3-...-nap-...
autopilot-managed-node のラベルと taint (無し) あり (組み込みは taint 計 2 個。クラスタ単位デフォルトのプールは compute-class taint なしの計 1 個) あり (taint 計 2 個)
gke-max-pods-per-node (実測) 110 32 32
マシンの選ばれ方 priority の指定どおり (サイズは requests から決定) podFamily は requests に応じたサイズ (今回は e2-medium、デフォルト経由の試行では ek-standard-8 も) 同左。machineFamily 指定時は priority どおり
最小値の mutation (probe 実測) なし (manifest どおり) 50m / 52Mi へ引き上げ (クラスタ単位デフォルトは明示の nodeSelector で選んでも同じ。追試で実測) 500m / 512Mi へ引き上げ (podFamily 系の明示選択で実測。namespace デフォルトの注入で選ばれた Pod のみ 50m / 52Mi 。machineFamily 系は未実測)
ephemeral-storage: 1Gi の付与 (実測) なし requests / limits の両方 (組み込みで実測) podFamily 系は両方、machineFamily 系は requests のみ
課金モデル (公式ドキュメントの分類、課金明細は未実測) Standard 課金 podFamily → Pod-based (machineFamily 系の rule を書く場合は machineFamily → node-based。 priority rule で優先されるため) podFamily → Pod-based、machineFamily → node-based
ノードプール手動削除 可能 HTTP 400 で拒否 HTTP 400 で拒否
Pod 削除後の scale-down 所要 (実測) 5.6 〜 15.3 分 約 7.0 〜 7.2 分 約 7.7 〜 8.7 分

この表では、最小値の行が Autopilot 系の 2 列で分かれています。 同じ podFamily: general-purpose を明示の nodeSelector で選んだ場合で比べると、ノードの外形 (VM 名のプレフィックス、taint、max-pods ラベルなど) も、機種の選ばれ方も、手動削除の拒否も区別がなく、今回明確に観測できた差は Pod の最小サイズでした。 そしてその挙動の差異は spec の書き方ではなく、クラスの区分 (組み込みまたはクラスタ単位デフォルトか、それ以外か) と、それ以外のカスタムにおける Pod ごとの選ばれ方 (namespace デフォルトの注入か、明示の nodeSelector か) によって生まれていました。

おわりに

全 3 回の記事を通じて、ComputeClass を用いてノードプールを自動作成する複数のパターンを実機検証しました。

Part 1 では、「宣言した構成のマシンだけが立ち上がるのか」という問いを立て、(priority を満たせる状況であれば) 指定したとおりの構成でマシンが調達できることを確認しました。 満たせない priority は、試行の痕跡を残さずスキップされ、ScaleUpAnyway の下では default の E2 へ fallback する挙動を観察しました (一方、DoNotScaleUp が Pending を維持することは Part 3 で確認しました)。

Part 2 では、「ノードの管理を Google に任せた場合」の挙動を確かめました。 組み込みの autopilot ComputeClass により、Standard クラスタの中に Autopilot 管理のノードを立て、gk3- プレフィックスや taint、Pod への mutation、DaemonSet の除外といった挙動を観察しました。

Part 3 では、組み込みの ComputeClass とカスタム ComputeClass が GKE からどのように区別されているのかを調査しました。 ノードの外形 (taint, ラベルなど) もマシンファミリーの選ばれ方も両者で同じ結果となる中、Pod が強制されるリソースの最小値だけは、spec の内容ではなく、クラスの区分 (組み込みまたはクラスタ単位デフォルトか) と Pod ごとの選ばれ方 (デフォルト注入か、明示の nodeSelector か) で扱いが分かれていました。

使い分けの指針としては、(一案として) 次のように考えられそうです:

小さな Pod を小さな requests のまま (= Pod あたりの下限を低く) 動かしたいなら、組み込みの autopilot 系か、クラスタ単位のデフォルト登録を使うのが良いでしょう。 namespace 単位のデフォルトも、注入で選ばれる Pod に限れば同じ最小値になりましたが、公式ドキュメント上の位置づけを確認できていないことに加え、登録した namespace の中でも Pod が明示の nodeSelector で選ぶと最小値はカスタム側に戻る点に注意です。

カスタムの podFamily ComputeClass を明示の nodeSelector で選ぶ構成では、(クラスタ単位デフォルトに登録している場合を除き) Pod あたり最小 0.5 vCPU / 0.5 GiB を前提に容量を見積もる必要があります。

特定のマシンファミリーを Autopilot 化したいだけなら、machineFamily 指定のカスタム ComputeClass を用いるのが最も簡単です。

いずれの場合も、クラスタ単位のデフォルト登録では対象 Pod が既存の Standard ノードに配置されるケースがあるため、この点は設計時に考慮しておいたほうが良いでしょう。

今後は podFamily の更なる拡充など、ComputeClass のアップデートがあれば機会を見て検証していきたいと思います。 長々とした記事になってしまいましたが、ご覧いただきありがとうございました。

ComputeClass を用いた GKE Standard のノードプール拡張 (Part 2: Autopilot mode workloads)

前回の Part 1 では、autopilot.enabled を使わない素の ComputeClass を Standard クラスタで動かし、priority の fallback やノードプールの自動削除の挙動を確かめました。 そこで起動したノードは、ComputeClass 用の taint こそ付くものの、中身は普通の Standard ノードであり、管理の主体はユーザ側にありました。

Part 2 では、その管理を Google に託してみます。 組み込みの autopilot ComputeClass を使って、Standard クラスタの中に Autopilot 管理のノードを追加します。 「ノードの管理を Google に任せる」場合、運用負担の軽減など、そのメリットについてはイメージしやすいと思いますが、一方で、結果としてクラスタにどのような変化があり、何が制限されるのかは、実機を見ないと想像しにくいところです。 今回は、この「ノードの管理を手放すと何が変わるのか」の答えを探っていきます。

Autopilot mode workloads とは

About Autopilot mode workloads in GKE Standard には、この機能が次のように説明されています。

You can use ComputeClasses to run Google Kubernetes Engine (GKE) Autopilot workloads in your GKE Standard mode clusters.

Google manages any new nodes that GKE provisions for these workloads, similar to how Google manages the nodes in Autopilot clusters.

まとめると、「クラスタ全体は Standard モードのまま運用しつつ、特定の ComputeClass を経由するワークロードだけを Autopilot 管理のノードに乗せられる」という機能です。

課金モデル

同ドキュメントには、課金モデルについて以下の説明があります。

The Pod-based billing model applies when GKE uses a podFamily priority rule to create nodes for a workload.

The node-based billing model applies when GKE uses a ComputeClass priority rule that explicitly request specific hardware, such as a certain machine family or GPUs.

Autopilot pricing applies only to the workloads and nodes that use an Autopilot ComputeClass.

ComputeClass の priority rule に何を書くか (podFamily か、machineFamily / GPU などの具体的なハードウェア指定か) で、Pod 課金 / ノード課金のどちらが適用されるかが決まる、と整理できます。 本記事で動かす組み込み autopilot ComputeClass は前者 (podFamily) にあたります。 machineFamily を指定するカスタム Autopilot ComputeClass は Part 3 で検証します。

検証環境

クラスタは Part 1 で構築したものと同じです (詳細は Part 1 の「検証環境」を参照ください)。 autopilot.enabled まわりのバージョン要件については、Run workloads in Autopilot mode in Standard clusters に次の記載があります。

To use Autopilot in ComputeClasses, the cluster must run 1.34.1-gke.1829001 or later.

To use podFamily priority rules in custom Autopilot ComputeClasses, the cluster must run 1.35.2-gke.1485000 or later.

検証クラスタは 1.36.0-gke.4447000 で、いずれの要件も満たしています。

Part 1 と同様、計測値はあくまで参考程度とお考えください。

組み込み ComputeClass の中身

組み込みの Autopilot ComputeClass は、クラスタ作成直後から kubectl get computeclass で確認できます。

$ kubectl get computeclass
NAME                 AGE
autopilot            2m25s
autopilot-arm        2m25s
autopilot-arm-spot   2m25s
autopilot-spot       2m25s

x86 向けの autopilot / autopilot-spot に加えて、Arm アーキテクチャ向けの autopilot-arm / autopilot-arm-spot も用意されています (Arm 系は Run workloads in Autopilot mode in Standard clusters の Limitations にバージョン要件の記載があります)。 本記事の検証で使うのは autopilot です。

$ kubectl get computeclass autopilot -o yaml
...
spec:
  activeMigration:
    optimizeRulePriority: true
  autopilot:
    enabled: true
  autoscalingPolicy:
    consolidationDelayMinutes: 1
    consolidationThreshold: 85
    gpuConsolidationThreshold: 85
  description: Provides general-purpose Autopilot compute.
  nodePoolAutoCreation:
    enabled: true
  priorities:
  - podFamily: general-purpose
  whenUnsatisfiable: DoNotScaleUp

priority は podFamily: general-purpose の 1 つだけです。 Part 1 で見た priority rule は machineFamily や machineType でハードウェアを指名するものでしたが、podFamily は毛色が違います。 Run workloads in Autopilot mode in Standard clusters では次のように説明されています。

priorities.podFamily : uses the podFamily priority rule to run Pods on the Autopilot container-optimized compute platform.

ハードウェアを指名する代わりに、Pod を Autopilot 側の "container-optimized compute platform" で動かすことを指定する priority rule です。 container-optimized compute platform 自体は Autopilot overview に、動作中に動的にリサイズできる Autopilot ノードからなり、Pod 数や resource consumption に応じて GKE 側がキャパシティを自動調整するプラットフォーム、と説明されています。

値の general-purpose については、次の記載があります。

General-purpose workloads: use one of the built-in Autopilot ComputeClasses, which place Pods on the container-optimized compute platform.

The general-purpose option is recommended for most production workloads that don't require specific hardware to run well. It supports both x86 and Arm architectures.

「特定のハードウェア要件を持たない汎用ワークロード」を意味する値のようです。 podFamily に指定できる値としてはこのほかに、Arm 向けの general-purpose-arm が Limitations に記載されています。 本記事の検証では general-purpose のみを使っています。

whenUnsatisfiable は DoNotScaleUp です。

DoNotScaleUp: Leave the Pod in the Pending status until a node that meets the ComputeClass requirements is available.

priority を満たせない場合に fallback のノードを立てるのではなく、Pod を Pending のまま保持する設定で、Part 1 で使った ScaleUpAnyway とは逆の方針が選ばれています。

ちなみに autopilot-spot の spec もほぼ同じで、priorities に spot: true が追加されているだけでした。

組み込み autopilot ComputeClass で Job を流す

この ComputeClass を nodeSelector に指定して、Job を実行します。 コンテナは python:3.12-slim で 900 秒 sleep するだけのもので、resources は requests: cpu 500m / memory 512Mi (limits も同値)、1 Pod です。

apply 後、Pod は約 114 秒で Pending → Running になりました。 立ち上がったノードを確認します。

$ kubectl get pods -l job-name=batch-builtin-autopilot -o wide
NAME                            ...   NODE
batch-builtin-autopilot-gxbmx   ...   gk3-gke-cc-poc-nap-e2-medium-1kz4sfeo-1f36dc0b-89nw

$ gcloud container node-pools list --cluster=gke-cc-poc --zone=asia-northeast1-a
NAME                             MACHINE_TYPE   ...
default-pool                     e2-medium      ...
nap-e2-medium-1kz4sfeo           e2-medium      ...

ノード VM 名のプレフィックスが、Part 1 で見てきた gke- から gk3- に変わっています。 これは公式にも Autopilot 管理の目印として明記されています。

In this output, the gk3- prefix in the Node column indicates that the node is managed by Autopilot.

一方で、ノードプール名は nap-e2-medium-1kz4sfeo で、プレフィックスは Part 1 の自動作成ノードプールと同じ nap- のままです。 つまり gk3- が付くのはノード VM 名だけで、ノードプール名からは Autopilot 管理かどうかを判別できません。 ノードプール側での判別には、後述の autopilotConfig.enabled フィールドが使えます。

マシンタイプは e2-medium でした。 priority は podFamily: general-purpose だけでマシンファミリーを指定していないため、Part 1 で見た「pending Pod の requests に応じてサイズを選ぶ」動きに従って、今回の要求 (cpu 500m / memory 512Mi × 1 Pod) に見合う小さなマシンが選ばれた、と考えられます。 なお、2026 年 5 月頃に同様の検証した際は、ここで ek-standard-16 という Autopilot 専用のマシンシリーズ (公式には container-optimized compute platform のノードで「表示されることがある」とされる、E2 ベースの専用シリーズ) が引かれていました。 今回の検証では、組み込み autopilot 経由の試行で ek は現れませんでしたが、別の経路で現れた例を Part 3 で取り上げます。

Standard クラスタにおける Autopilot ノードの特徴

立ち上がった Autopilot ノードを、Part 1 の basic-n2 で立った autopilot=false のノードと比べます。 まずラベルです。 代表的なものを抜粋します。

ラベル basic-n2 (autopilot=false / Part 1) autopilot (built-in / Part 2)
cloud.google.com/compute-class basic-n2 autopilot
cloud.google.com/autopilot-managed-node (無し) true
cloud.google.com/machine-family n2 e2
cloud.google.com/gke-max-pods-per-node 110 32
cloud.google.com/gke-image-streaming (無し) true
cloud.google.com/gke-gcfs (無し) true

autopilot-managed-node: true をはじめ、image streaming (gke-image-streaming) や GCFS (gke-gcfs) など、Autopilot 化に伴って有効になる要素が並びます。 gke-max-pods-per-node は 110 から 32 に変わっています。

taint も増えていました。

(autopilot=false / Part 1 basic-n2)
- cloud.google.com/compute-class=basic-n2:NoSchedule    (1 個)

(autopilot=true / built-in autopilot)
- cloud.google.com/autopilot-managed-node=true:NoSchedule
- cloud.google.com/compute-class=autopilot:NoSchedule
                                                         (2 個)

ComputeClass 用の taint に加えて、cloud.google.com/autopilot-managed-node=true:NoSchedule が付与されています。

ノードプール定義の側にも違いがあります。 gcloud container node-pools describe で取得すると、autopilotConfig.enabled: true というフィールドが入っていました。 Part 1 の autopilot=false なノードプールには、このフィールドはありません。

ノードの allocatable は次のとおりでした。

$ kubectl describe node gk3-gke-cc-poc-nap-e2-medium-1kz4sfeo-1f36dc0b-89nw | grep -A 7 'Allocatable:'
Allocatable:
  cpu:                940m
  ephemeral-storage:  47060071478
  memory:             2825844Ki
  pods:               32

pods の上限が、ラベルのとおり 32 になっています (Part 1 の Standard 系ノードは 110)。

まとめると、Autopilot 管理かどうかの判別には、公式に目印として明記されているノード VM 名の gk3- プレフィックスが使えます。 加えて今回の観測の範囲では、ノードのラベルと taint の autopilot-managed-node、ノードプールの autopilotConfig.enabled も一貫して判別に使えました。 ノードプール名の nap- プレフィックスは判別には使えません。

Pod spec への mutation

Autopilot にノード管理を任せると、ノードだけでなく Pod の spec にも手が入ります。 Resource requests in Autopilot には次の記載があります。

If your requests are less than the minimum, Autopilot automatically modifies your workload configuration to bring your requests within the allowed range.

この「最小値」は一律ではなく、Pod bursting に対応するクラスタかどうかで変わります。 general-purpose の組み込み ComputeClass の場合、bursting 対応クラスタで CPU 50m / Memory 52 MiB、非対応クラスタで CPU 250m / Memory 512 MiB です。 非対応クラスタではさらに、Pod の limits が requests と等しくなるよう調整されます。

では、Standard クラスタ × Autopilot mode workloads という今回の構成は、どちらの扱いになるのでしょうか。 この組み合わせの bursting に言及した記述は、確認した限り見つけられませんでした。 そこで、意図的に最小値以下の requests (cpu: 10m / memory: 16Mi、limits なし) を持つ Pod を、組み込み autopilot ComputeClass でデプロイしてみました。 結果、requests は次のようになりました。

{
  "limits": {
    "ephemeral-storage": "1Gi"
  },
  "requests": {
    "cpu": "50m",
    "ephemeral-storage": "1Gi",
    "memory": "52Mi"
  }
}

cpu / memory は 50m / 52Mi に引き上げられ、cpu / memory の limits は設定されていません。 bursting 対応クラスタ側の値です。 Pod bursting in GKE - Availability in GKE の記載とも整合するため、GKE Standard × Autopilot mode workloads の構成でも bursting 対応クラスタの扱いになると考えて良さそうです。

もうひとつ、上の出力にはマニフェストに書いていない ephemeral-storage: 1Gi が入っています。 これは Default resource requests で「All other containers: Ephemeral storage: 1 GiB」と定義されている default 値の付与で、冒頭の Job (500m / 512Mi、limits あり) でも requests / limits の両方に同じ値が追加されていました。 このように Autopilot 配下では manifest と実機の Pod spec が一致しなくなることがあるため、実機の値を確認したい場合は kubectl get pod ... -o yaml などで取得する運用になります。

DaemonSet の配置

ノードに taint が 2 つ付くとなると、気になるのは DaemonSet の扱いです。 toleration を指定しない通常の DaemonSet (alpine:3、requests: cpu 10m / memory 16Mi) を apply して、45 秒後の様子を見ます。

$ kubectl get ds ds-test -o wide
NAME      DESIRED   CURRENT   READY   ...   NODE SELECTOR
ds-test   1         1         1       ...   <none>

このとき、この検証セッションのクラスタには 5 ノード (default-pool の 1 台、Part 1 と同構成の ComputeClass 由来の 3 台、Autopilot 管理の gk3- 1 台) が動いています。 toleration を持たない DaemonSet なら本来「全ノードに 1 個ずつ」になりそうなところ、DESIRED=1 で、default-pool 以外の 4 台がそもそもカウントされていません。

これは Autopilot 特有の挙動ではなく、Kubernetes の DaemonSet コントローラの仕様から説明できます。 DaemonSet コントローラはノードごとに taint を tolerate できるかを判定し、Pod が tolerate しない NoSchedule taint を持つノードを DESIRED の母数から除外します。 Autopilot ノードの 2 つの taint も、Part 1 で見た非 Autopilot な ComputeClass ノードの compute-class taint も、この DaemonSet は tolerate できないため、4 台まとめて DESIRED から外れた、と考えられます。

運用面では、ここが ComputeClass 導入時の注意点になります。 監視、ログ収集、セキュリティなどの目的で「全ノードに 1 個ずつ」を前提に DaemonSet を運用している場合、ComputeClass の利用が広がると (Autopilot の有無を問わず)、それらのカバレッジから ComputeClass 由来のノードが外れることになります。 導入するなら、事前に方針を決めておきましょう。 Autopilot ノードにも配置するなら、少なくとも 2 つの taint を tolerate する必要があります (今回確認したのは toleration なしの場合のみで、toleration を付けた場合に実際に配置されるかまでは検証していません)。 加えて、toleration だけでは、意図しない Autopilot ノードにまで配置が広がりうるため、対象を絞る nodeAffinity や nodeSelector、Autopilot 側のワークロード制約に抵触しないかの確認もあわせて必要です。 逆に配置しないなら、Autopilot ノードは当該 DaemonSet の監視対象外とする、などの運用整理を明文化しておくと良いでしょう。

ちなみに、kube-system 配下の DaemonSet については、Autopilot ノードもカバーされるように設計されています。 検証時に gk3- ノード上の Pod を確認すると、gke-metadata-server / netd / kube-proxy など、kube-system の DaemonSet 群が乗っていました。 ログ収集は fluentbit-gke (default-pool 用) と fluentbit-gke-managed-node-small (Autopilot ノード用) のように DaemonSet 自体が分かれており、「Autopilot ノードを除外する一般 DaemonSet」と「Autopilot ノード専用 DaemonSet」の組み合わせでカバレッジを成立させているようです。

ノードプールの手動削除

最後に、Autopilot 管理のノードプールを gcloud container node-pools delete で直接消そうとするとどうなるかを試します。 対象は、組み込み autopilot で立った nap-e2-medium-1kz4sfeo です (autopilotConfig.enabled: true を持ちます)。

$ gcloud container node-pools delete nap-e2-medium-1kz4sfeo \
    --cluster=gke-cc-poc --zone=asia-northeast1-a --quiet
ERROR: (gcloud.container.node-pools.delete) ResponseError:
code=400, message=Autopilot node pools cannot be accessed or modified.

HTTP 400 で、明確に拒否されました。 Autopilot 管理のノードプールは、ユーザからある程度可視ではあるものの、Autopilot クラスタのノードと同じく、あくまで Google の管理下にあるということがわかります。

おわりに

今回の Part 2 では、冒頭の「ノードの管理を手放すと何が変わるのか」という問いに対して、実機検証からその答えを探りました。 調達されるノードは gk3- プレフィックスの Autopilot 管理ノードになり、taint とラベルが増え、Pod の spec には mutation が入り、toleration のない DaemonSet はそのノードをデプロイ対象から除外します。 また、Autopilot ノードは Google の管理下にあるため、ノードプールは自分では消せなくなりました。

今回は、あらかじめ用意されている組み込みの ComputeClass を使って検証しましたが、autopilot.enabled: true はカスタムの (ユーザーが独自に定義した) ComputeClass にも付与できます。 組み込み版と同じ設定を、このユーザー定義の ComputeClass に追加した場合、同じ結果が得られるのでしょうか。 Part 3 では、カスタム Autopilot ComputeClass を実際に適用し、組み込みの ComputeClass との違いを調査します。

ComputeClass を用いた GKE Standard のノードプール拡張 (Part 1: ComputeClass の基本動作)

GKE には ComputeClass という Custom Resource があり、ワークロードに使うマシン構成の優先順位とフォールバック (fallback) を宣言的に定義できます。 ComputeClass は、Pod に選ばせるノード構成のプロファイル (priorities と fallback、オートスケーリング設定の集合) であり、nodePoolAutoCreation.enabled: true を指定したときだけ、条件に合うノードプールの自動作成が有効になります。 この自動作成を使うと、「第一希望は spot の N2、調達できなければ on-demand の N2」といったように希望する構成を並べておくだけで、ノードプールの作成から不要になったあとの削除まで、ワークロードに応じたノードのプロビジョニングを GKE に任せられます。 (なお、手動で作ったノードプールに cloud.google.com/compute-class=<名前> のラベルと taint を付けて紐付ける使い方もありますが、本シリーズでは自動作成 (node pool auto-creation) を使う構成を扱います)

こう聞くと、「宣言した構成のマシンだけが立ち上がるのか」と捉えてしまいそうですが、例えば priority に並べた構成がいずれも調達できなかったとき、クラスタには何が起きるのでしょうか。 また、宣言した構成以外のマシンが起動したことに、運用者は気付けるのでしょうか。 公式リファレンス (About custom ComputeClasses in GKE) を読んだだけでは実機の挙動を想像しにくいところがあったため、検証用クラスタを立ててひととおり確かめてみました。

本シリーズは全 3 部の予定です。 Part 1 となる本記事では、標準的な ComputeClass (autopilot.enabled なし) の挙動を確かめます。 ComputeClass には、Standard クラスタの中で特定のワークロードだけを Autopilot mode で動かす構成 (Autopilot mode workloads) もありますが、こちらについては Part 2 以降で扱います。

ComputeClass とは

ComputeClass は GKE の Custom Resource (apiVersion: cloud.google.com/v1, kind: ComputeClass) です。 priorities フィールドに使いたいマシン構成を優先順に並べ、whenUnsatisfiable フィールドで、どの priority も満たせなかった場合の挙動を指定します。 About custom ComputeClasses in GKE にあるとおり、priority rule のトップレベルのプロパティには machineFamily / machineType / gpu / tpu などがあり、spot / minCores / minMemoryGb といったフィールドを追加で組み合わせて絞り込めます (このほかに Autopilot mode 専用の podFamily もありますが、Part 2 で扱います)。

また、spec には priority とは別に autopilot.enabled というフィールドがあり、これを true にすると、その ComputeClass を指定したワークロード用に Autopilot mode のノードがプロビジョニングされるようになります (Run workloads in Autopilot mode in Standard clusters のとおり、GKE 1.34.1-gke.1829001 以降が必要)。 組み込みの autopilot 系 ComputeClass では、このフィールドがデフォルトで有効になっています。

検証環境

検証用に新規プロジェクトを用意し、zonal Standard クラスタを 1 つ作成しました。

項目 値
Region / Zone asia-northeast1-a
Cluster Standard, zonal
Release channel rapid
GKE version (実測) 1.36.0-gke.4447000
Default node pool default-pool, e2-medium × 1, taint なし
その他 --enable-ip-alias (VPC-native), Workload Identity 有効

クラスタ作成は gcloud container clusters create の標準的なオプションのみで行い、--enable-autoprovisioning (cluster-wide NAP) は付けていません。 Configure node auto-provisioning には

To enable node pool auto-creation for a ComputeClass in GKE versions earlier than 1.33.3-gke.1136000, you must also enable cluster-level node auto-provisioning.

とあり、検証クラスタの 1.36.0-gke.4447000 はこのバージョン要件を満たすため、ComputeClass 単位の nodePoolAutoCreation.enabled: true だけで自動プロビジョニングを行えます。

なお、本記事に登場する公式ドキュメントの引用は、記事執筆時点 (2026 年 7 月) のものです。 計測値や起動したマシン構成は、検証環境で観測された一例であり、あくまで参考値とお考えください。

Dataplane V2 は必要か

GKE Dataplane V2 にあるとおり、GKE 1.22 以降の Autopilot クラスタでは Dataplane V2 がデフォルトで有効になっています。 そのため、検証前は、Standard クラスタの中で Autopilot mode のワークロードを動かす場合も Dataplane V2 の有効化が必要になるのでは、と考えていました。

しかし、Run workloads in Autopilot mode in Standard clusters の Limitations で Dataplane V2 に触れているのは、次の一文だけでした。

Calico network policy enforcement isn't supported. You must use GKE Dataplane V2 or disable network policy enforcement.

Autopilot mode を使うこと自体の要件として Dataplane V2 が挙げられているわけではなく、NetworkPolicy の enforcement を使いたい場合に Calico が使えないため、Dataplane V2 を使うか enforcement を無効にするか、という選択になる制約です。 本検証は NetworkPolicy を使わないため、Dataplane V2 は指定していません。

基本動作の確認 (basic-n2)

まずはユーザ定義の ComputeClass を 1 つ作って動かします。 priority に machineFamily: n2 を spot / on-demand の 2 段で並べ、whenUnsatisfiable: ScaleUpAnyway を指定した構成です。

apiVersion: cloud.google.com/v1
kind: ComputeClass
metadata:
  name: basic-n2
spec:
  priorities:
  - machineFamily: n2
    spot: true
  - machineFamily: n2
    spot: false
  nodePoolAutoCreation:
    enabled: true
  whenUnsatisfiable: ScaleUpAnyway
  activeMigration:
    optimizeRulePriority: true

spec の activeMigration.optimizeRulePriority: true は、起動時点で上位の priority の構成が調達できずに下位の priority で起動したノードを、(上位の priority の構成が調達可能になり次第) 能動的に上位の priority の構成に置き換えることを許可する設定です (About custom ComputeClasses in GKE 参照)。

ワークロードは、この ComputeClass を nodeSelector で指定した Deployment (nginx, replicas: 2, requests: cpu 200m / memory 256Mi) です。 apply 後、Pod は約 82 秒で Pending → Running になりました。

立ち上がったノードを確認します。

$ kubectl get pods -l app=cc-basic-app -o wide
NAME                            ...   NODE
cc-basic-app-554867d8dc-4cd8s   ...   gke-gke-cc-poc-nap-n2-standard-2-spot-74d607d0-q586
cc-basic-app-554867d8dc-qtps7   ...   gke-gke-cc-poc-nap-n2-standard-2-spot-74d607d0-q586

$ kubectl get nodes -L cloud.google.com/compute-class,cloud.google.com/machine-family,cloud.google.com/gke-spot
NAME                                                  ...   COMPUTE-CLASS   MACHINE-FAMILY   GKE-SPOT
gke-gke-cc-poc-nap-n2-standard-2-spot-74d607d0-q586   ...   basic-n2        n2               true

$ gcloud container node-pools list --cluster=gke-cc-poc --zone=asia-northeast1-a
NAME                             MACHINE_TYPE   ...
default-pool                     e2-medium      ...
nap-n2-standard-2-spot-quy0yl24  n2-standard-2  ...

priority 1 (machineFamily: n2, spot: true) のとおり、n2-standard-2 の spot ノードプールが自動作成され、そこに 2 Pod が乗りました。 ノードには cloud.google.com/compute-class: basic-n2 と cloud.google.com/machine-family: n2 の 2 つのラベルが付き、ComputeClass の名前と実際のマシンファミリーが揃っています。

machineFamily だけ指定して machineType を指定しない場合のサイズの選ばれ方については、About custom ComputeClasses in GKE に次の記載があります。

When you use the machineFamily field, GKE provisions nodes from that series with a machine type that is large enough to run your Pods. The autoscaler algorithm determines the most appropriate size based on the aggregate resource requests of all pending Pods.

今回のリクエスト (cpu: 200m / memory: 256Mi × 2 Pod) を満たすサイズとして n2-standard-2 (2 vCPU / 8 GB) が選ばれたことは、この記載と整合していそうです。 ただし、N2 ファミリーには、より小さいメモリ構成の n2-highcpu-2 (2 vCPU / 2 GB) もあるため、厳密に「ファミリー内で最小のマシンが選ばれる」とも限らないようです。

ノードの taint と Pod への toleration

自動作成されたノードプールのノードには、cloud.google.com/compute-class=basic-n2:NoSchedule という taint が付与されていました。 一方で、ワークロードのマニフェストに toleration は書いていません。 それでも Pod がこのノードに乗れているのは、対応する toleration が Pod 側に自動挿入されているからです。 kubectl get pod ... -o jsonpath='{.spec.tolerations}' を確認すると、次の内容が入っていました。

{
  "effect": "NoSchedule",
  "key": "cloud.google.com/compute-class",
  "operator": "Equal",
  "value": "basic-n2"
}

kubectl apply --dry-run=client -o yaml の出力と apply 後の kubectl get pod ... -o yaml を比べると、後者にだけこの toleration が追加されており、GKE が nodeSelector: cloud.google.com/compute-class: <ComputeClass 名> に対応する toleration をサーバ側で自動追加していることがわかります。 切り分けのため、同じ nodeSelector を持つ素の Pod を --dry-run=server で送ってみると、応答にこの toleration は現れませんでした。 mutating admission は server-side dry-run でも実行されるため、admission での注入ではなく、(断定はできませんが) Pod 作成後にコントローラが付与している可能性が高そうです。

逆に、ComputeClass を指定しない通常の Pod を同じクラスタに deploy して spec を見ると、compute-class の toleration は入っていませんでした。 toleration を自分で書かず、注入もされない Pod は、この NoSchedule taint によって自動作成されたノードプールから弾かれます。 よって、ユーザは明示的に toleration を書く必要がなく、nodeSelector で ComputeClass を指定さえすれば、対象の Pod を適したノードプールに乗せることができるようになっています。

priority の中で fallback する場合 (basic-fallback-n2)

basic-n2 では、priority 1 のとおりにノードが立ちました。 では、priority 1 が調達できない構成だった場合、priority 2 への切り替えはどのように起きるのでしょうか。

もうひとつ ComputeClass を用意して試します (便宜的に basic-fallback-n2 と呼びます)。 priority 1 に存在しない machineType (n2-standard-99999) を置き、priority 2 に machineFamily: n2 を置いた構成です。

apiVersion: cloud.google.com/v1
kind: ComputeClass
metadata:
  name: basic-fallback-n2
spec:
  priorities:
  - machineType: n2-standard-99999
  - machineFamily: n2
  nodePoolAutoCreation:
    enabled: true
  whenUnsatisfiable: ScaleUpAnyway

なお、この ComputeClass には activeMigration を入れていないため、basic-n2 と spec が完全に揃った比較ではありません。

apply 後、Pod は約 67 秒で Pending → Running になりました。 basic-n2 の約 82 秒と同水準で、priority 1 で足止めされた気配がありません。 events を見ます。

$ kubectl describe pod -l app=cc-fallback-app | grep -A 14 'Events:'
Events:
  Normal   TriggeredScaleUp  cluster-autoscaler  Pod triggered scale-up:
    [{...nap-n2-standard-2-1pyhxgx0-temporary-mig-... 0->1 (max: 1000)}]
  Warning  FailedScheduling  default-scheduler   0/3 nodes are available: ...
  Normal   Scheduled         default-scheduler   ... gke-...-nap-n2-standard-2-1pyh-...

priority 1 の n2-standard-99999 に対する TriggeredScaleUp はそもそも記録されておらず、最初から priority 2 (machineFamily: n2) の scale-up が走っています (FailedScheduling はノード起動を待つ間の通常のイベントです)。 priority 1 は「試して失敗した」のではなく、試行の痕跡を残さずスキップされた、と読み取れます。

どの priority も満たせない場合 (basic-m2)

では、priority に並べた構成がすべて調達できなかったら、何が立つのでしょうか。

この状況を意図的に作るために、quota が 0 のマシンファミリーを使います。 検証プロジェクトでは M2 ファミリー (メモリ最適化) の CPU quota が 0 でした。

$ gcloud compute regions describe asia-northeast1 --format=yaml | grep -B1 -A1 'metric: M2_CPUS'
- limit: 0.0
  metric: M2_CPUS
  usage: 0.0

m2 のマシンタイプ自体は asia-northeast1-a で提供されており (gcloud compute machine-types list で確認)、quota が 0 である以上、spot / on-demand のどちらの priority も満たせない状況を意図的に作れることになります。 この M2 を priority に 2 段 (spot / on-demand) で並べた ComputeClass basic-m2 を用意し、basic-n2 と同じ構成のワークロードを apply します。

apiVersion: cloud.google.com/v1
kind: ComputeClass
metadata:
  name: basic-m2
spec:
  priorities:
  - machineFamily: m2
    spot: true
  - machineFamily: m2
    spot: false
  nodePoolAutoCreation:
    enabled: true
  whenUnsatisfiable: ScaleUpAnyway
  activeMigration:
    optimizeRulePriority: true

Pod は約 89 秒で Pending → Running になりました。 何が立ったのかを確認します。

$ kubectl get pods -l app=cc-m2-app -o wide
NAME                         ...   NODE
cc-m2-app-54df8df9c9-68b5q   ...   gke-gke-cc-poc-nap-e2-standard-2-1bw7-d4923926-z5tf
cc-m2-app-54df8df9c9-vnnxq   ...   gke-gke-cc-poc-nap-e2-standard-2-1bw7-d4923926-z5tf

$ kubectl get nodes -L cloud.google.com/compute-class,cloud.google.com/machine-family
NAME                                                  ...   COMPUTE-CLASS   MACHINE-FAMILY
gke-gke-cc-poc-nap-e2-standard-2-1bw7-d4923926-z5tf   ...   basic-m2        e2

マシンファミリーは m2 ではなく e2 です。 ノードプール名も nap-e2-standard-2-... で、priority に書いたどの構成とも違うマシンが立っています。 basic-n2 で揃っていた compute-class と machine-family の 2 ラベルがここでは食い違っています。

この e2-standard-2 はどこから来たのでしょうか。 これは whenUnsatisfiable: ScaleUpAnyway の挙動によるものです。 About custom ComputeClasses in GKE の ScaleUpAnyway の説明には、今回の構成 (node pool auto-creation を使う Standard クラスタ) に関する記載があります。

In Standard clusters that use node pool auto-creation, GKE might create a new node pool that uses the default E2 machine series to place the Pod.

このとおり、priority をすべて満たせなかった結果として default の E2 シリーズの新規ノードプールが作られ、サイズは今回のリクエスト (cpu 200m / memory 256Mi × 2 Pod) を満たす e2-standard-2 になったようです。

events に記録されていた scale-up は、最初から fallback 先でした。

$ kubectl get events --sort-by=.lastTimestamp | grep -iE "scale|quota"
... TriggeredScaleUp  pod/cc-m2-app-...  Pod triggered scale-up:
    [{...nap-e2-standard-2-1bw7fz62-temporary-mig-... 0->1 (max: 1000)}]

m2 系のインスタンスグループへの TriggeredScaleUp は記録されておらず、scale-up の失敗を示す FailedScaleUp もありません。 Cloud Audit Log で compute.instances.insert のエラーを検索しても、結果は空でした。 確認した限り (Pod の events, insert 系のエラー監査ログ) では、m2 を調達しようとした痕跡がなかったため、autoscaler が API を呼び出す前に不適合と判定した可能性が高そうです。 (今回は、リソース枯渇を擬似再現しようとしたため上記のような結果となっていますが、quota が 1 以上の (実在する) machineType が本当にリージョン/ゾーンで枯渇している場合には、また違った挙動になってくるかもしれません)

さて、この fallback の痕跡はどこにも残らないのでしょうか。 kubectl から見える範囲にはありませんでしたが、cluster autoscaler が Cloud Logging に出力する visibility イベント (View cluster autoscaler events。Kubernetes の events とは別系統のログ) には、cc-m2-app の Pod 群を対象にした noScaleUp イベントが記録されていました。 観測したイベントの該当部分 (payload) は次のとおりです。

"napFailureReasons": [
  {
    "messageId": "no.scale.up.nap.pod.zonal.failing.predicates",
    "parameters": [
      "asia-northeast1-a",
      "expansion options filtered out and no longer considered"
    ]
  }
]

napFailureReasons は、その Pod グループのために NAP が新しいノードプールをプロビジョニングできない理由を示すフィールドです。 parameters に具体的な述語名はなく、m2 や quota の記載もありませんが、「NAP の候補が絞り込みの段階で除外された」ことは読み取れます。 これは、前段の「API を呼び出す前に不適合と判定した」という見立てとも整合します。

上記のとおり、ある程度は特定が可能なものの、現状、具体的にどのような fallback が起きたのかを示すログやイベントは出力されないように見えます。 今回は ComputeClass 名がたまたま basic-m2 だったため、compute-class ラベルと machine-family ラベルを見比べるだけで食い違いに気付けましたが、ComputeClass 名とマシンファミリー名は本来照合できる値ではありません (たとえば cost-optimized のような名前では、一致も不一致も定義できません)。

fallback の検知を運用に組み込むなら、ComputeClass の priorities の内容と、実ノードの machine-family / gke-spot などのラベルを照合する必要がありそうです (前述の visibility ログの noScaleUp イベントも手がかりにはなりますが、best-effort かつスロットリングありと明記されているため、これ単独での検知には向きません)。

ノードプールの自動削除

ワークロードを消した場合、自動作成されたノードプールはどれくらいで消えるのでしょうか。 ここまでの検証で残っている Deployment をすべて kubectl delete し、gcloud container node-pools list を 30 秒間隔でポーリングして、各ノードプールが一覧から消えるまでの時間を計測しました。

Pool machineType 由来 Pod 削除 → pool が一覧から消えるまで
nap-e2-standard-2-1bw7fz62 e2-standard-2 basic-m2 の fallback 約 5.6 分
nap-n2-standard-2-1pyhxgx0 n2-standard-2 basic-fallback-n2 約 13.8 分
nap-n2-standard-2-spot-quy0yl24 n2-standard-2 (spot) basic-n2 約 15.3 分

ノード削除のタイミングが autoscaling profile に依存することや、autoscalingPolicy.consolidationDelayMinutes で調整できることは About custom ComputeClasses in GKE に記載がありますが、既定の所要時間やエンドツーエンドの目安の記載は見つけられませんでした。 今回の計測では 5 分台から 15 分台まで、それなりに大きいばらつきが観測されています。

補足: ComputeClass の削除について

今回は「workload を削除し、プールが消えるのを待ってから ComputeClass を削除する」という順序で片付けたところ、すべてのプールが自然に消えました。 一方、別の検証で ComputeClass をプールの削除より先に消したケースでは、プール定義が長時間残り続ける挙動を観測しています (Part 3 で触れます)。 ComputeClass のリソースを削除する際は、workload → プールの削除確認 → ComputeClass の削除、の順が無難そうです。

おわりに

今回の Part 1 では、冒頭に「宣言した構成のマシンだけが立ち上がるのか」という問いを立てました。 priority を満たせる状況では、指定した構成のマシン (spot の N2) の調達から、taint と toleration の自動挿入による排他制御まで、宣言したとおりに機能することが確認できました。 一方、quota が 0 のマシンファミリーをあえて指定した basic-m2 では、ScaleUpAnyway の指定によって default の E2 シリーズ (e2-standard-2) への fallback が起きることを確認できましたが、その詳細がログやイベントからはやや追いにくい現状も明らかになりました。

今回の検証で起動したノードはいずれも、taint こそ付いているものの、Standard クラスタの一般的なノードでした。 ノードプールを自分で消すこともできますし、管理の主体はあくまでユーザ側にあります。 ComputeClass にはもうひとつ、autopilot.enabled というフィールドがありました。 これを有効にすると、立つノードは Google の管理下に移ります。 Standard クラスタであることを維持しながら、ノードの管理を手放すという、一見矛盾したようなこの構成では、具体的に何が変わるのでしょうか。 Part 2 では、組み込みの autopilot ComputeClass を使って、その仕組みと挙動を確認します。

Agent Identity を用いたエージェント毎のきめ細かい権限制御

Agent Identity は、AI エージェントに固有の ID を与え、その ID で他のリソースに対して安全に認証するための仕組みです。 Agent Identity 本体は GA しているものの、関連の gcloud コマンドがまだ alpha / beta であったり、誤解を招くような API があったりと、現時点では利用時に注意しておきたいポイントがいくつか見受けられます。

今回は、エージェントが (1) Google Cloud のリソースに、(2) 外部システムに、それぞれ「誰として・どうやって」アクセスを実現しているのか、という観点で、実機検証の結果を交えて整理してみたいと思います。

Agent Identity とは何を解決するものか

エージェントは自律的にタスクの解決プロセスを考え、Google Cloud のリソース、MCP サーバ、外部 SaaS、そして別のエージェントなど様々な相手にアクセスします。

このとき問題になるのが、そのエージェントは「誰」のつもりで認証するのか、ということです。 従来は 1 つのサービスアカウントを複数のエージェントで共有するケースも少なくなかったかと思います。 しかし、サービスアカウントを共有する場合、実際には「どのエージェントが何をしたか」を追いづらい、個々のエージェントにとって必要のない権限が付与されてしまっている、といった問題がありました。 また、エージェントによるリソースへのアクセスは、エージェント自身の権限で行われる場合と、ユーザーの権限を委任されて行われる場合がありますが、サービスアカウントが用いられる場合は (アプリケーションのログがあれば話は別ですが、少なくとも Cloud Audit Logs のみでは) これらの区別がつけられません。

そうした問題を解決するために登場したのが Agent Identity です。 公式ドキュメント(Agent Identity overview)では、Agent Identity の役割を次のように説明しています。

Agent Identity provides a strongly attested, cryptographic identity for each agent that is based on the SPIFFE standard. With Agent Identity, your agent can securely authenticate to MCP servers, cloud resources, endpoints, and other agents, acting either on its own behalf or on behalf of an end user.

つまり Agent Identity は、ざっくり言うと「エージェントごとに固有の身元情報 (SPIFFE ID + X.509) を与え、その ID でエージェントが Google Cloud / 外部 / 別エージェントに対して、エージェント自身として、あるいはユーザの代理として認証できるようにし、その行動を監査可能にする」ための仕組みです。

(注:厳密には、IAM プリンシパルとして機能する SPIFFE ID を発行する Agent Identity と、エージェントが外部システムにアクセスするための認証情報の保管やトークン取得の仲介を行う IAM Connectors は別の API です (前者は Google Cloud リソースへの認証に用いる一方、後者は外部システムへの認証に用いる) 。が、上記ではいずれもエージェントの認証に関わる機能として広義の Agent Identity に含めて扱っています)

検証の前提

今回の実機検証の記録は、2026 年 6 月時点のものです。 リージョンは asia-northeast1 を利用しています。

現状、Agent Identity 本体、Agent Runtime 連携、Agent Identity auth manager / IAM Connectors などの各機能について、一部は GA しており、一部はプレビュー段階であるなど、ローンチのステージが混在しています。 特に外部リソースの認証に使う Agent Identity auth manager / 2-legged OAuth 周辺は API がプレビュー扱いのため、コマンド体系や挙動は今後変わる可能性があります。

SPIFFE ID で Google Cloud リソースへアクセスする

Google Cloud リソースへのアクセスを per-agent な権限制御で行うには、エージェントの SPIFFE ID (spiffe://...) から導出される IAM プリンシパル (principal://... 形式、以下「エージェント ID」) を使用します。 エージェント ID は IAM プリンシパルとして機能するため、IAM バインディングでエージェント ID 毎に必要最低限の権限を付与すれば良い、ということになります。

Agent Runtime にデプロイする場合、既定では Google マネージドなサービスエージェントの権限が用いられます (後述の補足を参照) 。 なので、これをエージェント ID に切り替えるには、デプロイ時に identity_type=AGENT_IDENTITY を指定します。

agent_engine = client.agent_engines.create(
    agent=MyAgent(),
    config=types.AgentEngineConfig(
        identity_type=types.IdentityType.AGENT_IDENTITY,  # ← ここ
        # requirements ほかは省略
    ),
)

補足: Agent Runtime のデフォルトの Runtime Identity

Agent Runtime (旧 Agent Engine) を使って、オプションの指定なくエージェントをデプロイすると、既定で割り当てられる ID は per-agent の SPIFFE ID ではなく、Google マネージドのサービスエージェントのメールアドレスになります。

割り当てられた ID は、Agent Registry の RuntimeIdentity 属性から確認することができます。

"agentregistry.googleapis.com/system/RuntimeIdentity": {
  "principal": "sa://service-<PROJECT_NUMBER>@gcp-sa-aiplatform-re.iam.gserviceaccount.com"
}

上記の例では、sa://... の形式の値がこのエージェントの実行 ID となっています。 公式ドキュメント によると、このメールアドレスは AI Platform Reasoning Engine Service Agent という Google マネージドのサービスエージェントのものです (aiplatform の有効化時に自動付与されるサービスエージェント) 。

公式ドキュメントの Agent identity with Agent Runtime によると、後方互換性のためにこのような仕様となっているようですね。

If the identity flag isn't configured, the Agent Runtime instance continues to use service accounts. This ensures backward compatibility if you already implemented Infrastructure-as-Code-based deployments on your agents.

IAM Connectors を用いて外部リソースへアクセスする

サードパーティの SaaS API など、Google Cloud 外のリソースにアクセスする場合は、Google が発行する SPIFFE ID のトラストドメインと関係が無いため、エージェント ID を直接提示しても検証ができません。 そのため、外部リソースにアクセスする場合は IAM Connectors という機能を使います。 エージェントは IAM Connectors へのアクセス時に SPIFFE のエージェント ID で認証を行い (iamconnectors.user 権限が必要)、IAM Connectors が外部リソースに対するアクセストークン取得のリクエストを代行し、得られたアクセストークンをエージェントに渡す、という仕組みになっています。

なお、IAM Connectors から外部リソースへのアクセス時には、connector に保存された OAuth の client_id / client_secret を用いた Client Credentials Grant が行われます。 また、アクセストークン取得後はエージェントが直接外部リソースにアクセスするため実際の API コールなどには IAM Connectors は介在しません。

また、Agent Identity (というか IAM Connectors) は、エージェント自身として外部システムに認証する 2-legged OAuth (クライアントクレデンシャルを用いる。エンドユーザーは介在しない) と、3-legged OAuth (authorization code を用いる。特定のエンドユーザーの代理として外部システムにアクセスするため、ユーザーの同意が必要) の両方に対応しています。

今回は、ユーザーの同意を伴わない 2-legged OAuth を試してみます。

構築の流れ

実際に試した構成は次のとおりです。 手順 1 は本来外部リソース (例えば サードパーティの SaaS API など) の構築に相当する部分で、今回は検証用に自分で立てた OAuth サーバーで代用しています。

1. 外部リソースの用意

Client Credentials Grant でトークンを発行する /token と、Bearer トークンを検証する /protected を持つ適当なサーバーを Cloud Run でデプロイしました。 OAuth の client_id / client_secret は自分で発行したテスト値です。

$ gcloud run deploy <TOKEN_SERVER> \
    --source <DIR> --region asia-northeast1 --project=<PROJECT_ID> \
    --allow-unauthenticated --env-vars-file env.yaml \
    --min-instances 0 --max-instances 1

2. 2-legged OAuth connector の作成

トークンエンドポイントを手順 1 のサーバーに向け、テスト用の client_id / client_secret を IAM Connectors に登録します。

$ gcloud alpha agent-identity connectors create <CONNECTOR_ID> \
    --project=<PROJECT_ID> --location=asia-northeast1 \
    --two-legged-oauth-client-id=... \
    --two-legged-oauth-client-secret=... \
    --two-legged-oauth-token-endpoint=https://<TOKEN_SERVER>/token

3. エージェント ID を使用して Agent Runtime にエージェントをデプロイ

前述のとおり、Agent Runtime へのデプロイ時に identity_type=AGENT_IDENTITY を指定することで、実行 ID がエージェント ID (principal://...) になります。

4. エージェントへの権限付与

エージェント ID に対して roles/iamconnectors.user を付与し、IAM Connectors の利用を許可します。

$ gcloud alpha agent-identity connectors add-iam-policy-binding <CONNECTOR_ID> \
    --project=<PROJECT_ID> --location=asia-northeast1 \
    --role=roles/iamconnectors.user \
    --member="principal://agents.global.org-<ORG_ID>.system.id.goog/resources/aiplatform/projects/<PROJECT_NUMBER>/locations/asia-northeast1/reasoningEngines/<ENGINE_ID>"

なお、今回は Agent Identity の PoC 用途に限るため、エージェントのコードが retrieveCredentials を呼ぶときに connector のフルリソース名を直接指定することで Binding の登録を不要としました。 ちゃんと使う場合は Agent Registry の Binding で エージェント・宛先リソース・connector の対応関係を登録して管理しましょう。

認証の流れ

前述の環境を構築すると、以下のような流れで認証・認可が行われ、エージェントが外部リソースへアクセスできるようになります。

1. エージェント → IAM Connectors

外部リソースへのアクセスを必要とするエージェントが、自身の エージェント ID (SPIFFE ID) で、IAM Connectors の API (iamconnectorcredentials.retrieveCredentials) にアクセストークンを要求します。 このときの認証は、Google Cloud リソースへのアクセスとなるため、エージェント ID による IAM 認証です。 前述のとおり、IAM Connectors へのリクエストには roles/iamconnectors.user が必要です。

2. IAM Connectors → 外部のトークン発行先

IAM Connectors はエージェントからのリクエストを受けて、外部リソース (のトークン発行先) に対して OAuth のクライアントクレデンシャル交換を要求します。 このとき、IAM Connectors の認証 (外部リソースから見て、正しいクライアントからのリクエストであるか) に は、SPIFFE ではなく、connector に保存された client_id / client_secret を使った Basic 認証が使われます。 成功すると、IAM Connectors は取得したアクセストークンをエージェントに返します。

ちなみに、IAM Connector から /token に送られてきた HTTP リクエストを確認してみたところ、User-Agent: Google のカスタムヘッダが付与された HTTP POST となっていました。 中身は標準的な OAuth 2.0 の Client Credentials Grant で、grant_type=client_credentials、クライアント認証は HTTP Basic (Authorization: Basic <base64(client_id:client_secret)>) でした。 トークンサーバー側のログにも via_basic: true (Authorization ヘッダが Basic で始まる) が記録されており、復号すると client_id:client_secret 構造だったことが確認できました。

POST /token  200  User-Agent: Google
     grant_type=client_credentials / client_id=<CLIENT_ID> / HTTP Basic で認証

3. エージェント → OAuth で保護された外部リソース

エージェントは、手順 2 で得たアクセストークンを Authorization: Bearer ... として提示し、外部リソース側はトークンの有効性を確認して認可します。

呼び出しの結果、次のように /protected へのアクセスができました。

{
  "retrieve_ok": true,
  "protected_status": 200,
  "protected_body": "{\"message\":\"2LO-E2E-OK\",\"ok\":true}",
  "header_field": "Authorization: Bearer"
}

なお、エージェント自身は client_secret を保持しません (connector が保管し、describe にも含まれない)。 シークレットを IAM Connectors に隔離することで、エージェントは「エージェント ID (SPIFFE) でトークン取得を依頼するだけ」で良い、という構造になっています。

実機検証を通じて得られた知見

1. agentidentity.googleapis.com は必要か

ちょっと紛らわしいですが、Agent Identity の各機能は Agent Identity API (agentidentity.googleapis.com) を有効化しなくても使えるし、現状 Agent Identity API を有効化する方法はなさそう、という話です。

現在、gcloud alpha には gcloud alpha agent-identity auth-providers というコマンドがあり、一見すると外部リソースへのアクセスに必要そうに見えるのですが、実際は (上記の 2-legged OAuth には) 必要ありません。 実行してみると、この機能を利用するには Agent Identity API (agentidentity.googleapis.com) の有効化が必要、というメッセージが返ってきます。

$ gcloud alpha agent-identity auth-providers list --project=<PROJECT_ID> --location=global
  
ERROR: (gcloud.alpha.agent-identity.auth-providers.list) PERMISSION_DENIED:
Agent Identity API has not been used in project <PROJECT_ID>
before or it is disabled. Enable it by visiting
https://console.developers.google.com/apis/api/agentidentity.googleapis.com/overview?project=...
      service: agentidentity.googleapis.com
      serviceTitle: Agent Identity API
    reason: SERVICE_DISABLED

ならばということで Agent Identity API (agentidentity.googleapis.com) の有効化を試みると、次のように拒否されます。

$ gcloud services enable agentidentity.googleapis.com --project=<PROJECT_ID>

ERROR: (gcloud.services.enable) PERMISSION_DENIED: Permission denied to enable
service [agentidentity.googleapis.com]
Help Token: ...
- '@type': type.googleapis.com/google.rpc.PreconditionFailure
  violations:
  - subject: '110002'
    type: googleapis.com
- '@type': type.googleapis.com/google.rpc.ErrorInfo
  domain: serviceusage.googleapis.com
  reason: AUTH_PERMISSION_DENIED

gcloud services list --available のリストに出てこないため、この検証用プロジェクトで有効化できないことはわかりますが、上記の reason を見るに有効化を拒否している (NOT_FOUND などではなく AUTH_PERMISSION_DENIED) ため、API 自体は存在していそうな感じがあります。

しかし、例えば前述のように 2-legged OAuth を構成するとして、上記の API やコマンドが使えないことで困ることは特にありません。 エージェント ID を用いた外部リソースへのアクセスを解説している一連の 公式ドキュメント では、この Agent Identity API (agentidentity.googleapis.com) の有効化に関する記述は見受けられませんでした。 実際、この API を有効化せずとも SPIFFE のエージェント ID は発行できていますし、IAM プリンシパルとして機能しています。

少なくとも今回検証した 2-legged OAuth による外部リソースへのアクセスでは、公式ドキュメントに記載のとおり gcloud alpha agent-identity connectors ... を使えばよく、gcloud alpha agent-identity auth-providers ... や agentidentity.googleapis.com の明示的な有効化は不要でした。

ちなみに、トークン取得のための API iamconnectorcredentials.retrieveCredentials については、以下の様子からアルファ版といった位置付けと考えられるため、今後仕様が変更されるかもしれません。

  • API バージョンが v1alpha となっている
  • クライアントライブラリ google-cloud-iamconnectorcredentials が 0.1.0 となっている

2. (現状の) トークン取得 API (iamconnectorcredentials) への通信プロトコルは REST のみ

注: このセクションで扱う API は、connector の管理 (iamconnectors.googleapis.com / gcloud alpha agent-identity connectors) ではなく、実行時にトークンを取得する iamconnectorcredentials.googleapis.com (クライアントライブラリ google-cloud-iamconnectorcredentials、retrieve_credentials) のほうです。

Google Cloud のクライアントライブラリは、API への通信に gRPC と REST を選べることが多いですが、このトークン取得 API は現状 REST のみが有効となっています。 公式の ADK の内部実装でも、特に選択の余地なく REST が使われています。

ちなみに、このトークン取得 API を gRPC で呼ぶと、connector が存在し IAM で適切な権限が付与されていたとしても NOT_FOUND が返ってきます。

3. (現状の) トークン取得 API (iamconnectorcredentials) は LRO 未対応

Google Cloud の API は、時間のかかるリクエストに対してオペレーション ID を素早く返却し、クライアントがポーリングして完了を待つことがあります。 その場合、ライブラリの .result() がポーリングを実行して完了待ちを行います。 今回紹介したトークン取得 API もオペレーション ID を返すことができますが、実際には LRO をサポートしていないため、.result() (内部で GetOperation を呼ぶ) を使うとそのオペレーションを取得しようとして NOT_FOUND になりました。

この件については ADK の内部実装にコメントがあり、「現状このサービスは LRO 未対応なので、.done()/.result() が使えず、自前で再試行する」という対処になっていることがわかりました。

# 1. The service does not yet support LROs, so even though the
#    retrieve_credentials method returns an Operation object, the methods like
#    operation.done() and operation.result() will not work yet.

ADK を使う場合は、GcpAuthProviderScheme で connector を指定するだけで、プロトコルの設定も LRO ポーリングも ADK が処理してくれます。 公式ドキュメントでも API を直接呼ぶような使い方は紹介されていませんし、ADK を使っておけば意識する必要がない話ではあるのですが、PoC などで API を直接呼ぶ際は注意です。

4. セキュリティ強度の違い

Agent Identity は mTLS / DPoP / cert-binding によって「トークンを盗まれても再利用できない」ことを売りにしています (参考) が、これは Google Cloud リソースに対するアクセストークンの話に限るという点は注意しておきたいところです。 2-legged OAuth の検証で見たように、エージェントが IAM Connectors から受け取って外部リソースに直接提示する OAuth トークンは、通常の bearer トークンに過ぎません。 そのため、「エージェント自身が client_secret を持たない」のはそのとおりではあるものの、結果としてエージェントが受け取り、外部リソースに提示するトークン自体は cert-binding の保護外になります。

どう使っていくか

Google Cloud リソースの per-agent な認証・認可という選択肢が増えたのは良いことで、その要件がある場合の実装コストが低く、セキュアな手段として Agent Identity は便利に使えそうです。 一方で、全てのエージェントに対して per-agent な IAM バインディングをきめ細かく行っていくとすると、エージェントの数が数百や数千になったときの監査・管理コストが大きな課題になりそうです。 機微情報を扱うエージェントや、監査要件の厳しいエージェントには Agent Identity で per-agent なきめ細かい権限制御や監査・追跡容易性を確保しておき、開発用途のちょっとしたエージェントや、開発したばかりでソーク中のエージェントなどは、ある程度まとまった権限を付与したサービスアカウントを共用するようなアプローチも有効かもしれません。

また、エージェントから外部リソースへのアクセスについては、IAM Connectors が有力な選択肢にはなったものの、これ以外に方法がないということではありません。 「個々のエージェントから隔離されたシークレットで外部リソースにアクセスする」という目的であれば、公式ドキュメントにもあるとおり、IAM Connectors を使わずに Secret Manager にクライアントシークレットを置き、エージェント ID に secretAccessor を付与して ADC で取得するパターンも依然として選択肢になり得ます。 このあたりはアクセス先の外部リソースの制約にも依存することも意識しておくと良さそうです。 外部リソースが例えばアカウント単位で課金するルールの場合、per-agent で大量のアカウントを調達しようとするとコスト影響が大きくなるかもしれませんし、あるいは AI エージェント間でのアカウント共用を禁止するような制約があるかもしれません。

まとめ

Agent Identity は per-agent で権限制御を行うための仕組みで、SPIFFE ID と X.509 証明書を持ち、発行された ID は IAM プリンシパルとして機能します。 エージェントが外部リソースにアクセスする際は、IAM Connectors を介して相手のアクセストークンを取得します。 今回は 2-legged OAuth での検証の様子をご紹介しました。

公式ドキュメントでは IAM Connectors を auth provider や auth manager とも表記しているため紛らわしいですが、現状は gcloud alpha agent-identity auth-providers や Agent Identity API (agentidentity.googleapis.com) は必要なく、gcloud alpha agent-identity connectors を利用します。 今回試した API がアルファ扱いということもあり、今後挙動が変わる可能性はありますが、同じようなところで詰まっている人の参考になれば幸いです。

Cloud Run Jobs を実行したとき、アプリが動き出すまでに起きていること

Cloud Run Jobs は Google Cloud のサーバレスなジョブ実行基盤です。 コンテナを起動して任意の処理を 1 回以上実行し、終わったら自動でインスタンスを破棄してくれるという、バッチや単発タスク向けのサービスになっています。

本記事では、「Cloud Run Jobs にジョブの実行をリクエストしてから、アプリケーションコンテナのコードが実際に動き出すまでの過程で、どこにどれだけの時間がかかっているのか」の内訳を見ていきたいと思います。 今回は gcloud run jobs executions describe で見える区分と、そこに書かれている message の内容を頼りに整理してみました。 また、上記のインフラ側のイベント記録と、アプリケーションログのタイムスタンプとの間にある時間差についてもちょっとした実験を行って確認しています。

TL;DR

  • execution の createTime からアプリの ENTRYPOINT が exec されるまでに、合計 ~8.0 秒程度 (N=10 中央値、Cloud Run gen2、asia-northeast1) を要した
  • Cloud Run Jobs 実行時のインフラ側のイベントは image import / provision / schedule wait / sandbox start / Started が識別でき、最も時間がかかるのは sandbox start で ~5.0 秒程度
  • Cloud Run Jobs のインフラの準備完了 (Started condition の時点) から、実際にアプリケーションコンテナの ENTRYPOINT のコマンドが実行開始されるまでのラグは、今回の検証では中央値 113 ms 程度 (異なるクロック間の比較なので精度は何とも言えないが、おおむね 100 ms 前後の何かが乗っていそう)

describe で見えるイベント (アプリ exec の手前まで)

gcloud run jobs executions describe を打つと、conditions というフィールドに何件かのコンディションが並びます。 それぞれに lastTransitionTime と message が付いていて、Cloud Run 側が「いつ何が起きたか」を記録していることがわかります。

$ gcloud run jobs executions describe <EXECUTION_NAME> \
    --region=asia-northeast1 --project=<PROJECT_ID> --format=yaml

主要部分の抜粋がこちらです。

createTime: 2026-05-29T02:54:28.268653Z
startTime: 2026-05-29T02:54:32.294535Z
completionTime: 2026-05-29T02:54:43.909070Z
conditions:
- type: ContainerReady
  lastTransitionTime: 2026-05-29T02:54:30.168169Z
  message: Imported container image in 1.9s.
  state: CONDITION_SUCCEEDED
- type: ResourcesAvailable
  lastTransitionTime: 2026-05-29T02:54:30.523283Z
  message: Provisioned imported containers.
  state: CONDITION_SUCCEEDED
- type: Started
  lastTransitionTime: 2026-05-29T02:54:37.851445Z
  message: Started deployed execution in 7.32s.
  state: CONDITION_SUCCEEDED
- type: Completed
  lastTransitionTime: 2026-05-29T02:54:43.909070Z
  message: Execution completed successfully in 11.61s.
  state: CONDITION_SUCCEEDED

これを見ると、createTime の時点から ContainerReady → ResourcesAvailable → Started → Completed の順に時刻が並んでいて、それぞれの message が「何が完了したのか」を自己説明的に書いてくれています。

これらの type の値 (ContainerReady / ResourcesAvailable / Started / Completed) の正確な定義については、私が当たった範囲の v2 REST リファレンスでは明確なものを見つけられませんでした。 本記事では、各 condition の message が示す内容を、そのままその区分の意味として扱います。

実測した中央値 (N=10、後述) を、yaml に見える主要なタイムスタンプの差分として並べると、次のようになりました (以下の表で ContainerReady などの condition 名は、その condition の lastTransitionTime を指します) 。

区分 区間 中央値
image import createTime → ContainerReady ~703 ms
provision ContainerReady → ResourcesAvailable ~350 ms
schedule wait ResourcesAvailable → startTime ~1,835 ms
sandbox start startTime → Started ~5,030 ms

※ schedule wait と sandbox start は、対応する message の無い区間に対して便宜上著者が付けたラベルです。その区間に実際に何が走っているかは公式の message には書かれていないため、推測を含んだ呼称として読んでください (例えば sandbox start の区間は、gen2 の microVM provision とコンテナランタイム起動が走っているあたりだろう、というあくまで推測です) 。

合計すると、createTime から Started までで ~7.9 秒。 これだけでも、Cloud Run Jobs を実行してからアプリのコードが動き出す手前まで、いくつかの段階があることが見て取れます。

describe には出てこない「Started のあと」

Started の message は Started deployed execution in 7.32s. で、これを見る限り execution が動き出した時刻と思われます。 ただ、これがそのまま「コンテナの ENTRYPOINT が exec された瞬間」と一致するかどうかまでは、message や公式ドキュメントの該当箇所で触れられていません。 例えば Node.js のようにランタイムの初期化にそれなりの時間がかかりうるようなアプリケーションの場合は、アプリケーションの最初のログ出力のタイミングを頼りにしようとすると、実際の ENTRYPOINT が exec された瞬間とはかなり乖離してしまう可能性があります。

今回は簡易な検証として、ENTRYPOINT の先頭にシェルを挟み、本来のコマンドの直前に時刻を出力するようにしてみました。

ENTRYPOINT ["/bin/sh","-c","echo PHASE container_exec epoch_ns=$(date +%s%N); exec node dist/main.js"]

/bin/sh の起動コストは数 ms 程度と想定されるので、今回のざっくりとした検証であれば、ここで出力した時刻を「コンテナ exec の瞬間」と見なしても概ね問題ないと考えました。 時刻取得に使用している date +%s%N では Unix epoch をナノ秒精度で取れます (node:20-slim のような coreutils が入っているベースイメージならそのまま使えます)。 exec node dist/main.js の exec で、シェルが node プロセスに置き換わります。PID 1 を node が引き継ぐので、余計なシェルプロセスがぶら下がらないようにしています。

なお、このログ出力は普通の stdout なので Cloud Logging に流れます。 あとは Started condition の lastTransitionTime と、このログの epoch を比較すれば、Started → ENTRYPOINT exec のラグが (おおよそ) 見えてくるのではと考えました。

計測結果: Started → ENTRYPOINT 開始

Cloud Run Jobs のジョブを 1 件用意し、N=10 回 をコールドスタートで実行し、それぞれの execution について「Started condition の lastTransitionTime」と「container_exec ログの epoch」の差を取りました。

結果(ms):

指標 値
中央値 113
min – max 52 – 195
mean 119

Started のあと ENTRYPOINT が動き出すまでに、おおむね 100 ms 前後のラグが乗っていそうな感触です。

ただし、この値はそのまま「ENTRYPOINT が動き出すまでに絶対的なラグがある」ものとして扱うのには慎重になりたいところです。 比較しているのは、Cloud Run のコントロールプレーン側が打った Started の時刻と、コンテナを実行しているインスタンス側の時計が打った container_exec の時刻です。 両者は別々のクロックなので、計測値には両者の時計のずれ (clock skew) が含まれます。

アプリが動き出すまでの全体内訳

ここまでの区分を、createTime から ENTRYPOINT exec までの時系列で並べてみると、以下のようになります。 いずれも N=10 中央値です。

区分 中央値 (ms) 取り方
image import 703 createTime → ContainerReady
provision 350 ContainerReady → ResourcesAvailable
schedule wait 1,835 ResourcesAvailable → startTime
sandbox start 5,030 startTime → Started
Started → ENTRYPOINT 開始 113 Started → ログの container_exec
アプリ exec まで合計 ~8,031

※ 「アプリ exec まで合計」は各行の中央値を単純加算した参考値です。end-to-end (createTime → ENTRYPOINT exec) の計測で中央値を取った場合とは一致しない可能性があります。

このうち、上の 4 段は describe から読み取れる区分です。 最後の Started → ENTRYPOINT のラストワンマイルが、ENTRYPOINT に手を入れたことで見えてきた区間です (ただし前述のとおり clock skew の懸念は残る) 。

支配的なのは sandbox start で ~5 秒、一番短い区間が ENTRYPOINT exec までの 113 ms でした。 なお、最初の image import の区間の所要時間は、イメージサイズやキャッシュの有無によって大きく変動する可能性があります (今回の計測値は全てキャッシュヒット状態のもの) 。

注意点

数値の前提と、留保しておきたい点をいくつか書いておきます。

  • 全部 N=10 中央値の値です。インフラ側のフェーズのなかでも sandbox start は特に試行ごとの分散が大きく、レンジで見ると数秒単位で振れています
  • Cloud Run gen2、asia-northeast1、cpu=1 / memory=512Mi、node:20-slim ベースのコンテナという単一構成での観測値です。条件が違えば値は当然変わります
  • Started → ENTRYPOINT 開始のラグは、コントロールプレーンとインスタンスの時計のずれ (clock skew) を含む値です。精度の信頼できる値として扱わず、「100 ms 前後の何かが乗っている」という見立てに留めるのが安全でしょう
  • condition の type の正確な定義は、私が当たった範囲では明確な記載を見つけられませんでした。本記事では message を区分の意味の根拠として扱っています

補足: container/startup_latencies メトリクスについて

Cloud Monitoring には run.googleapis.com/container/startup_latencies という「インスタンス起動の所要時間」を distribution で返すメトリクスがあります。 descriptor を見ると monitoredResourceTypes に cloud_run_job も入っているので、createTime → Started (~7.9 秒) と突き合わせれば対応関係がわかるはず、と思って実測してみたのですが、結果はそうなりませんでした。

  • 本検証時点 (2026-05-30 / asia-northeast1) で、今回の検証を通じて計 80 回超の Job 実行を行いましたが、メトリクスは bucketOptions (ヒストグラムの bin スキーマ) だけが返り、count / mean / bucketCounts がすべて空でした。つまり実データが 1 点も投入されていない状態でした。launchStage が BETA なので、Jobs に対しては実装が追いついていない時期に当たったのかもしれません
  • 比較として、同プロジェクトに一時的に立てていた Cloud Run (Services) の同じメトリクスは値が記録されており、観測できた 2 サンプルでは mean ~72 ms / ~128 ms といったところでした (サンプル数が小さいので参考値)
  • メトリクス名は「container startup latencies」となっていますが、descriptor の説明文も "Distribution of time spent starting a new container instance in milliseconds." とシンプルで、ここでの「starting a new container instance」が image pull / schedule / sandbox 起動まで含むのか、それともコンテナプロセスを起こす狭い区間だけなのかは明示されていません。前述の観測値を見る限り、Conditions に記録されている各区間の全てを合わせたものではなく、もっと狭い区間を捕捉しているように見えます

以上から、startup_latencies メトリクスは本記事で扱った createTime → Started の代替にはならず、Jobs では現時点でそもそも値が出ないようでした。

まとめ

Cloud Run Jobs を実行してから、自分のアプリのコードが動き出すまでに何が起きているのか、について describe コマンドから得られる情報を中心に整理してみました。 Job の実行をリクエストしてから、アプリケーションのログが出力され始めるまでにそれなりの時間差がある場合は、今回ご紹介したような方法でインフラの準備作業にかかる各区間の所要時間を整理してみると、どこで時間がかかっているのかを特定する手がかりになるかもしれません。

  • gcloud run jobs executions describe の conditions と message を読めば、image import / provision / schedule wait / sandbox start / Started までの主要な区分と所要時間がわかる
  • describe には出てこない「Started のあと、ENTRYPOINT が exec されるまで」の区間だけは、ENTRYPOINT を /bin/sh -c "echo ...; exec ..." で包む形で計装した
  • 結果は N=10 中央値 113 ms、レンジ 52–195 ms。異なるクロック間の比較で時計のずれを含んだ値なので精度は保証できないものの、ms 100 オーダーの何かが乗っていそうな感触