Quick start

The Kubewarden stack comprises:

• One or more

  ClusterAdmissionPolicyA ClusterAdmissionPolicy defines how policies evaluate requests. Glossary
  resources: this defines policies for Kubernetes clusters.

• One or more

  PolicyServerA PolicyServer validates incoming requests by executing Kubewarden policies against requests. Glossary
  resources: representing a deployment of a Kubewarden PolicyServer. The Kubewarden PolicyServer loads and evaluates your administrator's policies.

• One or more

  AdmissionPolicyA namespace-wide resource. The policy processes only requests targeting the namespace where the AdmissionPolicy is defined. Glossary
  resources: policies for a defined namespace.

• A deployment of a kubewarden-controller: this controller monitors the

  ClusterAdmissionPolicyA ClusterAdmissionPolicy defines how policies evaluate requests. Glossary
  resources and interacts with the Kubewarden
  PolicyServerA PolicyServer validates incoming requests by executing Kubewarden policies against requests. Glossary
  components.

tip

Kubewarden describes its Kubernetes Custom Resource Definitions (CRDs) here.

Kubewarden CRDs mentioned in this tutorial and in the whole documentation have short names, which are easier to use. These are the short names for all the CRDs:

Resource	shortName
AdmissionPolicies	ap
ClusterAdmissionPolicies	cap
AdmissionPolicyGroups	apg
ClusterAdmissionPolicyGroups	capg
PolicyServers	ps

Installation

Authentication

You can retrieve Kubewarden policies from the GitHub container registry at https://ghcr.io. You need authentication to use the repository with the Kubewarden 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 Kubewarden stack using helm charts as follows:

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

helm repo update kubewarden

Install the following Helm charts inside the kubewarden namespace in your Kubernetes cluster:

• kubewarden-crds, which registers the

  ClusterAdmissionPolicyA ClusterAdmissionPolicy defines how policies evaluate requests. Glossary
  ,
  AdmissionPolicyA namespace-wide resource. The policy processes only requests targeting the namespace where the AdmissionPolicy is defined. Glossary
  and
  PolicyServerA PolicyServer validates incoming requests by executing Kubewarden policies against requests. Glossary
  Custom Resource Definitions. Also, the
  PolicyReportA PolicyReport and a ClusterPolicyReport store results of policy scans. Which one is used depends on the scope of the resource. Glossary
  Custom Resource Definitions used by the audit scanner.

• kubewarden-controller, which installs the Kubewarden controller and the audit scanner

  note

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

• kubewarden-defaults, which creates a PolicyServer resource named default. It 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 kubewarden-crds kubewarden/kubewarden-crds

helm install --wait -n kubewarden kubewarden-controller kubewarden/kubewarden-controller

helm install --wait -n kubewarden kubewarden-defaults kubewarden/kubewarden-defaults

caution

Since v0.4.0, a PolicyServer resource named default isn't created using the kubewarden-controller chart. Now a Helm chart called kubewarden-defaults, installs the default policy server.

This means that if not using the latest version of the kubewarden-controller while upgrading or deleting, your default policy server isn't upgraded or deleted. So, you might run into issues if you try to install the kubewarden-defaults with conflicting information, for example, the same policy server name. To install future upgrades of the kubewarden-defaults Helm chart remove the existing PolicyServer resource created by the kubewarden-controller before installing the new chart. Now you can update your policy server using Helm upgrades without resource conflicts. When you remove the PolicyServer, you remove all the policies bound to it as well.

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

Main components

Kubewarden has three main components which you will interact with:

• The
  PolicyServerA PolicyServer validates incoming requests by executing Kubewarden policies against requests. Glossary
• The
  ClusterAdmissionPolicyA ClusterAdmissionPolicy defines how policies evaluate requests. Glossary
• The
  AdmissionPolicyA namespace-wide resource. The policy processes only requests targeting the namespace where the AdmissionPolicy is defined. Glossary

PolicyServer

The kubewarden-controller manages a Kubewarden PolicyServer. You can deploy multiple

PolicyServerA PolicyServer validates incoming requests by executing Kubewarden policies against requests. Glossary

s in the same Kubernetes cluster.

A PolicyServer validates incoming requests by executing Kubewarden 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/policy-server:v1.3.0
  replicas: 2
  serviceAccountName: ~
  env:
    - name: KUBEWARDEN_LOG_LEVEL
      value: debug

note

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 kubewarden-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

ClusterAdmissionPolicyA ClusterAdmissionPolicy defines how policies evaluate requests. Glossary

resource is the core of the Kubewarden 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

ClusterAdmissionPolicyA ClusterAdmissionPolicy defines how policies evaluate requests. Glossary

