Tips & Tricks

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. In most cases, rules can be grouped into a single policy definition. Here are some tips when it comes to organizing rules:

  • Create a single ClusterPolicy for all validate rules and a Policy for all Namespaced validate rules.
  • mutate and generate rules should go into their own policy definition.
  • Policies that cannot be written as a single rule but have highly related processing can go into their own policy definition.
  • Name your rules effectively as this is a component that will be displayed to users upon enforcement for validate rules.

• 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 have no precedence/overriding behavior, so even though a rule may be written to either allow or deny a resource/action, one 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.

• In some less common cases, Kyverno will attempt to validate the schema of a policy and fail because it cannot determine if it satisfies the OpenAPI schema definition for that resource. In these cases add spec.schemaValidation: false to your policy to tell Kyverno to skip validation. This is similar to passing the --validate flag to kubectl.

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.

• Just like in validate rules, in some less common cases Kyverno will attempt to validate the schema of a policy and fail because it cannot determine if it satisfies the OpenAPI schema definition for that resource. In mutate rules, Kyverno will internally try to generate a patch to see if the policy would be valid. In these cases add spec.schemaValidation: false to your policy to tell Kyverno to skip validation. This is similar to passing the --validate flag to kubectl.

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.