Kyverno

Mark as read

Kyverno: Kubernetes Policy as Code の完全ガイド

1. はじめに

Kyvernoとは

Kyverno（キバーノ）は、Kubernetes環境におけるポリシー・アズ・コード（Policy as Code） を実現するツールです。Kubernetes APIサーバーに統合された Webhook を通じて、リソースの作成・更新・削除などの操作を検証・変更・監査し、セキュリティ、コンプライアンス、ベストプラクティスの強制を行います。

Kyvernoの最大の特徴は、KubernetesネイティブなYAML形式でポリシーを定義できることであり、複雑なスクリプトを必要としません。これにより、Kubernetes管理者やプラットフォーム・エンジニアは、既存のKubernetes知識を活かして簡単にセキュリティポリシーを管理できます。

主な特徴

Kubernetesネイティブ: YAML形式のポリシーをKubernetes CustomResourceDefinition (CRD) として定義
宣言的: コマンドラインツールではなく、宣言的なマニフェストで全てを定義
フレキシブル: 検証、変更、生成、クリーンアップなど複数の操作モード
CEL対応: Common Expression Language (CEL) による高度なルールロジック
マルチテナント対応: 異なるチーム/プロジェクト向けのポリシー分離
監査ログ統合: Kubernetesの監査ログと統合して全ての検証結果を記録

なぜKyvernoが必要か

現代のKubernetes環境では、以下のような課題が存在します：

セキュリティ脅威: 不適切な設定によるセキュリティ脆弱性
ポリシー非準拠: 企業のセキュリティポリシーやコンプライアンス要件への未準拠
リソース浪費: 不適切なリソースリクエスト設定による浪費
運用の一貫性: 異なるチーム間での設定ばらつき

Kyvernoは、これらの問題をKubernetes-nativeな方法で系統的に解決します。

2. Kyvernoの基本概念

2.1 Policy (ポリシー)

Kyvernoのコア要素は ClusterPolicy と Policy という2つのCRDです。

ClusterPolicy: クラスタ全体に適用されるグローバルなポリシー
Policy: 特定のNamespace内にのみ適用されるローカルなポリシー

2.2 Rule (ルール)

Policy内に複数のRuleを定義でき、各Ruleは独立した条件チェックとアクションを持ちます。

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: example-policy
spec:
  rules:
    - name: rule-1
      # ここに条件とアクションを記述
    - name: rule-2
      # 別の条件とアクション

2.3 Policy操作モード

Kyvernoは以下の操作モードをサポートします：

(1) Validation (検証)

リソースが特定の条件を満たしているか検証します。条件を満たさない場合は、リソース作成/更新を拒否します。

validation:
  message: "Image must be from approved registry"
  pattern:
    spec:
      containers:
        - image: "gcr.io/*"

(2) Mutation (変更)

リソースを自動的に修正・変更します。例えば、デフォルト値の追加やイメージタグの置換などです。

mutate:
  patchStrategicMerge:
    spec:
      containers:
        - (image): "*"
          imagePullPolicy: "Always"

(3) Generation (生成)

特定のリソースが作成される際に、自動的に別のリソースを生成します。例えば、Namespaceが作成される際に、デフォルトのNetworkPolicyを生成する場合などです。

generate:
  kind: ConfigMap
  name: default-config
  namespace: "{{request.object.metadata.name}}"
  data:
    config.yaml: |
      defaults: true

(4) Cleanup (クリーンアップ)

特定の条件でリソースを削除します。例えば、期限切れのリソースやメモリ使用量が多いPodなどです。

cleanup:
  removeResources:
    - kind: Pod
      selector:
        matchLabels:
          cleanup: "true"

2.4 マッチング戦略

ポリシーをどのリソースに適用するかは、以下の要素で制御します：

Resources: 対象となるリソースの種類 (Pod, Deployment, Service など)
Namespace: 対象Namespace
Selector: ラベルセレクタによるマッチング
Exclude: 除外するリソースやNamespace

3. アーキテクチャ概要

3.1 全体構成

┌─────────────────────────────────────────────────────┐
│              Kubernetes API Server                  │
│  ┌───────────────────────────────────────────────┐  │
│  │   ValidatingAdmissionWebhook                  │  │
│  │   (Kyverno Controller Manager内)             │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
         ▲                                      ▲
         │                                      │
   リクエスト                              レスポンス
   (JSON Patch)                          (Allow/Deny)
         │                                      │
         ▼                                      ▼
