Skip to main content
Version: Next 🚧

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:
  # kubewarden specific:
  io.kubewarden.policy.title: My policy
  io.kubewarden.policy.version: 0.1.0 # should match the OCI tag
  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
  # The next annotation is a list of self-reported host capability calls that
  # the policy can make. Used when annotating the policy.
  hostCapabilities:
    - kubernetes/get_resource
    - oci/v2/*
  # artifacthub specific: (optional, to release in Artifact Hub)
  io.kubewarden.policy.ociUrl: ghcr.io/myorg/my-policy
  io.artifacthub.displayName: Policy Name
  io.artifacthub.resources: Pod
  io.artifacthub.keywords: pod, cool policy, kubewarden

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
[...]

Self-reporting which host capabilities calls the policies use​

Within the metadata file, using the hostCapabilities field, users can define which host capability calls the policy intends to use. For example:

[...]
hostCapabilities:
  - kubernetes/list_resources_by_namespace
  - kubernetes/list_resources_all
  - kubernetes/get_resource
[...]

This metadata is used when annotating the policy Wasm module with kwctl annotate. In addition, kwctl annotate performs an heuristic scan of the Wasm binary's data for known host-capability strings, and compares what it detects against the hostCapabilities list declared in metadata.yml. Any mismatch is reported as warnings on stderr.

See host capability calls documentation page for more info.

warning

Both the self-reporting and the heuristic scan cannot be used as a security boundary. A policy publisher could embed any arbitrary hostCapabilities list in the metadata regardless of what the binary actually does at runtime.

Use this information as one signal alongside other trust indicators (image signing, source code review, policy provenance, etc) not as an authoritative proof of what capabilities a policy exercises.

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.