The Kubewarden metadata file,
is a configuration file containing important information and settings
related to the policies used within Kubewarden.
This documentation is overview of the purpose and usage of the metadata file.
metadata.yaml file has defaults for the policy,
as well as metadata such as author and description,
set by the policy author.
kwctl annotate command uses the file to annotate the
.wasm file containing the policy.
Therefore, all the relevant information required to run the policy is available.
More information about how to annotate the policy is in the
Distributing Policies guide.
When policy users want to use a policy, they generate a YAML manifest using
This command reads the policy metadata embedded in the shipped Wasm module,
performs checks, and returns a YAML manifest that the author can use as-is or modify.
As a policy author, you can adapt the
metadata.yaml file provided during the
scaffolding of your policy.
See the following example of a
- apiGroups: [""]
# artifacthub specific:
io.artifacthub.displayName: Policy Name
io.artifacthub.keywords: pod, cool policy, kubewarden
# kubewarden specific:
io.kubewarden.policy.title: My policy
io.kubewarden.policy.description: Short description
# The next two annotations are used in the policy report generated by the
# Audit scanner. Severity indicates policy check result criticality and
# Category indicates policy category. See more here at docs.kubewarden.io
io.kubewarden.policy.category: Resource validation
Enabling background audit checks
The metadata file includes a flag,
that enables the background audit checks for a specific policy.
By default, this flag is set to
There are policies that, due to the way they work or to the type of events they're concerned with,
should have this field set to
You can find more information in the
audit scanner documentation,
under the limitations section.
Defining Kubernetes resources that policies can access
Within the metadata file,
users can define which Kubernetes resources the policy can access.
For example, if the policy needs access to the
The policy author can define the
- apiVersion: v1 kind: Namespace
Specifying policies as mutating or non-mutating
The metadata file has a flag,
that lets users configure a policy as either mutating or non-mutating.
A mutating policy modifies the incoming requests or the resources being managed.
A non-mutating policy observes and enforces restrictions without making any changes.
This distinction is crucial in determining how policies interact with the Kubernetes resources and their impact on the cluster.
Specify policy type as Kubernetes or Raw
The metadata file has a flag,
policyType, that lets users to mark a policy as either
A Kubernetes policy is a policy that validates Kubernetes resources.
A Raw policy is a policy that validates arbitrary JSON documents.
By default, if not specified by the user, this field is set to
kubernetes when annotating a policy.
Refer to the Raw Policies section for more information.
Defining resource type targets
The metadata file provides users with the ability to define the rules within the
which determines the resource types to which the policy applies.
This feature empowers users to exercise precise control over policy enforcement,
guaranteeing that policies are only applied to the intended resource types.
With this fine-grained control, users can guarantee that policies are targeted accurately,
aligning with their specific requirements and avoiding any unintended application of policies to unrelated resource types.