Kubewarden Admission Controller

Kubewarden is a Kubernetes Dynamic Admission Controller that uses WebAssembly (Wasm) for policy execution. The monorepo consists of four primary components:

• adm-controller: A Kubernetes controller that manages the registration of admission policies and reconciles them with cluster webhooks.
• policy-server: The runtime component responsible for evaluating Wasm-based admission policies.
• audit-scanner: A component that scans existing cluster resources against currently registered policies.
• kwctl: A CLI tool used for managing and testing Kubewarden policies.

The policy-fetcher crate is a component used by Kubewarden to retrieve policies from external sources. It specifically supports pulling policies from:

• OCI registries
• HTTP servers

The kwctl command-line tool is used to manage Kubewarden policies. It provides a wide range of subcommands for policy lifecycle management, testing, and scaffolding.

Core Subcommands:

• pull / push: Manage policies in OCI registries.
• run / bench: Execute and benchmark policies locally.
• scaffold: Generate Kubernetes resources or configuration files.
• verify: Verify policy integrity using Sigstore.
• inspect / digest: Examine policy details and OCI manifests.
• load / save: Bulk import/export policies via tarball.
• annotate: Add metadata to WebAssembly modules.
• rm: Remove policies from the local store.
• policies: List downloaded policies.
• info: Display system information.
• completions: Generate shell completion scripts.
• docs: Generate documentation for kwctl itself.

The Audit scanner inspects resources defined in a Kubernetes cluster to identify those violating Kubewarden policies.

Scan results are persisted in the cluster as Custom Resources:

• PolicyReport: Stores results for specific namespaced resources.
• ClusterPolicyReport: Stores results for cluster-wide resources.

Each resource being scanned has its own dedicated report object.

PolicyMode

Determines how the policy affects requests:

• protect: The policy actively enforces rules (default).
• monitor: The policy observes requests without blocking them.

PolicyStatus

Describes the lifecycle state of a policy:

• unscheduled: Transient state; no policy server is assigned.
• scheduled: Transient state; a policy server has been assigned.
• pending: The policy server exists and is reconciling resources.
• active: The Kubernetes API server is actively forwarding admission review objects to the policy.

The audit scanner iterates through namespaces, resource types, and individual resources. You can tune performance using parallelism and pagination flags.

Key Tuning Parameters:

• --page-size: Controls the chunk size of resources fetched from the Kubernetes API. Larger values increase memory usage and reduce API calls.
• --parallel-namespaces: Number of Namespaces to evaluate simultaneously.
• --parallel-resources: Number of resources to evaluate simultaneously.
• --parallel-policies: Number of policies to evaluate for a single resource simultaneously.

Note on Throughput: The maximum number of outgoing evaluation requests is calculated as: --parallel-namespaces × --parallel-resources × --parallel-policies.

The updatecli configuration is modular and uses shared values files to maintain a single source of truth for artifact definitions across different pipelines:

• values/scms.yaml: Contains GitHub authentication and repository settings.
• values/artifacts.yaml: Defines shared OCI artifacts and Helm charts used by all pipelines.
• values/update-deps-pr-values.yaml: Configuration specific to Pull Requests for weekly dependency updates.
• values/release-pr-values.yaml: Configuration specific to Pull Requests for release automation.

The scanner identifies cluster-wide resources by looking for ClusterAdmissionPolicy objects.

Process Flow:

1. Policy Mapping: It creates a map where the key is the Kubernetes resource type (Group, Version, Kind) and the value is a list of policies targeting that type.
2. Resource Fetching: It fetches all resources of the targeted types using pagination to minimize memory usage and API server load.
3. Parallel Evaluation: For each resource, the scanner invokes auditClusterResource. This process is parallelized based on the --parallel-resources flag.
4. Policy Execution: For each policy targeting the resource:
   • It checks if the policy's label selectors match the resource.
   • It creates a fake CREATE admission request and sends it to the Policy Server.
5. Reporting: A ClusterPolicyReport is generated for the resource.