This is unreleased documentation for Policy Manager 1.23-next.

Context aware policies

Developers can create policies that fetch information from a Kubernetes cluster at run time. These are context aware policies. Context aware policies can determine whether an AdmissionRequest is acceptable using information from resources deployed in the cluster.

Context aware policies are only available in Kubewarden versions ≥ v1.6.0.

Control of which resources a policy can access in the cluster is by by the policy server’s Service Account. A cluster administrator controls what a policy can access via Kubernetes RBAC rules. Context aware policies have only read access to the requested resources.

For security reasons, only ClusterAdmissionPolicy policies can fetch information from the Kubernetes cluster. This is because unprivileged users can deploy AdmissionPolicy resources.

If an unprivileged user deploys a context aware policy as an AdmissionPolicy, the system:

Blocks all attempts to access Kubernetes resources.
Reports them to the cluster administrator.

By default, Kubewarden blocks all cluster resources. A Kubewarden administrator defines which Kubernetes resources each context aware policy can read. contextAwareResources to do this.

The following example deploys a policy that requires access to the Deployment and Pod resources:

apiVersion: policies.kubewarden.io/v1
kind: ClusterAdmissionPolicy
metadata:
  name: context-aware-policy
  namespace: default
spec:
  policyServer: default
  module: "registry://ghcr.io/kubewarden/policies/context-aware-policy:v1.0.0"
  settings: {}
  contextAwareResources:
    - apiVersion: "apps/v1"
      kind: "deployment"
    - apiVersion: "v1"
      kind: "pod"
  rules:
    - apiGroups: ["apps"]
      apiVersions: ["v1"]
      resources: ["deployment"]
      operations:
        - CREATE
        - UPDATE
  mutating: false

Once deployed, this policy can read the data of the deployment and pod resources.

Policy authors provide lists of Kubernetes resources for their context aware policy. Policy authors do this by annotating the policy. Kubewarden administrators view policy metadata using the kwctl inspect command. They can get a list of resources the policy needs access to. An administrator uses this list to populate the ClusterAdmissionPolicy definition.

To prevent system abuse, Kubewarden administrators must review the resources the policy accesses.

For example, a policy evaluating ingress objects would have good reasons to read the Ingress resources defined in the cluster. The same policy can’t justify having access to Secret resources.

Policies should have the minimum access needed to function correctly.

Kubernetes resource identification uses apiVersion and kind.

Usually, apiVersion is a string in the format <api>/<version>. Resources from the core API group (Pod, Service, and others) shouldn’t define the group name, <api>. They should only define the <version> (for example, v1).

For a core resource, the first won’t work, the second will.

- apiVersion: "core/v1"
  kind: "pod"

- apiVersion: "v1"
  kind: "pod"

All other Kubernetes resources need the full definition: <api>/<version>.

Context aware policies

Further readings