Kubewarden is a Kubernetes Dynamic Admission Controller that uses policies written in WebAssembly.

For more information refer to the official Kubewarden website.

Kubewarden Admission Controller - Monorepo

This repository is a monorepo containing the source code for all the different components of the Kubewarden Admission Controller:

• adm-controller: A Kubernetes controller that allows you to dynamically register Kubewarden admission policies and reconcile them with the Kubernetes webhooks of the cluster where it's deployed
• policy-server: The runtime component that evaluates admission policies written in WebAssembly
• audit-scanner: A component that scans existing resources in the cluster against registered policies
• kwctl: A CLI tool for testing and managing Kubewarden policies

Documentation

The full and exhaustive documentation is available at docs.kubewarden.io.

The docs/ folder contains README files for each component:

• Controller
• Policy Server
• Audit Scanner
• kwctl
• CRDs

Installation

The adm-controller can be deployed using a Helm chart. For instructions, see https://charts.kubewarden.io.

Please refer to our quickstart for more details.

Note: This chart replaces the three separate charts that were used previously: kubewarden-crds, kubewarden-controller, and kubewarden-defaults.

Migration from three-chart setup

Please refer to the migration guide in the documentation for instructions on migrating from the legacy kubewarden-crds, kubewarden-controller, and kubewarden-defaults charts to the unified admission-controller chart.

Configuration

Defaults

The chart can deploy a default Policy Server and recommended policies:

policyServer:
  enabled: true
  replicaCount: 1
  # ... (see values.yaml for full options)

recommendedPolicies:
  enabled: false # disabled by default
  defaultPolicyMode: "monitor"
  allowPrivilegeEscalationPolicy:
    # ... (see values.yaml)

These resources are owned and reconciled by the controller. Manual changes are reverted on the next reconciliation. Setting enabled to false removes all managed resources.

Resources that namespaced policies can target

Namespaced policies (AdmissionPolicy and AdmissionPolicyGroup) can target only the resources listed in namespacedPoliciesAllowedResources. ClusterAdmissionPolicy and ClusterAdmissionPolicyGroup are not affected. A policy that targets both permitted and not permitted resources is rejected as a whole.

namespacedPoliciesAllowedResources:
  - apiGroups: [""]
    resources: [pods, configmaps, secrets]
  - apiGroups: ["apps"]
    resources: [deployments, statefulsets]

Each entry has the same shape as the apiGroups and resources fields of a policy rule. Wildcards (*) and subresources (pods/exec) are not permitted in this list. The controller skips these items and logs them. A policy rule that targets a subresource of a permitted resource is permitted.

The controller accepts a namespaced policy that targets other resources, but it does not deploy the policy. The policy status is rejected. The PolicyActive condition lists the resources that are not permitted. When you add these resources to the list, the controller deploys the policy.

The chart comes with a default list of Kubernetes resources that are considered safe to be validated or mutated by namespaced policies.

CRDs

CRDs are installed with the helm.sh/resource-policy: keep annotation:

• helm upgrade updates CRDs normally
• helm uninstall does not delete CRDs, which prevents cascade-deletion of all PolicyServers and policies in the cluster

Reinstalling under a different release name or namespace

Because the CRDs are kept on uninstall, they survive with the Helm ownership metadata of the release that created them (meta.helm.sh/release-name and meta.helm.sh/release-namespace). Helm checks this metadata on the next install:

• Same release name and namespace: Helm adopts the existing CRDs and the install succeeds.

• Different release name or namespace: Helm refuses to take over the CRDs and the install fails with:

  Error: ... invalid ownership metadata; annotation
  meta.helm.sh/release-name must equal "<new>": current value is "<old>"
  

This is expected: the CRDs still belong to the previous release. To adopt them into the new release, install with --take-ownership (Helm 3.18+ or Helm 4), which re-stamps the ownership metadata:

helm install <release> <chart> -n <namespace> --take-ownership

Uninstall

helm uninstall kubewarden-controller -n kubewarden

This removes:

• The controller Deployment
• Managed defaults (resources labeled kubewarden.io/managed-by=kubewarden-controller-defaults)
• ConfigMaps, Secrets, Services

It does not remove:

• CRDs (kept by helm.sh/resource-policy: keep)
• User-managed PolicyServers and policies

To remove CRDs after uninstall:

kubectl delete crd policyservers.policies.kubewarden.io
kubectl delete crd clusteradmissionpolicies.policies.kubewarden.io
kubectl delete crd admissionpolicies.policies.kubewarden.io
kubectl delete crd clusteradmissionpolicygroups.policies.kubewarden.io
kubectl delete crd admissionpolicygroups.policies.kubewarden.io

Software bill of materials & provenance

Every release publishes a software bill of materials (SBOM) and build provenance for each Kubewarden component. The SBOM follows the SPDX format. The provenance follows the SLSA provenance schema. Docker buildx generates both files during the build. It stores them in the container registry next to the container image. The release also uploads them as release assets.

Kubewarden publishes three images: controller, audit-scanner and policy-server. The release assets follow the pattern <component>-attestation-<arch>-<provenance|sbom>.<ext>.

Kubewarden signs the container images and the SBOM and provenance files in the release assets. The signatures use keyless signing with the GitHub Actions OIDC identity of the release workflow.

To verify the signature of an image, run:

cosign verify --certificate-oidc-issuer=https://token.actions.githubusercontent.com \
    --certificate-identity="https://github.com/kubewarden/adm-controller/.github/workflows/release.yml@refs/tags/<TAG TO VERIFY>" \
    ghcr.io/kubewarden/adm-controller/controller:<TAG TO VERIFY>

The command works with a tag and with a digest. The release signs the multi-architecture image and each single-architecture image.

To verify the provenance file from the release assets, run:

cosign verify-blob --certificate-oidc-issuer=https://token.actions.githubusercontent.com \
    --certificate-identity="https://github.com/kubewarden/adm-controller/.github/workflows/release.yml@refs/tags/<TAG TO VERIFY>" \
    --bundle controller-attestation-amd64-provenance.intoto.jsonl.bundle.sigstore \
    controller-attestation-amd64-provenance.intoto.jsonl

To verify the SBOM file, use the same command with the sbom.json files:

cosign verify-blob --certificate-oidc-issuer=https://token.actions.githubusercontent.com \
    --certificate-identity="https://github.com/kubewarden/adm-controller/.github/workflows/release.yml@refs/tags/<TAG TO VERIFY>" \
    --bundle controller-attestation-amd64-sbom.json.bundle.sigstore \
    controller-attestation-amd64-sbom.json

Note

The commands in this section use the controller image. The same commands work for the audit-scanner and policy-server images.

The SBOM and provenance files are also attached to the image in the registry. Docker buildx stores them in one attestation manifest per architecture, as JSON documents that follow the in-toto SPDX predicate format. The registry copy is not signed. The signed copies are the release assets. You can inspect the registry copy with crane or docker buildx imagetools inspect.

To list the attestation manifests of a tag, run:

crane manifest ghcr.io/kubewarden/adm-controller/controller:<TAG TO VERIFY> | jq '.manifests[] | select(.annotations["vnd.docker.reference.type"]=="attestation-manifest")'

Each attestation manifest has one layer per SBOM or provenance file. To list the layers, run:

crane manifest ghcr.io/kubewarden/adm-controller/controller@sha256:<ATTESTATION MANIFEST DIGEST>

To download one file, use the digest of its layer:

crane blob ghcr.io/kubewarden/adm-controller/controller@sha256:<LAYER DIGEST>

Security disclosure

See SECURITY.md on the kubewarden/community repo.

Changelog

See GitHub Releases content.