┌─────────────────────────────────────────────────────┐
│         Kyverno Controller Manager Pod              │
│  ┌───────────────────────────────────────────────┐  │
│  │  Policy Engine                                │  │
│  │  ├─ Policy Loader                            │  │
│  │  ├─ Rule Matcher                             │  │
│  │  ├─ Validation Engine                        │  │
│  │  ├─ Mutation Engine                          │  │
│  │  └─ Generation Engine                        │  │
│  └───────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────┐  │
│  │  Background Processor                         │  │
│  │  (Generation, Cleanup)                        │  │
│  └───────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────┐  │
│  │  Audit Logger                                 │  │
│  │  (Policy Check Results)                       │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
         │
         │ CRD監視
         ▼
┌─────────────────────────────────────────────────────┐
│         Kubernetes Etcd                             │
│  ├─ ClusterPolicy / Policy CRDs                     │
│  ├─ Application Resources                          │
│  └─ Configuration Secrets                          │
└─────────────────────────────────────────────────────┘

3.2 主要コンポーネント

(1) Policy Engine

Kyvernoの心臓部です。以下の処理を順序立てて実行します：

ポリシー読み込み: Etcdから有効なポリシーを読み込む
ルールマッチング: リソースがポリシーのマッチング条件を満たすかチェック
条件評価: CEL式やパターンマッチング実行
アクション実行: Validation、Mutation、Generation などの処理
結果返却: Webhook応答を生成

(2) ValidatingAdmissionWebhook

Kubernetes APIサーバーの外部Webhookメカニズムを使用して、全てのAPIリクエストをインターセプトします。

リクエスト処理フロー：

APIリクエスト 
    ↓
Authentication & Authorization
    ↓
Validation Webhook (Kyverno)
    ↓ Validation Webhook (他のツール等)
    ↓
Mutating Webhook (Kyverno)
    ↓
Mutating Webhook (他のツール等)
    ↓
リソース作成/更新
    ↓
Audit Log記録

(3) Background Processor

Webhook処理の対象外（例：既存リソースの監視、定期的なクリーンアップ）の処理を担当します。

Generation Ruleで作成されるリソースの監視
CleanupPolicy による定期的なリソース削除

(4) Audit Logger

全てのポリシーチェック結果をKubernetesの監査ログと統合し、コンプライアンス追跡を実現します。

3.3 デプロイメント

Kyvernoは通常、kyverno Namespaceに以下のコンポーネントとしてデプロイされます：

# Kyverno Controller Manager (通常は2-3レプリカ)
Deployment: kyverno

# Webhook Service
Service: kyverno-svc

# ValidatingAdmissionWebhook設定
ValidatingWebhookConfiguration: kyverno-resource-validating-webhook-cfg
ValidatingWebhookConfiguration: kyverno-webhook-cfg

# MutatingAdmissionWebhook設定
MutatingWebhookConfiguration: kyverno-resource-mutating-webhook-cfg
MutatingWebhookConfiguration: kyverno-mutating-webhook-cfg

# RBAC
ServiceAccount: kyverno
ClusterRole: kyverno
ClusterRoleBinding: kyverno

4. Policy (ポリシー) の種類

4.1 検証ポリシー (Validation Policy)

リソースが特定のルールを満たしているか検証し、満たさない場合は拒否します。

主な用途:

セキュリティベースラインの強制
コンプライアンス要件の確認
リソース命名規則の検証

例: イメージレジストリの制限

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: restrict-image-registry
  namespace: kyverno
spec:
  validationFailureAction: audit  # audit/enforce
  background: true
  rules:
    - name: validate-image-registry
      match:
        resources:
          kinds:
            - Pod
      validate:
        message: "Images must be from approved registries (gcr.io, docker.io)"
        pattern:
          spec:
            containers:
              - image: "gcr.io/* | docker.io/*"
            initContainers:
              - image: "gcr.io/* | docker.io/*"

4.2 変更ポリシー (Mutation Policy)

リソースを自動的に修正し、デフォルト値を追加したり、設定を標準化します。

主な用途:

デフォルト値の自動設定
イメージタグの自動置換
セキュリティコンテキストの自動追加

例: imagePullPolicyの自動設定

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: add-default-image-pull-policy
  namespace: kyverno
spec:
  rules:
    - name: add-image-pull-policy
      match:
        resources:
          kinds:
            - Pod
      mutate:
        patchStrategicMerge:
          spec:
            containers:
              - (name): "*"
                imagePullPolicy: "IfNotPresent"

