This is unreleased documentation for Admission Controller 1.37-dev.

Quick start

The Kubewarden Admission Controller stack comprises:

  • One or more ClusterAdmissionPolicy resources: this defines policies for Kubernetes clusters.

  • One or more PolicyServer resources: representing a deployment of a Admission Controller PolicyServer. The Admission Controller PolicyServer loads and evaluates your administrator’s policies.

  • One or more AdmissionPolicy resources: policies for a defined namespace.

  • A deployment of a admission-controller: this controller monitors the ClusterAdmissionPolicy resources and interacts with the Admission Controller PolicyServer components.

Admission Controller describes its Kubernetes Custom Resource Definitions (CRDs) here.

Admission Controller CRDs mentioned in this tutorial and in the rest of documentation have short names, which are easier to use. These are the short names for the CRDs:

Resource shortName

AdmissionPolicies

ap

ClusterAdmissionPolicies

cap

AdmissionPolicyGroups

apg

ClusterAdmissionPolicyGroups

capg

PolicyServers

ps

Installation

Authentication

You can retrieve Admission Controller policies from the GitHub container registry at https://ghcr.io. You need authentication to use the repository with the Admission Controller CLI, a GitHub personal access token (PAT). Their documentation guides you through creating one if you haven’t already done so. Then you authenticate with a command like:

echo $PAT | docker login ghcr.io --username <my-gh-username> --password-stdin

Deploy the Admission Controller stack using helm charts as follows:

helm repo add kubewarden https://charts.kubewarden.io
helm repo update kubewarden

Install the admission-controller Helm chart in the kubewarden namespace in your Kubernetes cluster. This will:

  • Register the ClusterAdmissionPolicy, AdmissionPolicy and PolicyServer Custom Resource Definitions. Also, the PolicyReport Custom Resource Definitions used by the audit scanner.

  • Deploy the Admission Controller and the audit scanner

    If you need to disable the audit scanner component check the audit scanner installation documentation page.

  • Create a PolicyServer resource named default. You can also install a set of recommended policies to secure your cluster by enforcing well known best practices.

helm install --wait -n kubewarden --create-namespace admission-controller kubewarden/admission-controller

The default configuration values are sufficient for most deployments. The documentation describes all the options.

Main components

The Admission Controller has three main components which you interact with:

PolicyServer

The admission-controller manages a Admission Controller PolicyServer. You can deploy multiple PolicyServers in the same Kubernetes cluster.

A PolicyServer validates incoming requests by executing Admission Controller policies against them.

This is the default PolicyServer configuration:

apiVersion: policies.kubewarden.io/v1
kind: PolicyServer
metadata:
  name: reserved-instance-for-tenant-a
spec:
  image: ghcr.io/kubewarden/adm-controller/policy-server:v1.37.0
  replicas: 2
  serviceAccountName: ~
  env:
    - name: KUBEWARDEN_LOG_LEVEL
      value: debug

Check the latest released PolicyServer version and change the tag to match.

Overview of the attributes of the PolicyServer resource:

Required Placeholder Description

Y

image

The name of the container image

Y

replicas

The number of desired instances

N

serviceAccountName

The name of the ServiceAccount to use for the PolicyServer deployment. If there is no provided value, the default ServiceAccount from the installation namespace, of admission-controller, gets used.

N

env

The list of environment variables

N

annotations

The list of annotations

Changing any of these attributes causes a PolicyServer deployment with the new configuration.

ClusterAdmissionPolicy

The ClusterAdmissionPolicy resource is the core of the Admission Controller stack. It defines how policies evaluate requests.

Enforcing policies is the most common operation which a Kubernetes administrator performs. You can declare as many policies as you want, each targets one or more Kubernetes resources (that is, pods, Custom Resource and others). You also specify the type of operations applied to targeted resources. The operations available are CREATE, UPDATE, DELETE and CONNECT.

Default ClusterAdmissionPolicy configuration:

apiVersion: policies.kubewarden.io/v1
kind: ClusterAdmissionPolicy
metadata:
  name: psp-capabilities
spec:
  policyServer: default
  module: registry://ghcr.io/kubewarden/policies/capabilities-psp:v1.0.10
  rules:
    - apiGroups: [""]
      apiVersions: ["v1"]
      resources: ["pods"]
      operations:
        - CREATE
        - UPDATE
  mutating: true
  settings:
    allowed_capabilities:
      - CHOWN
    required_drop_capabilities:
      - NET_ADMIN

Overview of the attributes of the ClusterAdmissionPolicy resource:

Required Placeholder Description

N

policy-server

Identifies an existing PolicyServer object. Only this PolicyServer instance serves the policy. The policy server named default serves a ClusterAdmissionPolicy without an explicit PolicyServer.

Y

module

The location of the Admission Controller policy. The following schemes are allowed:

N

- registry: Policy download from an OCI artifacts compliant container registry. Example: registry://<OCI registry/policy URL>

N

