Tips & Tricks

Tips and tricks for writing more effective policy.

These are some tips and tricks you can use when putting together your Kyverno policies.

General

  • Need more examples or struggling to see a practical use case? Remember to check out the extensive community samples library for ideas on how to author certain types, as well as to kickstart your own needs. Very often, you may not need to start from scratch but can instead use one of the samples as a starting point to further customize.

  • Use kubectl explain to explain and explore the various parts and fields of a Kyverno policy. It works just like on native Kubernetes resources!

     1KIND:     Policy
     2VERSION:  kyverno.io/v1
     3
     4RESOURCE: validate <Object>
     5
     6DESCRIPTION:
     7    Validation is used to validate matching resources.
     8
     9FIELDS:
    10  anyPattern   <>
    11    AnyPattern specifies list of validation patterns. At least one of the
    12    patterns must be satisfied for the validation rule to succeed.
    13
    14  deny <Object>
    15    Deny defines conditions used to pass or fail a validation rule.
    16
    17  foreach      <Object>
    18    ForEach applies policy rule checks to nested elements.
    19
    20  message      <string>
    21    Message specifies a custom message to be displayed on failure.
    22
    23  pattern      <>
    24    Pattern specifies an overlay-style pattern used to check resources.
    
  • Use kubectl get kyverno -A to show all the Kyverno Custom Resources present in your cluster. This will return resources such as policies of various types, policy reports, and intermediary resources used internally by Kyverno.

  • When using VS Code, because of the OpenAPIV3 schema Kyverno supports, you can make use of this integration to assist in writing policy by getting field hints and describing elements.

  • Make use of the Kyverno CLI to test policies out in advance.

  • Organize your policies in a way which is meaningful to you, your organization, and your Kubernetes cluster design keeping in mind how they are processed. Each policy is processed in an idempotent manner while rules within policies are executed serially. When needing to control processing order, put highly-related rules in the same policy and use the applyRules field.

  • Ensure the resource you’re matching and the spec definition align. For example, if writing a mutate rule which matches on a Deployment, the spec of what is being mutated needs to also align to a Deployment which may be different from, for example, a Pod. When copying-and-pasting from other rules, remember to check the spec.

  • Check Kyverno logs when designing rules if the desired result is not achieved:

1kubectl -n <kyverno_namespace> logs <pod_name>

Depending on the level of detail needed, you may need to increase the log level. To see variable substitution messages, use log level 4. To see the full AdmissionReview payload sent by the Kubernetes API server to Kyverno, use the --dumpPayload=true flag and inspect the logs. Remember to remove this flag at the conclusion of your troubleshooting process.

Validate

  • When developing your validate policies, it’s easiest to set validationFailureAction: Enforce so when testing you can see the results immediately without having to look at a report.

  • Before deploying into production, ensure you have validationFailureAction: Audit so the policy doesn’t have unintended consequences.

  • validate rules cannot counteract the other. For example, a rule written to ensure all images come from registry reg.corp.com and another rule written to ensure they do not come from reg.corp.com will effectively render all image pulls impossible and nothing will run. Where the rule is defined is irrelevant.

  • The choice between using a pattern statement or a deny statement depends largely on the data you need to consider; pattern works on incoming (new) objects while deny can additionally work on variable data such as the API operation (CREATE, UPDATE, etc.), old object data, and ConfigMap data.

Mutate

  • When writing policies which perform cascading mutations, rule ordering matters. All rules which perform cascading mutations should be in the same policy definition and ordered top to bottom to ensure consistent results.

  • Need to mutate an object at a specific ordered position within an array? Use the patchesJson6902 method.

Generate

  • generate rules which trigger off the same source object should be organized in the same policy definition.

  • Be careful with the synchronize=true behavior as other users who may have privileges to change an object may do so to a Kyverno-protected object and see their changes wiped away during the next sync cycle.


Last modified June 08, 2024 at 6:16 PM PST: Docsy bump to 0.10.0 and docs fixes/enhancements (#1274) (ed2056b)