4.3 生成ポリシー (Generation Policy)

特定のリソース作成時に、別のリソースを自動生成します。

主な用途:

Namespace作成時のデフォルトNetworkPolicy生成
Namespace作成時のRBAC設定生成
デフォルトリソースクォータの生成

例: Namespace作成時のNetworkPolicy生成

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: default-network-policy
  namespace: kyverno
spec:
  rules:
    - name: default-deny-all
      match:
        resources:
          kinds:
            - Namespace
      generate:
        kind: NetworkPolicy
        name: default-deny-all
        namespace: "{{request.object.metadata.name}}"
        data:
          spec:
            podSelector: {}
            policyTypes:
              - Ingress
              - Egress

4.4 クリーンアップポリシー (Cleanup Policy)

特定の条件のリソースを定期的に削除します。

主な用途:

古いPodの自動削除
完了したJobの自動削除
期限切れのテンポラリリソースの削除

例: 完了したJobの自動削除

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: cleanup-completed-jobs
  namespace: kyverno
spec:
  rules:
    - name: cleanup-succeeded-jobs
      match:
        resources:
          kinds:
            - Job
      cleanup:
        removeResources:
          - kind: Job
            selector:
              matchLabels:
                cleanup: "true"

5. ルールマッチング機構

5.1 マッチング条件

ポリシーをどのリソースに適用するかは、複数の条件を組み合わせて制御します。

Match セクション

rules:
  - name: my-rule
    match:
      # (1) リソース種別
      resources:
        kinds:
          - Pod
          - Deployment
        names:
          - "my-pod-*"
        selector:
          matchLabels:
            env: production
      
      # (2) Namespace
      resources:
        namespaces:
          - default
          - kube-system
      
      # (3) 操作種別
      operations:
        - CREATE
        - UPDATE

Exclude セクション

rules:
  - name: my-rule
    match:
      resources:
        kinds:
          - Pod
    exclude:
      resources:
        namespaces:
          - kube-system
          - kyverno
        labels:
          exclude-policy: "true"
      operations:
        - DELETE

5.2 パターンマッチング

Kyvernoは複数のパターンマッチング方式をサポートします。

(1) ワイルドカード

# 全ての値
pattern:
  spec:
    containers:
      - image: "*"

# プレフィックスマッチ
pattern:
  spec:
    containers:
      - image: "gcr.io/*"

# サフィックスマッチ
pattern:
  spec:
    containers:
      - image: "*:latest"

(2) 複数パターン (OR)

# 複数パターンのいずれかに合致
pattern:
  spec:
    containers:
      - image: "gcr.io/* | docker.io/* | quay.io/*"

(3) 存在チェック

# フィールドが存在することを検証
pattern:
  spec:
    containers:
      - resources: ?*
      - livenessProbe: ?*

(4) 空でない検証

# 空でない値
pattern:
  metadata:
    annotations:
      app: "?*"

5.3 CEL (Common Expression Language)

より高度な条件評価には、CEL (Common Expression Language) を使用できます。

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: complex-validation
spec:
  rules:
    - name: check-cpu-limits
      match:
        resources:
          kinds:
            - Pod
      validate:
        message: "CPU limit must be >= 100m and <= 4000m"
        cel:
          expressions:
            - expression: >
                object.spec.containers.all(c, 
                  c.resources.limits.cpu > '100m' && 
                  c.resources.limits.cpu <= '4000m')
              message: "CPU limit out of range"

CEL式で利用可能なビルトイン関数：

object: リクエストされたリソースの内容
oldObject: 更新前のリソース内容（UPDATE時）
request: APIリクエスト情報
authorizer: 認可情報

6. 設定の具体例

6.1 セキュリティ関連の実用的な例

例1: ホストパスアクセスの禁止

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: restrict-host-path
  namespace: kyverno
spec:
  validationFailureAction: enforce
  background: true
  rules:
    - name: validate-hostpath
      match:
        resources:
          kinds:
            - Pod
      validate:
        message: "HostPath volumes are not allowed"
        pattern:
          spec:
            =(volumes):
              - name: "*"
                =(hostPath): null

例2: seLinuxオプションの強制

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: add-selinux-context
  namespace: kyverno
spec:
  rules:
    - name: add-selinux
      match:
        resources:
          kinds:
            - Pod
      mutate:
        patchStrategicMerge:
          spec:
            securityContext:
              seLinuxOptions:
                level: "s0:c123,c456"
                type: "spc_t"

