Enforce Policy as Code

Declarative policy enforce → OPA Gatekeeper or Kyverno. K8s resource validate + mutate.

Use When

• Enforce org standards (labels, annotations, limits)
• Prevent security misconfig (privileged containers, host namespaces, insecure images)
• Compliance before deploy
• Standardize naming + metadata
• Auto remediate via mutation
• Audit existing resources no block
• CI/CD shift-left

In

• Required: K8s cluster w/ admin
• Required: Engine choice (OPA Gatekeeper or Kyverno)
• Required: Policy list (security, compliance, ops)
• Optional: Existing resources to audit
• Optional: Exemption patterns (namespaces/resources)
• Optional: CI/CD config for pre-deploy validate

Do

See Extended Examples for complete configuration files and templates.

Step 1: Install Engine

Deploy OPA Gatekeeper or Kyverno as admission controller.

OPA Gatekeeper:

# 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:

# 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

NS exclusions:

# 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

→ Engine pods HA. CRDs installed (ConstraintTemplate, Constraint / ClusterPolicy, Policy). Webhooks active. Audit running.

If err:

• Pod logs: kubectl logs -n gatekeeper-system -l app=gatekeeper --tail=50
• Endpoints: kubectl get endpoints -n gatekeeper-system
• Port/cert issues in webhook logs
• Resources sufficient (~500MB/replica)
• RBAC: kubectl auth can-i create constrainttemplates --as=system:serviceaccount:gatekeeper-system:gatekeeper-admin

Step 2: Define Templates + Policies

Reusable templates + constraints.

OPA Gatekeeper Template:

# required-labels-template.yaml
apiVersion: templates.gatekeeper.sh/v1
kind: ConstraintTemplate
metadata:
  name: k8srequiredlabels
  annotations:
# ... (see EXAMPLES.md for complete configuration)

Kyverno ClusterPolicy:

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

Apply:

# 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

→ Templates/Policies created. Status "True" enforce. No err. Webhook evals new resources.

If err:

• Rego syntax (Gatekeeper): opa test locally or check status
• YAML: kubectl apply --dry-run=client -f policy.yaml
• Status: kubectl get constraint -o yaml | grep -A 10 status
• Simple first, add complexity
• Match criteria correct (kinds, namespaces)

Step 3: Test Enforcement

Validate block non-compliant, allow compliant.

Test manifests:

# test-non-compliant.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: test-no-labels
  namespace: production
# ... (see EXAMPLES.md for complete configuration)

Test:

# 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

Policy reporting (Kyverno):

# 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 .

→ Non-compliant rejected w/ clear msg. Compliant created. Reports show pass/fail. Dry-run works.

If err:

• Audit mode not enforce: validationFailureAction: audit
• Webhook processing: kubectl logs -n gatekeeper-system -l app=gatekeeper
• NS exclusions exempting test ns
• Webhook connectivity: kubectl run test --rm -it --image=busybox --restart=Never
• Failure policy (Ignore vs Fail)

Step 4: Mutation Policies

Auto remediate via mutation.

Gatekeeper:

# gatekeeper-mutations.yaml
apiVersion: mutations.gatekeeper.sh/v1beta1
kind: Assign
metadata:
  name: add-default-labels
spec:
# ... (see EXAMPLES.md for complete configuration)

Kyverno:

# kyverno-mutations.yaml
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: add-default-labels
spec:
# ... (see EXAMPLES.md for complete configuration)

Apply + test:

# 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)

→ Mutations auto add labels/resources/modify images. Mutated values visible. Logged. No err.

If err:

• Mutation webhook enabled: kubectl get mutatingwebhookconfiguration
• Syntax: JSON paths + conditions
• Logs: kubectl logs -n kyverno deploy/kyverno-admission-controller
• No conflicts (multiple mutations same field)
• Mutation before validation (order matters)

Step 5: Audit + Reporting

Audit identifies violations no block.

Gatekeeper audit:

# 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 audit + reporting:

# 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)

Dashboard:

# prometheus-rules.yaml
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: policy-alerts
  namespace: monitoring
# ... (see EXAMPLES.md for complete configuration)

→ Audit finds violations no block. Reports generated pass/fail. Exportable. Metrics. Alerts.

If err:

• Audit controller: kubectl get pods -n gatekeeper-system -l gatekeeper.sh/operation=audit
• Audit interval setting
• Audit logs: kubectl logs -n gatekeeper-system -l gatekeeper.sh/operation=audit
• RBAC read all resource types
• CRD status populated: kubectl get constraint -o yaml | grep -A 20 status

Step 6: CI/CD Integration

Pre-deploy validation → shift-left.

CI/CD script:

#!/bin/bash
# validate-policies.sh

set -e

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

GitHub Actions:

# .github/workflows/policy-validation.yaml
name: Policy Validation

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

Pre-commit:

#!/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)

→ Pipeline validates pre-deploy. Violations fail w/ clear msg. Reports on PR. Pre-commit catches early. Devs notified pre-cluster.

If err:

• CLI tools in PATH
• kubeconfig creds valid
• Test locally: kyverno apply policy.yaml --resource manifest.yaml
• Policies synced complete
• Policy CLI logs for specific errs

Check

• Engine pods HA
• Webhooks active + reachable
• Templates + policies created no err
• Non-compliant rejected clear msg
• Compliant deploy OK
• Mutations auto remediate
• Audit finds violations existing
• Reports generated + accessible
• Metrics exposed
• CI/CD validates pre-deploy
• Pre-commit prevents
• NS exclusions appropriate

Traps

• Webhook Failure Policy: failurePolicy: Fail blocks all if webhook down. Ignore non-critical, understand security. Test availability before enforce.
• Too Strict Initial: Strict enforce breaks workloads. Audit first, review, communicate, enforce gradual.
• Missing Resource Specs: Must specify API groups/versions/kinds. kubectl api-resources. Wildcards (*) convenient but slow.
• Mutation Order: Mutation before validation. No conflicts. Test together.
• NS Exclusions: Exclude system ns necessary but not over-exclude. Review regularly.
• Rego Complexity (Gatekeeper): Complex Rego hard debug. Simple first, opa test locally, trace() logging, gator offline.
• Perf Impact: Policy eval adds latency. Efficient policies, right match criteria, monitor webhook latency.
• Policy Conflicts: Multiple policies same field → issues. Coordinate teams, policy libs, test combos.
• Bg Scanning: Full cluster scan expensive large clusters. Adjust interval.
• Version Compat: CRD versions change. Gatekeeper v3 → v1beta1, Kyverno v1.11 → kyverno.io/v1. Check docs.

→

• manage-kubernetes-secrets - Secret validation policies
• security-audit-codebase - Complementary security scanning
• deploy-to-kubernetes - App deployment w/ policy validate
• setup-service-mesh - Mesh authz policies complement admission
• configure-api-gateway - Gateway policies alongside admission
• implement-gitops-workflow - GitOps w/ policy validate in pipeline