# Enforce Policy As Code

> OPA GatekeeperまたはKyvernoを使用したポリシーアズコード強制を実装し、組織のポリシーに従って Kubernetesリソースを検証・変異させます。制約テンプレート、アドミッションコントロール、 監査モード、違反のレポート、CI/CDパイプラインとの統合によるシフトレフトポリシー検証を カバーします。リソース設定標準の強制、特権コンテナなどのセキュリティ誤設定の防止、 デプロイ前のコンプライアンス確保、命名規則の標準化、または既存クラスターリソースのポリシー 監査を行う場合に使用します。

- Skill: `pjt222/enforce-policy-as-code-3` (Agent Skill)
- Install (CLI): `npx get-skill add pjt222/enforce-policy-as-code-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pjt222/enforce-policy-as-code-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: pjt222 (https://skillmd.com/u/pjt222)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/pjt222/enforce-policy-as-code-3

---


# ポリシーアズコードの強制

OPA GatekeeperまたはKyvernoを使用した宣言的ポリシー強制でKubernetesリソースの検証と変異を実装します。

## 使用タイミング

- リソース設定の組織標準を強制（ラベル、アノテーション、制限）
- セキュリティの誤設定を防止（特権コンテナ、ホストNamespace、セキュアでないイメージ）
- リソースのデプロイ前にコンプライアンス要件を満たすことを確保
- リソース命名規則とメタデータの標準化
- 変異ポリシーによる自動修復の実装
- デプロイをブロックせずに既存クラスターリソースを監査
- シフトレフトアプローチのためにCI/CDパイプラインにポリシー検証を統合

## 入力

- **必須**: 管理者アクセス権付きのKubernetesクラスター
- **必須**: ポリシーエンジンの選択（OPA GatekeeperまたはKyverno）
- **必須**: 強制するポリシーのリスト（セキュリティ、コンプライアンス、運用）
- **任意**: 監査する既存リソース
- **任意**: 特定のNamespaceまたはリソースの免除/除外パターン
- **任意**: デプロイ前検証のためのCI/CDパイプライン設定

## 手順

> 完全な設定ファイルとテンプレートについては[拡張例](references/EXAMPLES.md)を参照してください。


### ステップ1: ポリシーエンジンのインストール

アドミッションコントローラーとしてOPA GatekeeperまたはKyvernoをデプロイします。

**OPA Gatekeeperの場合：**
```bash
# Install Gatekeeper using Helm
helm repo add gatekeeper https://open-policy-agent.github.io/gatekeeper/charts
helm repo update

# Install with audit enabled
helm install gatekeeper gatekeeper/gatekeeper \
  --namespace gatekeeper-system \
  --create-namespace \
  --set audit.replicas=2 \
  --set replicas=3 \
  --set validatingWebhookFailurePolicy=Fail \
  --set auditInterval=60

# Verify installation
kubectl get pods -n gatekeeper-system
kubectl get crd | grep gatekeeper

# Check webhook configuration
kubectl get validatingwebhookconfigurations gatekeeper-validating-webhook-configuration -o yaml
```

**Kyvernoの場合：**
```bash
# Install Kyverno using Helm
helm repo add kyverno https://kyverno.github.io/kyverno/
helm repo update

# Install with HA setup
helm install kyverno kyverno/kyverno \
  --namespace kyverno \
  --create-namespace \
  --set replicaCount=3 \
  --set admissionController.replicas=3 \
  --set backgroundController.replicas=2 \
  --set cleanupController.replicas=2

# Verify installation
kubectl get pods -n kyverno
kubectl get crd | grep kyverno

# Check webhook configurations
kubectl get validatingwebhookconfigurations kyverno-resource-validating-webhook-cfg
kubectl get mutatingwebhookconfigurations kyverno-resource-mutating-webhook-cfg
```

Namespaceの除外を作成します：
```yaml
# gatekeeper-config.yaml
apiVersion: config.gatekeeper.sh/v1alpha1
kind: Config
metadata:
  name: config
  namespace: gatekeeper-system
spec:
  match:
    - excludedNamespaces:
      - kube-system
      - kube-public
      - kube-node-lease
      - gatekeeper-system
      processes:
      - audit
      - webhook
  validation:
    traces:
      - user: system:serviceaccount:gatekeeper-system:gatekeeper-admin
        kind:
          group: ""
          version: v1
          kind: Namespace
```

**期待結果：** ポリシーエンジンのPodが複数レプリカで稼働中。CRDがインストール済み（GatekeeperはConstraintTemplate、Constraint；KyvernoはClusterPolicy、Policy）。検証/変異Webhookが有効。監査コントローラーが稼働中。

**失敗時：**
- Podのログを確認：`kubectl logs -n gatekeeper-system -l app=gatekeeper --tail=50`
- Webhookエンドポイントが到達可能か確認：`kubectl get endpoints -n gatekeeper-system`
- Webhookのログでポートの競合や証明書の問題を確認
- クラスターに十分なリソースがあることを確認（ポリシーエンジンはレプリカ毎に約500MB必要）
- RBACパーミッションを確認：`kubectl auth can-i create constrainttemplates --as=system:serviceaccount:gatekeeper-system:gatekeeper-admin`

### ステップ2: 制約テンプレートとポリシーの定義

再利用可能なポリシーテンプレートと特定の制約を作成します。

**OPA Gatekeeper制約テンプレート：**
```yaml
# required-labels-template.yaml
apiVersion: templates.gatekeeper.sh/v1
kind: ConstraintTemplate
metadata:
  name: k8srequiredlabels
  annotations:
# ... (see EXAMPLES.md for complete configuration)
```

**Kyverno ClusterPolicy：**
```yaml
# kyverno-policies.yaml
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: require-labels
  annotations:
# ... (see EXAMPLES.md for complete configuration)
```

ポリシーを適用：
```bash
# Apply Gatekeeper templates and constraints
kubectl apply -f required-labels-template.yaml

# Apply Kyverno policies
kubectl apply -f kyverno-policies.yaml

# Verify constraint/policy status
kubectl get constraints
kubectl get clusterpolicies

# Check for any policy errors
kubectl describe k8srequiredlabels require-app-labels
kubectl describe clusterpolicy require-labels
```

**期待結果：** ConstraintTemplate/ClusterPolicyが正常に作成済み。制約がenforcement状態で「True」を表示。ポリシー定義にエラーなし。Webhookが新しいリソースのポリシー評価を開始。

**失敗時：**
- Rego構文を検証（Gatekeeper）：ローカルで`opa test`を使用するか制約ステータスを確認
- ポリシーYAML構文を確認：`kubectl apply --dry-run=client -f policy.yaml`
- 制約のステータスを確認：`kubectl get constraint -o yaml | grep -A 10 status`
- まずシンプルなポリシーでテストしてから複雑にする
- マッチ基準（kinds、namespaces）が正しいか確認

### ステップ3: ポリシー強制のテスト

ポリシーが非準拠リソースをブロックし、準拠リソースを許可することを確認します。

テストマニフェストを作成：
```yaml
# test-non-compliant.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: test-no-labels
  namespace: production
# ... (see EXAMPLES.md for complete configuration)
```

ポリシーをテスト：
```bash
# Attempt to create non-compliant resource (should fail)
kubectl apply -f test-non-compliant.yaml
# Expected: Error with policy violation message

# Create compliant resource (should succeed)
kubectl apply -f test-compliant.yaml
# Expected: deployment.apps/test-compliant created

# Test with dry-run for validation
kubectl apply -f test-non-compliant.yaml --dry-run=server
# Shows policy violations without actually creating resource

# Clean up
kubectl delete -f test-compliant.yaml
```

ポリシーレポートでテスト（Kyverno）：
```bash
# Check policy reports
kubectl get policyreports -A
kubectl get clusterpolicyreports

# View detailed report
kubectl get policyreport -n production -o yaml

# Check policy rule results
kubectl get policyreport -n production -o jsonpath='{.items[0].results}' | jq .
```

**期待結果：** 非準拠リソースが明確な違反メッセージで拒否。準拠リソースが正常に作成。ポリシーレポートが合格/不合格の結果を表示。ドライラン検証がリソースを作成せずに機能。

**失敗時：**
- ポリシーがenforceモードではなくauditモードになっていないか確認：`validationFailureAction: audit`
- WebhookがリクエストをProcessingしているか確認：`kubectl logs -n gatekeeper-system -l app=gatekeeper`
- テストNamespaceを除外しているNamespace除外がないか確認
- Webhook接続をテスト：`kubectl run test --rm -it --image=busybox --restart=Never`
- Webhookの失敗ポリシー（IgnoreとFail）を確認

### ステップ4: 変異ポリシーの実装

変異による自動修復を設定します。

**Gatekeeperの変異：**
```yaml
# gatekeeper-mutations.yaml
apiVersion: mutations.gatekeeper.sh/v1beta1
kind: Assign
metadata:
  name: add-default-labels
