SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) architecture

The team designed SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) to use core features of Kubernetes, without reinventing the wheel. The project utilizes a combination of:

SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) operates seamlessly within the Kubernetes ecosystem. At its core, the SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) controller is a Kubernetes controller, monitoring SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) Custom Resource Definitions (CRDs) and configuring Kubernetes resources to execute them. This integration ensures that SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) uses the built-in Kubernetes mechanisms, such as controllers and CRDs, to watch, manage, and apply security policies efficiently.

SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) employs CRDs to define and manage SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) resources, which specify the rules for admission request validations. This design enables users to extend Kubernetes' capabilities with custom admission controls, ensuring that security and compliance policy enforcement is consistent across the cluster.

When setup by the SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) controller, the policy-server Service receives admission requests directly from the Kubernetes control plane, using ValidationWebhooks and MutatingWebhooks. This direct interaction streamlines the admission control process, reducing latency and increasing efficiency in policy enforcement.

WebAssembly offers a sand-boxed execution environment, ensuring policies run in isolation, thus enhancing the security and stability of the policy enforcement mechanism. This isolation prevents policies from interfering with each other or with the host system, mitigating the risk of malicious code execution. WebAssembly is portable and efficient, enabling policies to run across different environments without modification. This cross-platform compatibility ensures that SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) policies are versatile, so you can distribute and run them on diverse Kubernetes clusters

Policies in SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) are OCI (Open Container Initiative) artifacts. This standardization makes the distribution and versioning of policies easier, Policies contain both the WebAssembly modules for enforcement logic, and metadata necessary for the PolicyServer’s operation. Using OCI artifacts promotes interoperability and ease of management within cloud ecosystems.

SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) associates policies with their own 'validation' or 'mutating' webhook, allowing for fine-grained application of admission controls. This flexibility enables administrators to tailor the enforcement of policies according to specific needs, enhancing the security and compliance posture of the Kubernetes cluster.

On a new cluster, the SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) components defined are:

When the kubewarden-controller notices the default PolicyServer resource, it creates a policy-server deployment of the PolicyServer component.

SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) works as a Kubernetes Admission Webhook. Kubernetes specifies using Transport Layer Security (TLS) to secure all Webhook endpoints. The kubewarden-controller sets up this secure communication by:

These objects are all stored as Secret resources in Kubernetes.

Finally, kubewarden-controller creates the policy-server Deployment and a Kubernetes ClusterIP Service to expose it inside the cluster network.

The kubewarden-controller notices the new ClusterAdmissionPolicy resource and so finds the bound policy-server and reconciles it.

When creating, modifying or deleting a ClusterAdmissionPolicy or AdmissionPolicy, a reconciliation loop activates in kubewarden-controller, for the policy-server owning the policy. This reconciliation loop creates a ConfigMap with all the policies bound to the policy-server. Then the Deployment rollout of the policy-server starts. This results in starting the new policy-server instance with the updated configuration.

At start time, the policy-server reads its configuration from the ConfigMap and downloads all the SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) policies specified. You can download SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) policies from remote HTTP servers and container registries.

You use policy settings parameters to tune a policies' behavior. After startup and policy download the policy-server checks the policy settings provided by the user are valid.

The policy-server validates policy settings by invoking the validate_setting function exposed by each policy. There is further documentation in the specification reference section of the documentation.

If any policies received wrong configuration parameters, from the users policy specification, then any admission requests evaluated by that policy return an error.

When SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) has configured all policies, the policy-server spawns a pool of worker threads to evaluate incoming requests using the SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) policies specified by the user.

Finally, the policy-server starts a HTTPS server, listening to incoming validation requests. SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) uses the TLS key and certificate created by the SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) controller to secure the web server.

The web server exposes each policy by a dedicated path following the naming convention: /validate/<policy ID>.

All policy-server instances have a Readiness Probe, that kubewarden-controller uses to check when the policy-server Deployment is ready to evaluate an AdmissionReview.

Once SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) marks the policy-server deployment as 'uniquely reachable' or Ready, the kubewarden-controller makes the Kubernetes API server aware of the new policy. This is by creating either a MutatingWebhookConfiguration or a ValidatingWebhookConfiguration object. In this context, 'uniquely reachable', means that all the PolicyServer instances in the cluster have the latest policy configuration installed. The distinction, is a fine point, but is necessary, due to how roll-out of PolicyServers works. It’s possible to have the same policy, on different PolicyServers with different configurations.

Each policy has a dedicated MutatingWebhookConfiguration or ValidatingWebhookConfiguration pointing to the Webhook endpoint served by policy-server. The endpoint is reachable at the /validate/<policy ID> URL.

Now that all the necessary plumbing is complete, Kubernetes starts sending Admission Review requests to the right policy-server endpoints.

A policy-server receives the Admission Request object and, based on the endpoint that received the request, uses the correct policy to evaluate it.

SUSE® Rancher Prime: Admission Policy Manager (Kubewarden) evaluates each policy inside its own dedicated WebAssembly sand-box. The communication between a policy-server instance (the "host") and the WebAssembly policy (the "guest") uses the waPC communication protocol. The protocol description is part of the writing policies documentation. Policies can also use the interfaces provided by the Web Assembly System Interface (WASI).