Skip to content

feat: add YAML template mode to GeneratingPolicy generation entries - #115

Merged
realshuting merged 1 commit into
kyverno:mainfrom
realshuting:feat/16331-gpol-template
Jul 22, 2026
Merged

realshuting merged 1 commit into
kyverno:mainfrom
realshuting:feat/16331-gpol-template

Conversation

@realshuting

Copy link
Copy Markdown
Member

Explanation

This PR adds a new addition to the GeneratingPolicy / NamespacedGeneratingPolicy API: a YAML template declaration mode for spec.generate[] entries. Today generated resources can only be declared through a CEL expression, which forces manifest-shaped resources into deeply nested, dyn()-heavy CEL object construction that is hard to author and debug. With this change, users can declare generated resources as plain YAML (single or multi-document), optionally interpolated with CEL (( ... )) placeholders — significantly easing migration from ClusterPolicy generate rules.

Related issue

Part of kyverno/kyverno#16331 (design and semantics discussed there).

Proposed Changes

API only — the runtime implementation lands in kyverno/kyverno (companion PR, linked from the issue).

  • Generation gains an optional Template *GenerationTemplate field, mutually exclusive with Expression, enforced at the API server by a CRD XValidation rule:
    (has(self.expression) && !has(self.template)) || (!has(self.expression) && has(self.template))
  • New GenerationTemplate type:
    • value (required, MinLength=1): YAML string, single or multi-document. The namespace of each generated resource is taken from its rendered metadata.namespace.
    • interpolate (optional, enum none|cel, default none): none treats the value as plain YAML; cel evaluates (( ... )) placeholders as CEL expressions before the YAML is parsed.
  • New InterpolationMode enum with InterpolationModeNone / InterpolationModeCEL constants.
  • v1beta1 type aliases for GenerationTemplate / InterpolationMode.
  • Regenerated deepcopy, register, CRDs (gpol + ngpol), helm chart CRDs, and API docs.

Example

apiVersion: policies.kyverno.io/v1beta1
kind: GeneratingPolicy
metadata:
  name: generate-scrape-policy
spec:
  matchConstraints:
    resourceRules:
    - apiGroups: [""]
      apiVersions: ["v1"]
      resources: ["namespaces"]
      operations: ["CREATE", "UPDATE"]
  variables:
  - name: nsName
    expression: object.metadata.name
  generate:
  - template:
      interpolate: cel
      value: |
        apiVersion: v1
        kind: ConfigMap
        metadata:
          name: (( variables.nsName ))-config
          namespace: (( variables.nsName ))
        data:
          key: value

Existing policies using expression are unaffected (the exclusivity rule only rejects entries that set both or neither).

Checklist

  • I have read the contributing guidelines.
  • I have added tests that prove my fix is effective or that my feature works (existing API test suites pass; behavioral tests live in the companion kyverno PR).
  • I have added or changed the documentation — docs PR will accompany the kyverno implementation PR.

Adds an optional 'template' declaration to spec.generate[] entries as an
alternative to 'expression', allowing generated resources to be authored
as plain YAML (single or multi-document) with optional CEL interpolation
via (( ... )) placeholders.

- Generation gains Template *GenerationTemplate, mutually exclusive with
  Expression (enforced by a CRD XValidation rule)
- GenerationTemplate.Value holds the YAML document(s)
- GenerationTemplate.Interpolate selects placeholder evaluation:
  none (default) or cel
- v1beta1 aliases and regenerated deepcopy/CRDs/docs

Part of kyverno/kyverno#16331

Signed-off-by: realshuting <shuting@nirmata.com>

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR extends the GeneratingPolicy / NamespacedGeneratingPolicy API to support declaring generated resources via a YAML “template” (optionally CEL-interpolated), as an alternative to the existing CEL-only expression form. It introduces the new GenerationTemplate and InterpolationMode API types and propagates the change through generated CRDs, Helm chart CRDs, deepcopy code, and API docs.

Changes:

  • Add spec.generate[].template (YAML value + interpolation mode) and enforce mutual exclusivity with spec.generate[].expression via CRD XValidation.
  • Introduce GenerationTemplate and InterpolationMode (with none|cel and default none) plus v1beta1 aliases/constants.
  • Regenerate deepcopy, CRDs (standalone + bundled), Helm chart CRDs, and HTML API docs.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
