Feature Overview

Templating is the primary value point for the ACM / Open Cluster Management policy engine; however we frequently encounter users having challenges with developing and testing their templating.

This issue is to explore how we might be able to provide some solutions around improving the development experience of new policies.

Goals

This Section: Provide high-level goal statement, providing user context
and expected user outcome(s) for this feature

• Improve developer's abilities to craft custom configuration policies that leverage templating
• Improve debuggability of configuration policies that leverage templating
• Reduce the workflow loop and steps of developing policies, trying/deploying them, testing, and evaluating behavior
• More quickly demonstrate the value and power of templating in ConfigurationPolicies

Requirements

This Section: A list of specific needs or objectives that a Feature must
deliver to satisfy the Feature.. Some requirements will be flagged as MVP.
If an MVP gets shifted, the feature shifts. If a non MVP requirement slips,
it does not shift the feature.

(Optional) Use Cases

This Section:

• Templating requires proper syntax to be able to be properly evaluated
  • Users today have to apply the Policy, and wait for the status to return in the Policy status to know that the templating is broken
  • Alternatively, users now have the template-resolver to be able to run a CLI command; but this still requires another manual step to run the template-resolver each time they update any templates
  • Possible cases, but not limited to:
    • White-spacing issues:  https://redhat-internal.slack.com/archives/CU4QXLPQB/p1738788273427249 
    • Identation issues:  https://redhat-internal.slack.com/archives/CU4QXLPQB/p1738724618675239?thread_ts=1738711953.379259&cid=CU4QXLPQB 
    • Improper use of operators:  https://redhat-internal.slack.com/archives/CU4QXLPQB/p1738724618675239?thread_ts=1738711953.379259&cid=CU4QXLPQB 
    • Improper referencing when using hub templates:  https://redhat-internal.slack.com/archives/CU4QXLPQB/p1738333245554869 
      • Not closing hub template blocks:  https://redhat-internal.slack.com/archives/CU4QXLPQB/p1734656794958099?thread_ts=1734652299.160369&cid=CU4QXLPQB 
    • Variable scoping and referencing issues:  https://redhat-internal.slack.com/archives/CU4QXLPQB/p1737553387865359?thread_ts=1737499832.048449&cid=CU4QXLPQB 
    • https://redhat-internal.slack.com/archives/CU4QXLPQB/p1747339116842629 
• Templating limits the available sprig and go functions available to use
  • How to flag these and better let users know what is actually available
• Auto-completing templating code
  • Functions
  • lookups
    • If connected to a cluster, is it possible to auto-complete the API group, Kind, Namespace, Resource names, etc
  • Each code bracket
• Validating the API schema of the ConfigurationPolicy, OperatorPolicy
• OperatorPolicy
  • If connected to a cluster, allow for auto-completing values available from the OLM catalogs?

Questions to answer

• Is this mainly a "community" deliverable?
  • e.g. if we do a linter for an IDE; is that just a community thing?
  • e.g. if we do a playground; that would just be an OCM.io thing.
• (Sho) is more preferable to an IDE, linting-based solution for 2.14; if this a chosen and delivered solution, can the linting be integrated into the Create policy wizard?
• What is the right place or experience that we should be telling users to develop policies in?
  • Create policy wizard
  • IDE (e.g. VS Code)
  • Playground (doesn't exist)
    • https://playground.kyverno.io/#/ 
    • https://play.authzed.com/schema 

Out of Scope

• …

Background, and strategic fit

This Section: What does the person writing code, testing, documenting
need to know? What context can be provided to frame this feature?

Assumptions

• ...

Customer Considerations

• Customer will use pre-existing or sample policies to build new policies; they will dump the policy that is being newly drafted or edited into the Create policy wizard
  • The Create policy wizard is not providing sufficient hints on what is wrong with the templates; e.g. syntax errors
  • User is not using their local IDE
• Customers have to manually run template-resolver periodically and continuously to validate templates that are being drafted

Documentation Considerations

Questions to be addressed:

• What educational or reference material (docs) is required to support this
  product feature? For users/admins? Other functions (security officers, etc)?
• Does this feature have a doc impact?
• New Content, Updates to existing content, Release Note, or No Doc Impact
• If unsure and no Technical Writer is available, please contact Content
  Strategy.
• What concepts do customers need to understand to be successful in
  [action]?
• How do we expect customers will use the feature? For what purpose(s)?
• What reference material might a customer want/need to complete [action]?
• Is there source material that can be used as reference for the Technical
  Writer in writing the content? If yes, please link if available.
• What is the doc impact (New Content, Updates to existing content, or
  Release Note)?