From aa700edeb0124b50311abfe516f0e80e78270a61 Mon Sep 17 00:00:00 2001 From: Rohanraj123 Date: Sun, 31 Aug 2025 16:52:05 +0530 Subject: [PATCH 1/2] Add data related to messageExpression and auditAnnotations in ValidatingPolicy docs Signed-off-by: Rohanraj123 --- .../policy-types/validating-policy/_index.md | 128 +++++++++++++++++- 1 file changed, 127 insertions(+), 1 deletion(-) diff --git a/content/en/docs/policy-types/validating-policy/_index.md b/content/en/docs/policy-types/validating-policy/_index.md index 66a5f7c82..16561d597 100644 --- a/content/en/docs/policy-types/validating-policy/_index.md +++ b/content/en/docs/policy-types/validating-policy/_index.md @@ -169,7 +169,7 @@ spec: ) ``` -To write a policy for JSON payloads: +***To write a policy for JSON payloads:*** 1. Set `spec.evaluation.mode` to `JSON`. 2. Next, define a `spec.matchConditions` with CEL expressions to tell the engine which payloads should be matched. 3. Finally, define your validation rules in `spec.validations`. @@ -177,3 +177,129 @@ To write a policy for JSON payloads: To evaluate JSON policies, use the [Kyverno CLI](../../kyverno-cli/). A Kyverno Engine SDK is planned for a subsequent release. + +## Reporting Details in ValidatingPolicy + +When a ValidatingPolicy is evaluated, the results are recorded in PolicyReports. PolicyReports are standard Kubernetes custom resources that summarize the outcomes of policy evaluations, including whether resources passed or failed validation. + +Kyverno provides additional fields in ValidatingPolicy rules to make PolicyReports more informative and contextual. Two important features are: + +### Using auditAnnotations to add custom data + +The auditAnnotations field allows attaching custom key-value data to the results stored in PolicyReports. These values can be static strings or dynamic expressions using [CEL (Common Expression Language)](/docs/policy-types/cel-libraries/) +. + +This is useful for adding metadata such as severity, team ownership, or any resource-specific values that help consumers of the PolicyReport better understand and act on violations. + +***Example Policy:*** + +```yaml + +``` + + +***Resulting PolicyReport entry:*** + +```bash +# Example: Add PolicyReport output here +``` + +### Using messageExpression to generate dynamic messages + +While the message field provides a static failure message, messageExpression allows you to dynamically build messages using CEL expressions. This produces more contextual and precise failure descriptions. + +If both message and messageExpression are defined, the messageExpression takes precedence. + +The expression must evaluate to a string. + +If the expression fails or produces an invalid string (empty, whitespace-only, or multi-line), Kyverno falls back to the static message. + +***Example Policy:*** + +```yaml +apiVersion: policies.kyverno.io/v1alpha1 +kind: ValidatingPolicy +metadata: + name: check-deployment-labels + annotations: + policies.kyverno.io/title: Check Deployment Labels + policies.kyverno.io/category: Other + policies.kyverno.io/severity: medium +spec: + validationActions: + - Audit + matchConstraints: + resourceRules: + - apiGroups: [apps] + apiVersions: [v1] + operations: [CREATE, UPDATE] + resources: [deployments] + variables: + - name: environment + expression: >- + has(object.metadata.labels) && 'env' in object.metadata.labels && object.metadata.labels['env'] == 'prod' + validations: + - expression: >- + variables.environment == true + messageExpression: >- + 'Deployment labels must be env=prod' + (has(object.metadata.labels) && 'env' in object.metadata.labels ? ' but found env=' + string(object.metadata.labels['env']) : ' but no env label is present') +``` +***Example Resource Deployment:*** + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: bad-deployment + labels: + app: nginx + env: testing +spec: + replicas: 1 + selector: + matchLabels: + app: nginx + template: + metadata: + labels: + app: nginx + spec: + containers: + - name: nginx + image: nginx:latest +``` + +***Resulting PolicyReport entry:*** + +```yaml +apiVersion: v1 +items: +- apiVersion: wgpolicyk8s.io/v1alpha2 + kind: PolicyReport + metadata: + generation: 1 + labels: + app.kubernetes.io/managed-by: kyverno + ownerReferences: + - apiVersion: apps/v1 + kind: Deployment + name: no-env + results: + - category: Other + message: Deployment labels must be env=prod but no env label is present + policy: check-deployment-labels + result: fail + scored: true + severity: medium + source: KyvernoValidatingPolicy + scope: + apiVersion: apps/v1 + kind: Deployment + name: no-env + summary: + error: 0 + fail: 1 + pass: 0 + skip: 0 + warn: 0 +``` \ No newline at end of file From 1ad5a298cbffd27599ce73f8ce63dec9ca5a9cf9 Mon Sep 17 00:00:00 2001 From: Rohanraj123 Date: Sun, 31 Aug 2025 17:15:13 +0530 Subject: [PATCH 2/2] add auditAnnotations section Signed-off-by: Rohanraj123 --- .../policy-types/validating-policy/_index.md | 47 ++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/content/en/docs/policy-types/validating-policy/_index.md b/content/en/docs/policy-types/validating-policy/_index.md index 16561d597..d642268c9 100644 --- a/content/en/docs/policy-types/validating-policy/_index.md +++ b/content/en/docs/policy-types/validating-policy/_index.md @@ -194,9 +194,54 @@ This is useful for adding metadata such as severity, team ownership, or any reso ***Example Policy:*** ```yaml - +apiVersion: policies.kyverno.io/v1alpha1 +kind: ValidatingPolicy +metadata: + name: check-deployment-labels +spec: + auditAnnotations: + - key: team + valueExpression: "platform" + matchConstraints: + resourceRules: + - apiGroups: [apps] + apiVersions: [v1] + operations: [CREATE, UPDATE] + resources: [deployments] + variables: + - name: environment + expression: >- + has(object.metadata.labels) && 'env' in object.metadata.labels && object.metadata.labels['env'] == 'prod' + validations: + - expression: >- + variables.environment == true + message: >- + Deployment labels must be env=prod ``` +***Example Deployment:*** +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-deployment + labels: + app: nginx + env: prod +spec: + replicas: 1 + selector: + matchLabels: + app: nginx + template: + metadata: + labels: + app: nginx + spec: + containers: + - name: nginx + image: nginx:latest +``` ***Resulting PolicyReport entry:***