Developer feedback

Help the reader find the failed layer

A useful failure report answers four questions: what failed, which input was checked, what can be changed, and where the reader can inspect the evidence. Without those details, a policy turns a predictable mistake into a support conversation.

A policy failure is a user interface

Compare “validation failed” with “Accounts and Ledger need Pod-template label platform.learnwithsk.dev/owner=microbank.” The second message identifies the expected field and value. Add a runbook link in the developer-facing report when your integration supports it, plus policy name, resource, and evaluation time.

Do not require a developer to guess which of several layers rejected a release. Build tests, manifest validation, policy evaluation, admission, reconciliation, and business checks should each report their own status.

Connect policy to the delivery path

Run fast offline checks before a deployment request is reviewed. At admission, retain the controller's actual failure details. In a portal, distinguish not evaluated, failed, passed, and stale. A default green card hides missing integrations.

Keep policy outputs free of secret values. Resource names and source revisions usually suffice for diagnosis. If an error includes a confidential configuration value, preserve it in restricted logs and show a sanitized explanation to the broader audience.

Repair this report

Weak report: “Deployment validation failed.”

Better teaching example: “Owner check failed for Deployment/accounts in the local rendered manifest at revision R2. Add platform.learnwithsk.dev/owner: microbank under spec.template.metadata.labels. Re-render and rerun the owner fixtures. If the supplied platform base lacks the label, contact its maintainer.”

R2 is an illustrative revision label, not a claimed run. In an actual report, include the real revision and a link to its output. The message points to the nested field so a learner does not add the label only to the Deployment itself.

Now classify three possible reports:

• “YAML parser expected a mapping”: fix document structure before policy evaluation.
• “Owner must be microbank”: repair the matching policy field, then rerun.
• “No resources matched”: investigate scope or input selection; do not report a pass.

Use the same distinction in CI and the portal. A report from an earlier revision should be labelled stale. A missing integration should say not evaluated. The report's job is to help a person make the next correct decision, not to keep a dashboard green.

Try it

Use the invalid fixture from the policy lab as a support exercise. Read only the report, correct the Pod-template label, rerun the test, and confirm the same rule now passes. Record how many unrelated documents you had to open.

Then induce a different failure in an offline copy, such as malformed YAML. Confirm the report describes a parse problem rather than an ownership violation. Report the stage that failed so the developer can choose the right repair.

Checkpoint and revision

Write the failure message, suggested repair, escalation owner, and evidence link for your rule. Have someone unfamiliar with it attempt the correction when possible. Treat clear feedback as part of the policy’s operating behavior and test it before enforcement.

Compare your reasoning

A good error points at the smallest repair without printing secrets. In the next lab, first use a deliberately wrong field to test the message, then a valid one to confirm the repair works. Preserve both observations instead of only the final successful screen.

Sources

Kyverno reports↗, Backstage template authorization↗.