- http, https: Policy download from a regular HTTP(s) server. Example: https://<website/policy URL>

N

- file: Load the policy from a file in the computer file system. Example: file:///<policy WASM binary full path>

Y

resources

The Kubernetes resources evaluated by the policy

Y

operations

What operations for the previously given types should be forwarded to this admission policy by the API server for evaluation.

Y

mutating

Set this boolean value true for policies that can mutate incoming requests

N

settings

A free-form object that contains the policy configuration values

N

failurePolicy

The action to take if the request evaluated by a policy results in an error. The following options are allowed:

N

- Ignore: ignore an error calling the webhook and the API request continues.

N

- Fail: an error calling the webhook causes the admission to fail and API request rejection.

The controller registers the ClusterAdmissionPolicy resources * webhook scope. This means that registered webhooks forward all requests matching the given resources and operations, either namespaced or cluster-wide resources.

AdmissionPolicy

AdmissionPolicy is a namespace-wide resource. The policy processes only the requests that are targeting the Namespace with the AdmissionPolicy defined. Other than that, there are no functional differences between the AdmissionPolicy and ClusterAdmissionPolicy resources.

AdmissionPolicy requires Kubernetes 1.21.0 or greater. This is because Admission Controller uses the kubernetes.io/metadata.name label, introduced in Kubernetes 1.21.0

The complete documentation of these Custom Resources is here.

Example: Enforce your first policy

We will use the pod-privileged policy. We want to prevent the creation of privileged containers inside our Kubernetes cluster by enforcing this policy.

Let’s define a ClusterAdmissionPolicy to do that:

kubectl apply -f - <<EOF
apiVersion: policies.kubewarden.io/v1
kind: ClusterAdmissionPolicy
metadata:
  name: privileged-pods
spec:
  module: registry://ghcr.io/kubewarden/policies/pod-privileged:v0.2.2
  rules:
  - apiGroups: [""]
    apiVersions: ["v1"]
    resources: ["pods"]
    operations:
    - CREATE
    - UPDATE
  mutating: false
EOF

This produces the following output:

clusteradmissionpolicy.policies.kubewarden.io/privileged-pods created

After instantiating a ClusterAdmissionPolicy, the status becomes pending, and it forces a rollout of the targeted PolicyServer. In the example, it’s the PolicyServer named default. You can monitor the rollout by running the following command:

kubectl get clusteradmissionpolicy.policies.kubewarden.io/privileged-pods

You should see the following output:

NAME              POLICY SERVER   MUTATING   STATUS
privileged-pods   default         false      pending

Once the new policy is ready, the admission-controller registers a ValidatingWebhookConfiguration object to serve it.

The ClusterAdmissionPolicy status becomes active once the Deployment completes for every PolicyServer instance. Show ValidatingWebhookConfigurations with the following command:

kubectl get validatingwebhookconfigurations.admissionregistration.k8s.io -l kubewarden

You should see the following output:

NAME                          WEBHOOKS   AGE
clusterwide-privileged-pods   1          9s

Once the ClusterAdmissionPolicy is active and the ValidatingWebhookConfiguration registers, you can test the policy.

First, you can create a Pod with a Container not in privileged mode:

kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: unprivileged-pod
spec:
  containers:
    - name: nginx
      image: nginx:latest
EOF

This produces the following output:

pod/unprivileged-pod created

The Pod is successfully created.

Now, you can create a Pod with at least one Container privileged flag:

kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: privileged-pod
spec:
  containers:
    - name: nginx
      image: nginx:latest
      securityContext:
          privileged: true
EOF

The policy denies creation of the Pod and you should see the following message:

Error from server: error when creating "STDIN": admission webhook "clusterwide-privileged-pods.kubewarden.admission" denied the request: Privileged container is not allowed

Both examples didn’t define a namespace, which means the default namespace was the target. However, as you could see in the second example, the policy is still applied. As stated previously, this is due to the scope being cluster-wide and not targeting a specific namespace.

Uninstall

Uninstall the Helm chart as follows:

helm uninstall --namespace kubewarden admission-controller

Uninstalling the Helm chart removes:

  • The controller Deployment

  • Managed defaults such as the PolicyServer default and recommended policies

  • ConfigMaps, Secrets, Services, Deployments that make all PolicyServers be effective

It does not remove:

  • CRDs (kept by helm.sh/resource-policy: keep)

  • User-managed PolicyServers and policies

The user-managed custom resources are kept on purpose. Re-installing the chart deploys the controller, which reconciles them, and activates them back.

To remove all user-managed custom resources and the CRDs do:

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

Wrapping up

ClusterAdmissionPolicy is the core resource that a cluster operator has to manage. The admission-controller module automatically takes care of the configuration for the rest of the resources needed to run the policies.

What’s next?

Now, you are ready to learn more about the Admission Controller! Have a look at the policies on artifacthub.io, on GitHub, or reuse existing Rego policies as shown in the following chapters.

Small selection of available policies on ArtifactHub