configuration:

apiVersion: policies.kubewarden.io/v1
kind: ClusterAdmissionPolicy
metadata:
  name: psp-capabilities
spec:
  policyServer: reserved-instance-for-tenant-a
  module: registry://ghcr.io/kubewarden/policies/psp-capabilities:v0.1.9
  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

ClusterAdmissionPolicyA ClusterAdmissionPolicy defines how policies evaluate requests. Glossary

resource:

Required	Placeholder	Description
N	policy-server	Identifies an existing PolicyServer object. Only by this PolicyServer instance serves the policy. The policy server named default serves a ClusterAdmissionPolicyA ClusterAdmissionPolicy defines how policies evaluate requests. Glossary without an explicit PolicyServer.
Y	module	The location of the Kubewarden policy. Kubewarden permits the following schemes:
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 to forward to this admission policy by the API server for evaluation.
Y	mutating	Set this boolean value to 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. Permitted options:
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.

note

The controller registers the

ClusterAdmissionPolicyA ClusterAdmissionPolicy defines how policies evaluate requests. Glossary

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

AdmissionPolicy

AdmissionPolicyA namespace-wide resource. The policy processes only requests targeting the namespace where the AdmissionPolicy is defined. Glossary

is a namespace-wide resource. The policy only processes requests targeting the Namespace with the

AdmissionPolicyA namespace-wide resource. The policy processes only requests targeting the namespace where the AdmissionPolicy is defined. Glossary

defined. Other than that, there are no functional differences between the

AdmissionPolicyA namespace-wide resource. The policy processes only requests targeting the namespace where the AdmissionPolicy is defined. Glossary

and

ClusterAdmissionPolicyA ClusterAdmissionPolicy defines how policies evaluate requests. Glossary

resources.

info

AdmissionPolicyA namespace-wide resource. The policy processes only requests targeting the namespace where the AdmissionPolicy is defined. Glossary

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

The complete documentation of these Custom Resources is here or on docs.crds.dev.

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

ClusterAdmissionPolicyA ClusterAdmissionPolicy defines how policies evaluate requests. Glossary

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

ClusterAdmissionPolicyA ClusterAdmissionPolicy defines how policies evaluate requests. Glossary

, 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 kubewarden-controller registers a ValidatingWebhookConfiguration object to serve it.

The

ClusterAdmissionPolicyA ClusterAdmissionPolicy defines how policies evaluate requests. Glossary

status becomes active once the Deployment completes for every PolicyServer instance. Show

ValidatingWebhookConfigurationA Kubernetes resource created by the Kubewarden controller to let Kubernetes know where to send a AdmissionReview. Glossary

s 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

ClusterAdmissionPolicyA ClusterAdmissionPolicy defines how policies evaluate requests. Glossary

is active and the

ValidatingWebhookConfigurationA Kubernetes resource created by the Kubewarden controller to let Kubernetes know where to send a AdmissionReview. Glossary

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

note

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

You can remove the resources created by uninstalling the helm charts as follows:

helm uninstall --namespace kubewarden kubewarden-defaults

helm uninstall --namespace kubewarden kubewarden-controller

helm uninstall --namespace kubewarden kubewarden-crds

After removal of the helm charts remove the Kubernetes namespace that used to deploy the Kubewarden stack:

kubectl delete namespace kubewarden

caution

Kubewarden contains a helm pre-delete hook that removes all PolicyServers and kubewarden-controllers. Then the kubewarden-controller deletes all resources, so it's important that kubewarden-controller is running when helm uninstall executes.

Kubewarden deletes

ValidatingWebhookConfigurationA Kubernetes resource created by the Kubewarden controller to let Kubernetes know where to send a AdmissionReview. Glossary

s and

MutatingWebhookConfigurationA Kubernetes resource created by the Kubewarden controller to let Kubernetes know where to send an AdmissionReview. Glossary

s it has created. Check this with:

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

kubectl get mutatingwebhookconfigurations.admissionregistration.k8s.io -l "kubewarden"

If these resources aren't automatically removed, remove them manually using the following command:

kubectl delete -l "kubewarden" validatingwebhookconfigurations.admissionregistration.k8s.io

kubectl delete -l "kubewarden" mutatingwebhookconfigurations.admissionregistration.k8s.io

Wrapping up

ClusterAdmissionPolicyA ClusterAdmissionPolicy defines how policies evaluate requests. Glossary

is the core resource that a cluster operator has to manage. The kubewarden-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 deploy Kubewarden! Have a look at the policies on artifacthub.io, on GitHub, or reuse existing Rego policies as shown in the following chapters.

Full list of available policies on ArtifactHub