spec:
# ... (see EXAMPLES.md for complete configuration)
```

**Kyvernoの変異ポリシー：**
```yaml
# kyverno-mutations.yaml
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: add-default-labels
spec:
# ... (see EXAMPLES.md for complete configuration)
```

変異を適用してテスト：
```bash
# Apply mutation policies
kubectl apply -f gatekeeper-mutations.yaml
# OR
kubectl apply -f kyverno-mutations.yaml

# Test mutation with a deployment
# ... (see EXAMPLES.md for complete configuration)
```

**期待結果：** 変異がラベル、リソース、またはイメージを自動的に追加/変更。デプロイされたリソースが変異された値を表示。変異がポリシーエンジンのログに記録。変異適用中にエラーなし。

**失敗時：**
- 変異Webhookが有効か確認：`kubectl get mutatingwebhookconfiguration`
- 変異ポリシーの構文を確認：特にJSONパスと条件
- ログを確認：`kubectl logs -n kyverno deploy/kyverno-admission-controller`
- 変異が競合しないか確認（同じフィールドへの複数の変異）
- 変異が検証より先に適用されることを確認（順序が重要）

### ステップ5: 監査モードとレポートの有効化

デプロイをブロックせずに既存リソースの違反を特定するための監査を設定します。

**Gatekeeperの監査：**
```bash
# Audit runs automatically based on auditInterval setting
# Check audit results
kubectl get constraints -o json | \
  jq '.items[] | {name: .metadata.name, violations: .status.totalViolations}'

# Get detailed violation information
# ... (see EXAMPLES.md for complete configuration)
```

**Kyvernoの監査とレポート：**
```bash
# Generate policy reports for existing resources
kubectl create job --from=cronjob/kyverno-cleanup-controller -n kyverno manual-report-gen

# View policy reports
kubectl get policyreport -A
kubectl get clusterpolicyreport
# ... (see EXAMPLES.md for complete configuration)
```

ポリシーコンプライアンスのダッシュボードを作成：
```yaml
# prometheus-rules.yaml
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: policy-alerts
  namespace: monitoring
# ... (see EXAMPLES.md for complete configuration)
```

**期待結果：** 監査がデプロイをブロックせずに既存リソースの違反を特定。合格/不合格の数でポリシーレポートが生成済み。違反がレビューのためにエクスポート可能。メトリクスがモニタリング用に公開。増加する違反でアラートが発火。

**失敗時：**
- 監査コントローラーが稼働中か確認：`kubectl get pods -n gatekeeper-system -l gatekeeper.sh/operation=audit`
- インストール時の監査間隔設定を確認
- 監査ログでエラーを確認：`kubectl logs -n gatekeeper-system -l gatekeeper.sh/operation=audit`
- RBACパーミッションが監査のために全リソースタイプの読み取りを許可していることを確認
- CRDのstatusフィールドが設定されているか確認：`kubectl get constraint -o yaml | grep -A 20 status`

### ステップ6: CI/CDパイプラインとの統合

デプロイ前検証をシフトレフトポリシー強制に追加します。

**CI/CD統合スクリプト：**
```bash
#!/bin/bash
# validate-policies.sh

set -e

echo "=== Policy Validation for CI/CD ==="
# ... (see EXAMPLES.md for complete configuration)
```

**GitHub Actionsワークフロー：**
```yaml
# .github/workflows/policy-validation.yaml
name: Policy Validation

on:
  pull_request:
    paths:
# ... (see EXAMPLES.md for complete configuration)
```

**プリコミットフック：**
```bash
#!/bin/bash
# .git/hooks/pre-commit

# Validate Kubernetes manifests against policies
if git diff --cached --name-only | grep -E 'manifests/.*\.yaml$'; then
  echo "Validating Kubernetes manifests against policies..."