例3: Privileged Containerの禁止

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: restrict-privileged-containers
  namespace: kyverno
spec:
  validationFailureAction: enforce
  background: true
  rules:
    - name: privileged-containers
      match:
        resources:
          kinds:
            - Pod
      validate:
        message: "Privileged containers are not allowed"
        pattern:
          spec:
            containers:
              - securityContext:
                  privileged: false

6.2 リソース管理の実用例

例4: CPU/Memory リクエストとリミットの強制

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: require-resource-limits
  namespace: kyverno
spec:
  validationFailureAction: audit
  background: true
  rules:
    - name: check-resources
      match:
        resources:
          kinds:
            - Pod
          excludeResources:
            namespaces:
              - kube-system
              - kube-node-lease
      validate:
        message: "CPU and memory limits must be set"
        pattern:
          spec:
            containers:
              - resources:
                  limits:
                    memory: "?*"
                    cpu: "?*"
                  requests:
                    memory: "?*"
                    cpu: "?*"

例5: メモリリクエストとリミットの比率チェック

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: memory-ratio-check
  namespace: kyverno
spec:
  validationFailureAction: audit
  rules:
    - name: memory-ratio
      match:
        resources:
          kinds:
            - Pod
      validate:
        message: "Memory limit must be <= 2x memory request"
        cel:
          expressions:
            - expression: >
                object.spec.containers.all(c,
                  c.resources.limits.memory <= 
                  2 * c.resources.requests.memory)

6.3 コンプライアンス関連の実用例

例6: ラベルの強制

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: require-labels
  namespace: kyverno
spec:
  validationFailureAction: enforce
  background: true
  rules:
    - name: check-labels
      match:
        resources:
          kinds:
            - Pod
            - Deployment
            - Service
      validate:
        message: "Required labels missing: app, team, environment"
        pattern:
          metadata:
            labels:
              app: "?*"
              team: "?*"
              environment: "?*"

例7: Imageプルポリシーの自動設定

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: image-pull-policy
  namespace: kyverno
spec:
  rules:
    - name: set-image-pull-policy-always
      match:
        resources:
          kinds:
            - Pod
      mutate:
        patchStrategicMerge:
          spec:
            containers:
              - (name): "*"
                imagePullPolicy: Always
            initContainers:
              - (name): "*"
                imagePullPolicy: Always

6.4 ネットワークポリシー生成の実用例

例8: Namespace作成時のネットワークポリシー自動生成

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: generate-networkpolicy
  namespace: kyverno
spec:
  rules:
    - name: deny-all-traffic
      match:
        resources:
          kinds:
            - Namespace
      generate:
        kind: NetworkPolicy
        name: deny-all-traffic
        namespace: "{{request.object.metadata.name}}"
        data:
          apiVersion: networking.k8s.io/v1
          kind: NetworkPolicy
          metadata:
            name: deny-all-traffic
          spec:
            podSelector: {}
            policyTypes:
              - Ingress
              - Egress
            ingress: []
            egress: []
    
    - name: allow-dns
      match:
        resources:
          kinds:
            - Namespace
      generate:
        kind: NetworkPolicy
        name: allow-dns
        namespace: "{{request.object.metadata.name}}"
        data:
          apiVersion: networking.k8s.io/v1
          kind: NetworkPolicy
          metadata:
            name: allow-dns
          spec:
            podSelector: {}
            policyTypes:
              - Egress
            egress:
              - to:
                  - namespaceSelector:
                      matchLabels:
                        name: kube-system
                ports:
                  - protocol: UDP
                    port: 53

6.5 マルチテナント環境での設定例

例9: Namespace内でのポリシー制限

apiVersion: kyverno.io/v1
kind: Policy
metadata:
  name: team-a-policies
  namespace: team-a
spec:
  validationFailureAction: enforce
  background: true
  rules:
    - name: restrict-node-selector
      match:
        resources:
          kinds:
            - Pod
      validate:
        message: "Only team-a nodes are allowed"
        pattern:
          spec:
            nodeSelector:
              team: "team-a"

7. ユースケース

7.1 セキュリティ管理

目標: セキュリティリスクを最小化

実装例：

