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.