Kubernetes Admission Policy Parameter Management

Kubernetes Admission Policy Parameter Management is the practice of designing, provisioning, and maintaining the parameter resources that a ValidatingAdmissionPolicy consumes through its paramKind declaration, allowing a single policy's CEL logic to be reused with different configurable values across different bindings, rather than hardcoding specific thresholds or allowed lists directly into the policy expression itself.

Declaring a Parameter Kind

paramKind on the Policy

A policy declares the API group, version, and kind of the resource type it expects as parameters via paramKind, and its CEL expressions reference the resolved parameter data through the params variable, keeping the policy's logic generic over whatever specific values a given binding supplies.

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicy
metadata:
  name: enforce-allowed-registries
spec:
  paramKind:
    apiVersion: policy.example.com/v1
    kind: RegistryAllowlist
  matchConstraints:
    resourceRules:
    - apiGroups: [""]
      apiVersions: ["v1"]
      operations: ["CREATE"]
      resources: ["pods"]
  validations:
  - expression: >
      object.spec.containers.all(c,
        params.allowedPrefixes.exists(p, c.image.startsWith(p)))
    message: "container image must come from an approved registry"

Defining the Parameter Resource Type

The parameter kind itself is typically a Custom Resource, requiring its own CustomResourceDefinition to be registered before it can be referenced, with a schema designed specifically to hold the configurable values the policy's CEL expressions need.

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: registryallowlists.policy.example.com
spec:
  group: policy.example.com
  names:
    kind: RegistryAllowlist
    plural: registryallowlists
  scope: Cluster
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              allowedPrefixes:
                type: array
                items: { type: string }

Provisioning Parameter Instances

Creating Concrete Parameter Objects

Once the parameter kind is registered, specific instances hold the actual configured values, and different bindings can reference different instances to apply different thresholds in different contexts.

apiVersion: policy.example.com/v1
kind: RegistryAllowlist
metadata:
  name: production-registries
spec:
  allowedPrefixes:
  - "registry.internal.example.com/"
  - "gcr.io/distroless/"

Referencing Parameters From a Binding

A binding's paramRef points to a specific named parameter instance (optionally namespaced), and can also use a label selector to match multiple instances at once, in which case the policy is evaluated once per matching parameter object.

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicyBinding
metadata:
  name: registry-check-production
spec:
  policyName: enforce-allowed-registries
  paramRef:
    name: production-registries
  validationActions: ["Deny"]

Handling Missing or Absent Parameters

paramRef.default Behavior

A binding can specify how to behave when its referenced parameter object does not exist, via the parameter kind's configured default behavior on the policy (Allow or Deny), which should be set deliberately rather than left to an implicit default, since a missing parameter resource combined with a permissive default could silently disable enforcement entirely.

spec:
  paramKind:
    apiVersion: policy.example.com/v1
    kind: RegistryAllowlist
  failurePolicy: Fail

Governance of Parameter Resources

Access Control Over Parameter Objects

Because modifying a parameter resource changes the effective behavior of every binding referencing it without touching the policy or binding objects themselves, write access to parameter resources should be governed by RBAC with the same rigor as access to the policies and bindings that depend on them — a change to an allowlist parameter is functionally equivalent to a policy change.

Namespacing Parameters Appropriately

Choosing whether a parameter kind is namespaced or cluster-scoped should reflect whether the configuration genuinely varies per namespace or represents a single, cluster-wide source of truth; namespaced parameters allow different teams to maintain their own configuration values independently, while cluster-scoped parameters centralize control for values that should not vary by tenant.

Auditing Parameter Usage

Tracing Effective Configuration

Because a policy's actual enforced behavior depends on the combination of its CEL logic and whichever parameter instance a given binding references, auditing a policy's real-world effect requires inspecting the bound parameter object's current values alongside the policy definition, not the policy definition in isolation.

kubectl get registryallowlists production-registries -o yaml