特定のレジストリからのイメージのみ許可
Privileged コンテナを禁止
Root ユーザでの実行を禁止
ホストネットワークアクセスを禁止
ホストPID/IPC共有を禁止

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: security-baseline
spec:
  validationFailureAction: enforce
  background: true
  rules:
    - name: no-privileged
      match:
        resources:
          kinds:
            - Pod
      validate:
        message: "Privileged containers are not allowed"
        pattern:
          spec:
            containers:
              - securityContext:
                  privileged: false
    
    - name: no-root-user
      match:
        resources:
          kinds:
            - Pod
      validate:
        message: "Container must not run as root"
        pattern:
          spec:
            containers:
              - securityContext:
                  runAsNonRoot: true

7.2 リソース管理と効率化

目標: クラスタリソースの最適利用

実装例：

全てのPodにCPU/メモリリクエスト/リミットを強制
不適切なリソース設定を防止
リソースクォータの自動生成

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: enforce-resource-limits
spec:
  validationFailureAction: enforce
  background: true
  rules:
    - name: validate-resources
      match:
        resources:
          kinds:
            - Pod
      validate:
        message: "CPU and memory must have requests and limits"
        pattern:
          spec:
            containers:
              - resources:
                  requests:
                    cpu: "?*"
                    memory: "?*"
                  limits:
                    cpu: "?*"
                    memory: "?*"

7.3 コンプライアンスと監査

目標: 規制要件への準拠と監査証跡の確保

実装例：

必須ラベルの強制
監査ログとの統合
コンプライアンス状況の可視化

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: compliance-labels
spec:
  validationFailureAction: audit
  background: true
  rules:
    - name: required-labels
      match:
        resources:
          kinds:
            - Pod
      validate:
        message: "Required compliance labels: owner, cost-center"
        pattern:
          metadata:
            labels:
              owner: "?*"
              cost-center: "?*"

7.4 開発生産性の向上

目標: デフォルト設定の自動化で開発者の負担軽減

実装例：

デフォルトプルポリシー設定
デフォルトセキュリティコンテキスト追加
デフォルトアフィニティ設定

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: dev-defaults
spec:
  rules:
    - name: add-defaults
      match:
        resources:
          kinds:
            - Pod
      mutate:
        patchStrategicMerge:
          spec:
            containers:
              - (name): "*"
                imagePullPolicy: IfNotPresent
            securityContext:
              runAsNonRoot: true
              fsReadOnlyRootFilesystem: true

8. パフォーマンスと運用考慮事項

8.1 パフォーマンスへの影響

Webhook遅延

Kyvernoは各APIリクエストでWebhook呼び出しを発生させるため、以下の遅延が発生します：

ローカル処理: 1-5ms（ポリシー評価エンジン）
ネットワーク遅延: 5-20ms（API Server ← → Webhook）
合計: 通常 10-30ms

実装での最適化：
1. 不要なNamespaceでのポリシー除外
2. 大量リソース作成時のバッチ処理
3. Webhook Timeout設定の調整

リソース消費

Kyvernoコントローラーは以下のリソースを消費します：

# 推奨リソース設定（1000 Pods未満のクラスタ）
resources:
  requests:
    cpu: 100m
    memory: 256Mi
  limits:
    cpu: 500m
    memory: 512Mi

# 推奨リソース設定（1000+ Pods のクラスタ）
resources:
  requests:
    cpu: 200m
    memory: 512Mi
  limits:
    cpu: 1000m
    memory: 1Gi

8.2 ポリシー設計のベストプラクティス

(1) パフォーマンス最適化

# 推奨: 最小限のマッチング条件
rules:
  - name: efficient-rule
    match:
      resources:
        kinds:
          - Pod
        namespaces:
          - production
      operations:
        - CREATE
    validate:
      message: "..."
      pattern: {}

# 非推奨: 複雑すぎるパターン
rules:
  - name: inefficient-rule
    match:
      resources:
        kinds:
          - "*"
    validate:
      message: "..."
      pattern: {}

(2) ポリシー分離

大規模環境では、複数の小さなポリシーに分割：

# 分割前
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: all-in-one
spec:
  rules:
    - name: security-rules  # 10ルール
    - name: resource-rules  # 5ルール
    - name: compliance-rules # 8ルール

# 分割後
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: security-policies
spec:
  rules:
    - name: security-rules

---
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: resource-policies
spec:
  rules:
    - name: resource-rules

8.3 運用監視

Kyvernoメトリクスの監視