docs/user/crd/kyverno_cel_policies.v1alpha1.html Adds generated HTML docs for GenerationTemplate and InterpolationMode.
docs/user/crd/index.html Adds generated index docs entries for the new template mode and enum alias.
config/crds/policies.kyverno.io_namespacedgeneratingpolicies.yaml Adds template schema and XValidation exclusivity rule for namespaced CRD.
config/crds/policies.kyverno.io_generatingpolicies.yaml Adds template schema and XValidation exclusivity rule for cluster CRD.
config/crds.yaml Updates the aggregated CRDs bundle with the new schema + validations.
charts/kyverno-api/templates/crds/policies.kyverno.io_namespacedgeneratingpolicies.yaml Updates Helm-packaged namespaced CRD with new schema + validations.
charts/kyverno-api/templates/crds/policies.kyverno.io_generatingpolicies.yaml Updates Helm-packaged cluster CRD with new schema + validations.
api/policies.kyverno.io/v1beta1/generating_policy.go Adds v1beta1 type aliases and exports InterpolationMode* constants.
api/policies.kyverno.io/v1alpha1/zz_generated.deepcopy.go Fixes deep-copying of []Generation to avoid shallow-copying the new pointer field.
api/policies.kyverno.io/v1alpha1/generating_policy.go Adds Template, GenerationTemplate, InterpolationMode, and the XValidation rule.
Files not reviewed (1)
  • api/policies.kyverno.io/v1alpha1/zz_generated.deepcopy.go: Generated file

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@realshuting
realshuting marked this pull request as ready for review July 22, 2026 08:06
@realshuting
realshuting enabled auto-merge (squash) July 22, 2026 08:06
@realshuting
realshuting merged commit 79092da into kyverno:main Jul 22, 2026
10 checks passed
realshuting added a commit to realshuting/kyverno that referenced this pull request Jul 22, 2026
Picks up kyverno/api#115 which adds the Generation.Template API.
Regenerated CRDs are unchanged (already in sync).

Signed-off-by: realshuting <shuting@nirmata.com>
realshuting added a commit to kyverno/kyverno that referenced this pull request Jul 23, 2026
…nterpolation (#16699)

* feat: add YAML template mode for GeneratingPolicy with optional CEL interpolation

Implements the template declaration mode for spec.generate[] entries
(kyverno/api#115): generated resources can be authored as plain YAML
(single or multi-document) with optional CEL (( ... )) placeholder
interpolation, instead of dyn()-heavy CEL object construction.

- new pkg/cel/policies/gpol/template package: placeholder scanner
  (paren/quote aware, \(( escape) and structural YAML-node
  interpolation - whole-value placeholders splice native CEL results
  (maps/lists/scalars), embedded placeholders interpolate strings,
  placeholders in mapping keys are rejected at compile time
- gpol compiler compiles each generate entry into an expression or
  template union; template placeholder expressions are compiled eagerly
  with spec.generate[i].template.value diagnostics
- runtime renders templates against the same CEL activation and feeds
  the existing GenerateResources() path, preserving synchronize,
  generateExisting, orphanDownstreamOnPolicyDelete and scope semantics;
  namespace targeting is per-document via metadata.namespace, and
  namespaced policies are locked to their own namespace
- template placeholder expressions are included in the namespaced
  policy http.* restriction check
- regenerated policies CRDs (includes upstream api drift picked up by
  the dependency bump)
- unit, integration (expression/template parity), CLI and chainsaw
  conformance tests

Closes #16331

Signed-off-by: realshuting <shuting@nirmata.com>

* test: add chainsaw conformance tests for gpol template mode

- generate-multiple-resources: a single generate template entry with
  multi-document YAML producing a ConfigMap and a Secret
- generate-ciliumnetworkpolicy: mirrors the CiliumNetworkPolicy
  migration case from #16331 - LabelSelector whole-value structural
  splice, mixed static/interpolated toPorts, minimal cilium.io CRD
  and background-controller RBAC
- fix _step-templates relative paths in the template test directory

All three template tests verified against a local kind cluster.

Signed-off-by: realshuting <shuting@nirmata.com>

* chore: bump github.com/kyverno/api for GenerationTemplate

Picks up kyverno/api#115 which adds the Generation.Template API.
Regenerated CRDs are unchanged (already in sync).

Signed-off-by: realshuting <shuting@nirmata.com>

* test: verify expression and template entries mix within one policy

The exactly-one-of rule applies per generate[] entry, not per policy;
add an evaluation test proving both entry kinds coexist and generate
their resources in order.

Signed-off-by: realshuting <shuting@nirmata.com>

* chore: regenerate API reference docs for GenerationTemplate

make codegen-all-docs picks up the GenerationTemplate and
InterpolationMode types added by the kyverno/api bump.

Signed-off-by: realshuting <shuting@nirmata.com>

* fix: address template mode review comments and improve codegen CI

Review fixes:
- Render numbers documents starting at 1 in error messages, matching
  YAML conventions and 1-based line numbers
- ExtractExpressions returns an empty result for malformed YAML instead
  of a partial set that could surface misleading validation errors
- celValueToNative rejects uint values that overflow int64 instead of
  silently wrapping
- rename and extend the mislabeled splice test to cover both map and
  list splicing

Codegen CI improvements:
- verify-codegen jobs upload the regenerated diff as a patch artifact
  on failure, so contributors can 'git apply' the fix instead of
  re-running slow codegen locally
- new 'make codegen-api-bump' target chains codegen-all-code and
  codegen-all-docs, the exact set required after a kyverno/api bump
- document both in DEVELOPMENT.md

Signed-off-by: realshuting <shuting@nirmata.com>

---------

Signed-off-by: realshuting <shuting@nirmata.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants