はじめに
KubernetesのAdmission Webhookは、API Serverと外部サービスを連携させることで、リソース作成・更新時の制御を実現する仕組みです。
OPA GatekeeperやKyvernoなども、このAdmission Webhook API仕様を利用して動作しています。
本記事では、Webhookの内部API仕様を以下の観点から詳細に解説します。
- AdmissionReviewリクエストの構造
- Webhookレスポンス仕様
- MutatingとValidatingの違い
- failurePolicyやtimeoutの挙動
- セキュリティ（TLS / CAバンドル）
1. Admission Webhookの全体フロー
kubectl apply ↓ API Server ↓ Mutating Webhook (0..n回) ↓ Validating Webhook (0..n回) ↓ etcd保存 or 拒否 WebhookはHTTPS経由でAPI Serverから呼び出されます。
2. AdmissionReview リクエスト構造
API ServerはWebhookへAdmissionReviewオブジェクトをPOSTします。
基本JSON構造
{ "apiVersion": "admission.k8s.io/v1", "kind": "AdmissionReview", "request": { "uid": "12345-abcde", "kind": { "group": "", "version": "v1", "kind": "Pod" }, "resource": { "group": "", "version": "v1", "resource": "pods" }, "namespace": "default", "operation": "CREATE", "userInfo": { "username": "admin", "groups": ["system:masters"] }, "object": { // 作成されるPodの完全なSpec }, "oldObject": null, "dryRun": false } } 主要フィールド解説
| フィールド | 説明 |
|---|---|
| uid | リクエスト識別子（レスポンスに必須） |
| operation | CREATE / UPDATE / DELETE / CONNECT |
| object | 新しいリソース内容 |
| oldObject | UPDATE時の旧リソース |
| dryRun | ドライラン実行かどうか |
3.AdmissionReview レスポンス仕様
Webhookは以下の形式でレスポンスを返します。
Validating Webhook レスポンス例
{ "apiVersion": "admission.k8s.io/v1", "kind": "AdmissionReview", "response": { "uid": "12345-abcde", "allowed": false, "status": { "message": "privilegedコンテナは禁止されています" } } } フィールド解説
| フィールド | 説明 |
|---|---|
| uid | リクエストと一致させる必要あり |
| allowed | true=許可, false=拒否 |
| status.message | エラーメッセージ |
4.Mutating WebhookのPatch仕様
Mutating Webhookはリソースを書き換えることができます。
レスポンス例（JSON Patch）
{ "response": { "uid": "12345-abcde", "allowed": true, "patchType": "JSONPatch", "patch": "W3sib3AiOiJhZGQiLCJwYXRoIjoiL3NwZWMvY29udGFpbmVycy8wL2VudiIsInZhbHVlIjpbeyJuYW1lIjoiRU5WIiwidmFsdWUiOiJwcm9kIn1dfV0=" } } ※ patchはBase64エンコードされたJSONPatchです。
JSONPatchの中身（デコード後）
[ { "op": "add", "path": "/spec/containers/0/env", "value": [{"name":"ENV","value":"prod"}] } ] 5. Webhook設定（ValidatingWebhookConfiguration）
apiVersion: admissionregistration.k8s.io/v1 kind: ValidatingWebhookConfiguration metadata: name: my-webhook webhooks: - name: validate.example.com clientConfig: service: name: webhook-service namespace: default path: "/validate" caBundle: <base64-encoded-ca> rules: - apiGroups: [""] apiVersions: ["v1"] operations: ["CREATE"] resources: ["pods"] failurePolicy: Fail timeoutSeconds: 5 6. failurePolicyの内部挙動
| 設定 | Webhook障害時の挙動 |
|---|---|
| Fail | Webhookが応答しない場合、リクエスト拒否 |
| Ignore | Webhook障害時でも処理継続 |
セキュリティ系Webhookでは通常Failが推奨されます。
7. timeoutSeconds
Webhook呼び出しは同期処理です。タイムアウトを超えるとfailurePolicyに従います。
- デフォルト：10秒
- 推奨：2〜5秒
8.TLSとセキュリティ要件
Admission Webhookは<strong>HTTPS必須</strong>です。
必要条件：
- サーバ証明書（Webhook側）
- CA証明書をWebhookConfigurationに埋め込み
- API Serverが証明書を検証
caBundle: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...9. 実行順序と注意点
- Mutating → Validating の順番
- 複数Webhookは順番保証なし
- 再帰的Mutationに注意
- 副作用のあるWebhookは禁止
10.パフォーマンスとスケーリング
Webhookは同期処理のため：
- 遅いWebhookはクラスタ全体に影響
- Replica数を増やし冗長化
- 水平スケーリング設計が重要
まとめ
- AdmissionReviewがWebhook通信の基本単位
- allowed=falseで拒否可能
- MutatingではJSONPatchを使用
- failurePolicyとtimeoutが可用性に直結
- TLS必須でセキュア通信
Admission Webhookの内部仕様を理解することで、GatekeeperやKyvernoの動作原理も明確になります。