# Prometheus メトリクス例
kyverno_policy_execution_duration_seconds
kyverno_policy_results_total
kyverno_webhooks_processed_total
kyverno_policy_evaluate_duration_seconds
kyverno_policy_apply_duration_seconds

# AlertRule例
- alert: KyvernoWebhookLatencyHigh
  expr: histogram_quantile(0.99, kyverno_webhook_duration_seconds) > 1
  for: 5m

ログ監視

# Kyvernoコントローラーログ確認
kubectl logs -n kyverno deployment/kyverno -f

# 特定ポリシーのログ抽出
kubectl logs -n kyverno deployment/kyverno -f | grep "policy-name"

# 失敗したリクエスト確認
kubectl logs -n kyverno deployment/kyverno -f | grep -i "failed\|error"

8.4 トラブルシューティング

Webhookが応答しない場合

# 1. Kyvernoポッド状態確認
kubectl get pods -n kyverno

# 2. Webhookエンドポイント確認
kubectl get validatingwebhookconfigurations | grep kyverno

# 3. Webhook設定確認
kubectl describe validatingwebhookconfigurations \
  kyverno-resource-validating-webhook-cfg

# 4. ポッドログ確認
kubectl logs -n kyverno -l app=kyverno

ポリシーが適用されない場合

# 1. ポリシー存在確認
kubectl get clusterpolicies

# 2. ポリシー詳細確認
kubectl describe clusterpolicy policy-name

# 3. マッチング条件確認
kubectl get clusterpolicies policy-name -o yaml | grep -A 20 match

# 4. ルール結果確認（リソース作成後）
kubectl describe pod pod-name

9. トラブルシューティング

9.1 一般的な問題と対処法

問題1: "Admission webhook failed"エラー

Error: Admission webhook "validate.kyverno.io" denied the request

原因: ポリシー検証に失敗

対処法:

# ポリシー内容確認
kubectl get clusterpolicies policy-name -o yaml

# エラーメッセージ確認
kubectl get events -A | grep "webhook denied"

# ポリシー自体が正しいか確認
kubectl apply -f policy.yaml --dry-run=client

問題2: Webhookタイムアウト

Error: Webhook call timeout

原因: Kyvernoが応答せず、Timeout発生

対処法:

# Kyvernoリソース追加
kubectl -n kyverno edit deployment kyverno
# resources.limits.cpu を増加

# Webhook Timeout設定確認
kubectl get validatingwebhookconfigurations \
  kyverno-resource-validating-webhook-cfg -o yaml | \
  grep -A 5 "timeoutSeconds"

# Timeout増加（必要に応じて）
kubectl patch validatingwebhookconfigurations \
  kyverno-resource-validating-webhook-cfg \
  --type merge -p '{"webhooks":[{"name":"validate.kyverno.io","timeoutSeconds":5}]}'

問題3: Background processが動作しない

Generation ruleで作成されるべきリソースが生成されない

原因: Background Processor問題

対処法:

# Background処理ログ確認
kubectl logs -n kyverno deployment/kyverno | grep "background"

# ポリシー詳細確認
kubectl get clusterpolicies policy-name -o yaml | grep -A 10 generate

# ルール数制限確認（デフォルト: 1000）
kubectl logs -n kyverno deployment/kyverno | grep -i "limit"

9.2 デバッグ手法

ログレベル調整

# Kyvernoデプロイメント編集
kubectl -n kyverno edit deployment kyverno

# コンテナ引数に追加
spec:
  containers:
  - name: kyverno
    args:
      - --loggingFormat=json
      - --v=4  # ログレベル (1-5)

Audit Modeでのテスト

# ポリシーを先ずaudit modeで検証
spec:
  validationFailureAction: audit  # enforce の代わりに

# audit modeで問題ないことを確認後、enforce に変更
spec:
  validationFailureAction: enforce

10. ベストプラクティス

10.1 ポリシー設計

1. 小さく、焦点を絞ったポリシー

# 推奨: 1つのポリシーに1-2個のルール
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: restrict-privileged-containers
spec:
  rules:
    - name: privileged-containers
      # ...

# 非推奨: 複数の無関係なルール
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: all-rules
spec:
  rules:
    - name: rule1
    - name: rule2
    - name: rule3
    # ... 20個以上のルール

2. 明確なメッセージ

# 推奨: 具体的で実行可能なメッセージ
validate:
  message: >-
    Image must be from approved registries (gcr.io or docker.io).
    Current image: {{request.object.spec.containers[0].image}}

