Policy metadata
The Kubewarden metadata file, metadata.yaml
,
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.
The policy metadata.yaml
file has defaults for the policy,
as well as metadata such as author and description,
set by the policy author.
The 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 kwctl scaffold
.
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 metadata.yaml
:
rules:
- apiGroups: [""]
apiVersions: ["v1"]
resources: ["pods"]
operations: ["CREATE"]
mutating: false
contextAwareResources: []
executionMode: kubewarden-wapc
policyType: kubernetes
backgroundAudit: true
annotations:
# artifacthub specific:
io.artifacthub.displayName: Policy Name
io.artifacthub.resources: Pod
io.artifacthub.keywords: pod, cool policy, kubewarden
io.kubewarden.policy.ociUrl: ghcr.io/myorg/my-policy
# kubewarden specific:
io.kubewarden.policy.title: My policy
io.kubewarden.policy.description: Short description
io.kubewarden.policy.author: myself
io.kubewarden.policy.url: https://github.com/yourorg/my-policy
io.kubewarden.policy.source: https://github.com/yourorg/my-policy
io.kubewarden.policy.license: Apache-2.0
# 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.severity: medium
io.kubewarden.policy.category: Resource validation
Enabling background audit checks​
The metadata file includes a flag, backgroundAudit
,
that enables the background audit checks for a specific policy.
By default, this flag is set to true
.
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 false
.
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,
using the contextAwareResources
field,
users can define which Kubernetes resources the policy can access.
For example, if the policy needs access to the Namespace
resource.
The policy author can define the contextAwareResources
as:
[...]
contextAwareResources:
- apiVersion: v1 kind: Namespace
[...]
Specifying policies as mutating or non-mutating​
The metadata file has a flag, mutating
,
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 kubernetes
or raw
.
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 rules
field,
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.