# ... (see EXAMPLES.md for complete configuration)
```

**期待結果：** CI/CDパイプラインがデプロイ前にマニフェストを検証。ポリシー違反がパイプラインを明確なメッセージで失敗。ポリシーレポートがPRに添付。プリコミットフックが早期に違反を検出。開発者がクラスターに達する前にポリシーの問題を通知。

**失敗時：**
- CLIツールがインストールされPATHに含まれているか確認
- Kubeconfig証明書がポリシーのフェッチに有効か確認
- まずローカルでポリシー検証をテスト：`kyverno apply policy.yaml --resource manifest.yaml`
- クラスターから同期されたポリシーが完全か確認
- 特定の検証エラーのポリシーCLIログを確認

## バリデーション

- [ ] ポリシーエンジンのPodがHA構成で稼働中
- [ ] 検証と変異のWebhookが有効かつ到達可能
- [ ] 制約テンプレートとポリシーがエラーなしで作成済み
- [ ] 非準拠リソースが明確な違反メッセージで拒否
- [ ] 準拠リソースが正常にデプロイ
- [ ] 変異ポリシーがリソースを自動修復
- [ ] 監査モードが既存リソースの違反を特定
- [ ] ポリシーレポートが生成されアクセス可能
- [ ] ポリシーコンプライアンス監視のためのメトリクスが公開
- [ ] CI/CDパイプラインがデプロイ前にマニフェストを検証
- [ ] プリコミットフックがポリシー違反を防止
- [ ] Namespace除外が適切に設定済み

## よくある落とし穴

- **Webhookの失敗ポリシー**: `failurePolicy: Fail`はWebhookが利用できない場合に全リソースをブロックする。重要でないポリシーには`Ignore`を使用するが、セキュリティへの影響を理解する。強制前にWebhookの可用性をテストする。

- **過度に制限的な初期ポリシー**: 厳格なポリシーをenforceモードで始めると既存のワークロードが壊れる。監査モードから始め、違反を確認し、チームに伝えてから徐々に強制する。

- **リソース指定の欠如**: ポリシーはAPIグループ、バージョン、kindsを正確に指定する必要がある。`kubectl api-resources`で正確な値を見つける。ワイルドカード（`*`）は便利だがパフォーマンスの問題を引き起こす可能性がある。

- **変異の順序**: 変異は検証より先に適用される。変異が競合しないこと、検証が変異された値を考慮することを確認する。変異+検証を一緒にテストする。

- **Namespace除外**: システムNamespaceの除外は必要だが、過度に除外しないよう注意する。ポリシーが成熟するにつれて定期的に除外を確認する。

- **Regoの複雑さ（Gatekeeper）**: 複雑なRegoポリシーはデバッグが難しい。シンプルから始め、ローカルで`opa test`でテストし、`trace()`でログを追加し、オフラインテストにgatorを使用する。

- **パフォーマンスへの影響**: ポリシー評価がアドミッションにレイテンシを追加する。ポリシーを効率的に保ち、適切なマッチング基準を使用し、Webhookのレイテンシメトリクスを監視する。

- **ポリシーの競合**: 同じフィールドを変更する複数のポリシーが問題を引き起こす。チーム間でポリシーを調整し、共通パターンにはポリシーライブラリを使用し、組み合わせをテストする。

- **バックグラウンドスキャン**: バックグラウンド監査がクラスター全体をスキャンする。大きなクラスターではリソースを大量消費する可能性がある。クラスターのサイズとポリシーの数に基づいて監査間隔を調整する。

- **バージョンの互換性**: ポリシーCRDのバージョンが変わる。Gatekeeper v3は`v1beta1`制約を使用、Kyverno v1.11は`kyverno.io/v1`を使用。お使いのバージョンのドキュメントを確認する。

## 関連スキル

- `manage-kubernetes-secrets` - シークレット検証ポリシー
- `security-audit-codebase` - 補完的なセキュリティスキャン
- `deploy-to-kubernetes` - ポリシー検証付きのアプリケーションデプロイ
- `setup-service-mesh` - サービスメッシュ認可ポリシーがアドミッションポリシーを補完
- `configure-api-gateway` - ゲートウェイポリシーがアドミッションポリシーと連携
- `implement-gitops-workflow` - パイプラインでのポリシー検証付きGitOps