# 非推奨: 曖昧なメッセージ
validate:
  message: "Invalid configuration"

3. 段階的な展開

# Step 1: Audit mode で検証
spec:
  validationFailureAction: audit
  background: false  # クラスタ全体への影響を避ける

# Step 2: 特定Namespaceでのみ有効化
spec:
  rules:
    - match:
        resources:
          namespaces:
            - test

# Step 3: 全クラスタで有効化
spec:
  validationFailureAction: enforce

10.2 マルチテナント環境での考慮事項

1. Namespace単位のポリシー分離

# Namespace: team-a
apiVersion: kyverno.io/v1
kind: Policy
metadata:
  name: team-a-policies
  namespace: team-a
spec:
  rules:
    - name: team-a-specific
      # team-aのみに適用

# Namespace: team-b
apiVersion: kyverno.io/v1
kind: Policy
metadata:
  name: team-b-policies
  namespace: team-b
spec:
  rules:
    - name: team-b-specific
      # team-bのみに適用

# 全体共通
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: global-policies
spec:
  rules:
    - name: global-rule
      # 全Namespace対象

2. RBAC との連携

# Kyvernoへのアクセス制御
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: policy-admin
rules:
  - apiGroups: ["kyverno.io"]
    resources: ["clusterpolicies"]
    verbs: ["*"]
  - apiGroups: ["kyverno.io"]
    resources: ["policies"]
    verbs: ["*"]

---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: policy-admin
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: policy-admin
subjects:
  - kind: Group
    name: platform-team

10.3 例外処理

PolicyExceptionの活用

# ポリシー
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: require-labels
spec:
  rules:
    - name: check-labels
      match:
        resources:
          kinds:
            - Pod
      validate:
        message: "Required label: app"
        pattern:
          metadata:
            labels:
              app: "?*"

---
# 例外定義 (特定のPodを除外)
apiVersion: kyverno.io/v1alpha1
kind: PolicyException
metadata:
  name: legacy-app-exception
  namespace: legacy-apps
spec:
  rules:
    - name: check-labels
  match:
    resources:
      namespaces:
        - legacy-apps
      selector:
        matchLabels:
          legacy: "true"

11. 他のツールとの比較

11.1 OPA/Gatekeeper との比較

項目	Kyverno	OPA/Gatekeeper
ポリシー言語	YAML/CEL	Rego
学習曲線	低 (Kubernetes-native)	中～高 (Rego言語習得必要)
パフォーマンス	高速	中程度
Webhook統合	標準搭載	別途設定必要
Mutation機能	標準搭載	別途Rego実装必要
Generation機能	標準搭載	サポートなし
Kubernetes統合度	非常に高い	中程度
メンテナンス	CNCF sandbox	CNCF graduated

11.2 Kube-mgmt との比較

Kube-mgmt: ReplicaSet/Deploymentの変更を監視し、ConfigMap/Secretを同期

# Kube-mgmt: 特定ラベルの ConfigMap を全 Namespace に複製
# ラベル: app.kubernetes.io/part-of: namespace-config

# Kyverno: 同じ機能をポリシーで実現
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: sync-configmap-to-namespaces
spec:
  rules:
    - name: sync-config
      match:
        resources:
          kinds:
            - ConfigMap
          selector:
            matchLabels:
              app.kubernetes.io/part-of: namespace-config
      generate:
        kind: ConfigMap
        name: "{{request.object.metadata.name}}"
        namespace: "{{request.object.metadata.namespace}}"
        data: "{{request.object.data}}"

11.3 Kubewarden との比較

項目	Kyverno	Kubewarden
ポリシー言語	YAML/CEL	Rust/Go/Python等
実行環境	Go	WebAssembly (WASM)
パフォーマンス	高速 (Go)	非常に高速 (WASM)
セキュリティコンテキスト	カスタム対応	WASM境界により厳密
エコシステム	CNCF Kubernetes	より広範
言語自由度	低 (YAML/CEL固定)	高 (複数言語対応)

12. まとめ

12.1 Kyvernoの位置づけ

Kyvernoは、Kubernetes環境におけるポリシー・アズ・コードの標準的なツールとして確立しつつあります：

メリット:

Kubernetesネイティブで学習曲線が低い
シンプルなYAML形式で複雑なポリシーを表現可能
セキュリティ、リソース管理、コンプライアンスを統合的に実現
CNCF Sandbox projectとしての成熟度と信頼性

検討点:

複雑なビジネスロジックはCELでの実装が必要
非常に大規模なクラスタではパフォーマンス考慮
ポリシー数が増えるとメンテナンスコスト上昇

12.2 導入ロードマップ

Phase 1: パイロット (1ヶ月)

開発/テスト環境でのインストール
基本的な検証ポリシー実装 (セキュリティベースライン)
ドキュメント作成、チーム教育

Phase 2: 本番導入準備 (2ヶ月)

Audit modeでの全検証ポリシー適用
ポリシー例外の定義とドキュメント化
運用手順、トラブルシューティング資料作成

Phase 3: 本番展開 (1ヶ月)

Enforce modeへの段階的移行
Mutation/Generation ポリシーの導入
運用監視体制の構築

Phase 4: 最適化継続 (以降)

ポリシーの継続的改善
新しいセキュリティ脅威への対応
パフォーマンス監視と最適化

12.3 参考資料とリソース

公式ドキュメント:

学習リソース:

Kyverno Blog: https://kyverno.io/blog/
CNCF Slack: #kyverno チャネル
GitHub Issues/Discussions

ポリシーテンプレート:

Kyverno Policy Library: https://kyverno.io/policies/
Pod Security Policy (PSP) → Kyverno 移行ガイド

12.4 最後に

Kyvernoは、Kubernetesのセキュリティ、コンプライアンス、リソース管理を効率的に実現するための強力で実用的なツールです。Kubernetes-nativeなアプローチと柔軟性により、様々な組織規模と要件に対応できます。

段階的な導入と継続的な改善を通じて、堅牢で安全、かつ効率的なKubernetes環境を構築できるでしょう。

作成日: 2026年4月7日 バージョン: 1.0 言語: 日本語

Kyverno

Kyverno: Kubernetes Policy as Code の完全ガイド

目次

1. はじめに

Kyvernoとは

主な特徴

なぜKyvernoが必要か

2. Kyvernoの基本概念

2.1 Policy (ポリシー)

2.2 Rule (ルール)

2.3 Policy操作モード

(1) Validation (検証)

(2) Mutation (変更)

(3) Generation (生成)

(4) Cleanup (クリーンアップ)

2.4 マッチング戦略

3. アーキテクチャ概要

3.1 全体構成

3.2 主要コンポーネント

(1) Policy Engine

(2) ValidatingAdmissionWebhook

(3) Background Processor

(4) Audit Logger

3.3 デプロイメント

4. Policy (ポリシー) の種類

4.1 検証ポリシー (Validation Policy)

4.2 変更ポリシー (Mutation Policy)

4.3 生成ポリシー (Generation Policy)

4.4 クリーンアップポリシー (Cleanup Policy)

5. ルールマッチング機構

5.1 マッチング条件

Match セクション

Exclude セクション

5.2 パターンマッチング

(1) ワイルドカード

(2) 複数パターン (OR)

(3) 存在チェック

(4) 空でない検証

5.3 CEL (Common Expression Language)

6. 設定の具体例

6.1 セキュリティ関連の実用的な例

例1: ホストパスアクセスの禁止

例2: seLinuxオプションの強制

例3: Privileged Containerの禁止

6.2 リソース管理の実用例

例4: CPU/Memory リクエストとリミットの強制

例5: メモリリクエストとリミットの比率チェック

6.3 コンプライアンス関連の実用例

例6: ラベルの強制

例7: Imageプルポリシーの自動設定

6.4 ネットワークポリシー生成の実用例

例8: Namespace作成時のネットワークポリシー自動生成

6.5 マルチテナント環境での設定例

例9: Namespace内でのポリシー制限

7. ユースケース

7.1 セキュリティ管理

7.2 リソース管理と効率化

7.3 コンプライアンスと監査

7.4 開発生産性の向上

8. パフォーマンスと運用考慮事項

8.1 パフォーマンスへの影響

Webhook遅延

リソース消費

8.2 ポリシー設計のベストプラクティス

(1) パフォーマンス最適化

(2) ポリシー分離

8.3 運用監視

Kyvernoメトリクスの監視

ログ監視

8.4 トラブルシューティング

Webhookが応答しない場合

ポリシーが適用されない場合

9. トラブルシューティング

9.1 一般的な問題と対処法

問題1: "Admission webhook failed"エラー

問題2: Webhookタイムアウト

問題3: Background processが動作しない

9.2 デバッグ手法

ログレベル調整

Audit Modeでのテスト