Misc fixes (#1175)

* update sample

Signed-off-by: chipzoller <chipzoller@gmail.com>

* clarify use of `log_backtrace_at` container flag

Signed-off-by: chipzoller <chipzoller@gmail.com>

* clarify auth for registry

Signed-off-by: chipzoller <chipzoller@gmail.com>

* clarify GVK

Signed-off-by: chipzoller <chipzoller@gmail.com>

* better tip

Signed-off-by: chipzoller <chipzoller@gmail.com>

* better troubleshooting

Signed-off-by: chipzoller <chipzoller@gmail.com>

* clarify results[].policy format

Signed-off-by: chipzoller <chipzoller@gmail.com>

---------

Signed-off-by: chipzoller <chipzoller@gmail.com>

content/en/docs/Installation/customization.md

@@ -318,13 +318,12 @@ The following flags can be used to control the advanced behavior of the various
 | `generateValidatingAdmissionPolicy` (A) | false | Specifies whether to enable generating Kubernetes ValidatingAdmissionPolicies. |
 | `genWorkers` (B) | 10 | The number of workers for processing generate policies concurrently. |
 | `imagePullSecrets` (ABR) | | Specifies secret resource names for image registry access credentials. All referenced secrets must exist in Kyverno's Namespace. Multiple values are accepted but must be comma separated. |
-| `imageSignatureRepository` (AR) | | Specifies alternate repository for image signatures. Can be overridden per rule via `verifyImages.Repository`. |
 | `imageVerifyCacheEnabled` (A) | true | Enable a TTL cache for verified images. |
 | `imageVerifyCacheMaxSize` (A) | 1000 | Maximum number of keys that can be stored in the TTL cache. Keys are a combination of policy elements along with the image reference. `0` sets the value to default. |
 | `imageVerifyCacheTTLDuration` (A) | 60m | Maximum TTL value for a cache expressed as duration. `0` sets the value to default. |
 | `kubeconfig` (ABCR) | | Specifies the Kubeconfig file to be used when overriding the API server to which Kyverno should communicate. Only used when Kyverno is running outside of the cluster in which it services admission requests. |
 | `leaderElectionRetryPeriod` (ABCR) | `2s` | Controls the leader election renewal frequency. |
-| `log_backtrace_at` (ABCR) | | When logging hits line file:N, emit a stack trace. |
+| `log_backtrace_at` (ABCR) | | When logging hits line file:N, emit a stack trace. May only be specified once. |
 | `log_dir` (ABCR) | | If non-empty, write log files in this directory (no effect when -logtostderr=true). |
 | `log_file` (ABCR) | | If non-empty, use this log file (no effect when -logtostderr=true). |
 | `log_file_max_size` (ABCR) | `1800` | Defines the maximum size a log file can grow to (no effect when -logtostderr=true). Unit is megabytes. If the value is 0, the maximum file size is unlimited. |
@@ -344,7 +343,7 @@ The following flags can be used to control the advanced behavior of the various
 | `protectManagedResources` (AC) | false | Protects the Kyverno resources from being altered by anyone other than the Kyverno Service Account. Set to `true` to enable. |
 | `registryCredentialHelpers` (ABR) | | Enables cloud-registry-specific authentication helpers. Defaults to `"default,google,amazon,azure,github"`. |
 | `renewBefore` (AC) | `15d` | Sets the certificate renewal time before expiration (in days). |
-| `reportsChunkSize` (R) | `1000` | Maximum number of results in generated reports before splitting occurs if there are more results to be stored. |
+| `reportsChunkSize` (R) | `1000` | Maximum number of results in generated reports before splitting occurs if there are more results to be stored. Deprecated. |
 | `serverIP` (AC) | | Like the `kubeconfig` flag, used when running Kyverno outside of the cluster which it serves. |
 | `servicePort` (AC) | `443` | Port used by the Kyverno Service resource and for webhook configurations. |
 | `skipResourceFilters` (R) | true | Defines whether to obey the ConfigMap's resourceFilters when performing background report scans. When set to `true`, anything defined in the resourceFilters will not be excluded in background reports. Ex., when set to `true` if the resourceFilters contain the `[*/*,kube-system,*]` entry then background scan reports will be produced for anything in the `kube-system` Namespace. Set this value to `false` to obey resourceFilters in background scan reports. Ex., when set to `false` if the resourceFilters contain the `[*/*,kube-system,*]` entry then background scan reports will NOT be produced for anything in the `kube-system` Namespace. |

content/en/docs/Kyverno CLI/_index.md

@@ -156,7 +156,7 @@ Format of `value.yaml` with all possible fields:
 
 ```yaml
 apiVersion: cli.kyverno.io/v1alpha1
-kind: Value
+kind: Values
 metadata:
   name: values
 policies:
@@ -256,7 +256,7 @@ YAML file containing variables (`value.yaml`):
 
 ```yaml
 apiVersion: cli.kyverno.io/v1alpha1
-kind: Value
+kind: Values
 metadata:
   name: values
 policies:
@@ -288,7 +288,7 @@ Format of `value.yaml`:
 
 ```yaml
 apiVersion: cli.kyverno.io/v1alpha1
-kind: Value
+kind: Values
 metadata:
   name: values
 policies:
@@ -374,7 +374,7 @@ YAML file containing variables (`value.yaml`):
 
 ```yaml
 apiVersion: cli.kyverno.io/v1alpha1
-kind: Value
+kind: Values
 metadata:
   name: values
 policies:
@@ -405,7 +405,7 @@ Format of `value.yaml`:
 
 ```yaml
 apiVersion: cli.kyverno.io/v1alpha1
-kind: Value
+kind: Values
 metadata:
   name: values
 namespaceSelector:
@@ -478,7 +478,7 @@ YAML file containing variables (`value.yaml`):
 
 ```yaml
 apiVersion: cli.kyverno.io/v1alpha1
-kind: Value
+kind: Values
 metadata:
   name: values
 namespaceSelector:
@@ -549,7 +549,7 @@ spec:
 
 ```yaml
 apiVersion: cli.kyverno.io/v1alpha1
-kind: Value
+kind: Values
 metadata:
   name: values
 policies:
@@ -1128,7 +1128,7 @@ exceptions: # optional files for specifying exceptions. See below for an example
 variables: variables.yaml # optional file for declaring variables. see below for example.
 userinfo: user_info.yaml # optional file for declaring admission request information (roles, cluster roles and subjects). see below for example.
 results:
-- policy: <name>
+- policy: <name> # Namespaced Policy is specified as <namespace>/<name>
   isValidatingAdmissionPolicy: false # when the policy is ValidatingAdmissionPolicy, this field is required.
   rule: <name> # when the policy is a Kyverno policy, this field is required.
   resources: # optional, primarily for `validate` rules.
@@ -1154,7 +1154,7 @@ If needing to pass variables, such as those from [external data sources](/docs/w
 
 ```yaml
 apiVersion: cli.kyverno.io/v1alpha1
-kind: Value
+kind: Values
 metadata:
   name: values
 policies:
@@ -1176,7 +1176,7 @@ A variables file may also optionally specify global variable values without the
 
 ```yaml
 apiVersion: cli.kyverno.io/v1alpha1
-kind: Value
+kind: Values
 metadata:
   name: values
 globalValues:
@@ -1187,7 +1187,7 @@ If policies use a namespaceSelector, these can also be specified in the variable
 
 ```yaml
 apiVersion: cli.kyverno.io/v1alpha1
-kind: Value
+kind: Values
 metadata:
   name: values
 namespaceSelector:
@@ -1213,7 +1213,7 @@ Testing for subresources in `Kind/Subresource` matching format also requires a `
 
 ```yaml
 apiVersion: cli.kyverno.io/v1alpha1
-kind: Value
+kind: Values
 metadata:
   name: values
 subresources:
@@ -1233,7 +1233,7 @@ Here is an example when testing for subresources:
 
 ```yaml
 apiVersion: cli.kyverno.io/v1alpha1
-kind: Value
+kind: Values
 metadata:
   name: values
 subresources:
@@ -1456,7 +1456,7 @@ Variables manifest (`values.yaml`):
 
 ```yaml
 apiVersion: cli.kyverno.io/v1alpha1
-kind: Value
+kind: Values
 metadata:
   name: values
 policies:

content/en/docs/Troubleshooting/_index.md

@@ -92,7 +92,7 @@ Use [Namespace selectors](/docs/installation/customization/#namespace-selectors)
 
 **Symptom**: Kyverno is using too much memory or CPU. How can I understand what is causing this?
 
-**Solution**: It is important to understand how Kyverno experiences and processes work to know if what you deem as "too much" is, in fact, too much. Kyverno dynamically configures its webhooks (by default but configurable) according the policies which are loaded and on what resources they match. There is no easy rubric to follow where resource requirements are directly proportional to, for example, number of Pods or Nodes in a cluster. The following questions need to be asked and answered to build a full picture of the resources consumed by Kyverno.
+**Solution**: It is important to understand how Kyverno experiences and processes work to determine if what you deem as "too much" is, in fact, too much. Kyverno dynamically configures its webhooks (by default but configurable) according the policies which are loaded and on what resources they match. There is no straightforward formula where resource requirements are directly proportional to, for example, number of Pods or Nodes in a cluster. The following questions need to be asked and answered to build a full picture of the resources consumed by Kyverno.
 
 1. What policies are in the cluster and on what types of resources do they match? Policies which match on wildcards (`"*"`) cause a tremendous load on Kyverno and should be avoided if possible as they instruct the Kubernetes API server to send to Kyverno _every action on every resource_ in the cluster. Even if Kyverno does not have matching policies for most of these resources, it is _required_ to respond to every single one. If even one policy matches on a wildcard, expect the resources needed by Kyverno to easily double, triple, or more.
 2. Which controller is experiencing the load? Each Kyverno controller has different responsibilities. See the [controller guide](/docs/high-availability/#controllers-in-kyverno) for more details. Each controller can be independently scaled, but before immediately scaling in any direction take the time to study the load.

content/en/docs/Writing policies/jmespath.md

@@ -305,6 +305,10 @@ deny:
 
 It is common for a JMESPath expression to name a specific field so that its value may be acted upon. For example, in the [basics section](#basics) above, the label `appns` is written to a Pod via a mutate rule which does not contain it or is set to a different value. A Kyverno validate rule which exists to check the value of that label or any other field is commonplace. Because the schema for many Kubernetes resources is flexible in that many fields are optional, policy rules must contend with the scenario in which a matching resource does not contain the field being checked. When using JMESPath to check the value of such a field, a simple expression might be written `{{request.object.metadata.labels.appns}}`. If a resource is submitted which either does not contain any labels at all or does not contain a label with the specified key then the expression cannot be evaluated. An error is likely to result similar to `JMESPath query failed: Unknown key "labels" in path`. In these types of cases, the JMESPath expression should use a non-existence check in the form of the [OR expression](https://jmespath.org/specification.html#or-expressions) followed by a "default" value if the field does not exist. The resulting full expression which will correctly evaluate is `{{request.object.metadata.labels.appns || ''}}`. This expression reads, "take the value of the key request.object.metadata.labels.appns or, if it does not exist, set it to an empty string". Note that the value on the right side may need to be customized given the ultimate use of the value expected to be produced. This non-existence pattern can be used in almost any JMESPath expression to mitigate scenarios in which the initial query may be invalid.
 
+{{% alert title="Note" color="info" %}}
+When using the OR expression, if the left side equals `null`/`nil` or a value of `false` it will cause the right side to be evaluated instead. Some fields in Kubernetes define boolean values so be aware of what effect this might have if the field is present but with a value of `false`. One way to work around this is to use `to_string()` to convert the boolean to a string.
+{{% /alert %}}
+
 ### Matching Special Characters
 
 Kyverno reserves [special behavior for wildcard characters](/docs/writing-policies/validate/#wildcards) such as `*` and `?`. However, certain Kubernetes resources permit wildcards as values in various fields which are treated literally. It may be necessary to construct a policy which validates literal usage of such wildcards. Using the JMESPath [`contains()`](https://jmespath.org/specification.html#contains) filter it is possible to do so. The below policy shows how to use `contains()` to match on wildcards as literal characters.

content/en/docs/Writing policies/match-exclude.md

@@ -27,7 +27,7 @@ Specifying resource filters directly under `match` and `exclude` has been marked
 
 At least one element must be specified in a `match.(any/all).resources.kinds` or `exclude` block. The `kind` attribute is mandatory when working with the `resources` element. Wildcards (`*`) are supported in the `resources.kinds` and `subjects` fields.
 
-In addition, a user may specify the `group` and `apiVersion` with a kind in the `match` / `exclude` declarations for a policy rule.
+In addition, a user may specify the `group` and `apiVersion` with a kind in the `match` / `exclude` declarations for a policy rule, known as GVK format.
 
 Supported formats:
 
@@ -86,6 +86,8 @@ spec:
           - CREATE
 ```
 
+The `operations[]` list is optional but recommended. When `operations[]` is absent, the default behavior is to match on `CREATE` and `UPDATE` requests.
+
 By combining multiple elements in the `match` statement, you can be more selective as to which resources you wish to process. Additionally, wildcards are supported for even greater control. For example, by adding the `resources.names` field, the previous `match` statement can further filter out Services that begin with the text "prod-" **OR** have the name "staging". `resources.names` takes in a list of names and would match all resources which have either of those names.
 
 ```yaml

content/en/docs/Writing policies/tips.md

@@ -43,11 +43,7 @@ These are some tips and tricks you can use when putting together your Kyverno po
 * 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](/docs/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.
+* 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.
 

content/en/docs/Writing policies/verify-images/sigstore/_index.md

@@ -46,6 +46,9 @@ spec:
                 MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8nXRh950IZbRj8Ra/N9sbqOPZrfM
                 5/KAQN0/KjHcorm/J5yctVd7iEcnessRQjU917hmKO6JWVGHpDguIyakZA==
                 -----END PUBLIC KEY-----
+              rekor:
+                ignoreTlog: true
+                url: https://rekor.sigstore.dev
 ```
 
 {{% alert title="Note" color="info" %}}
@@ -602,7 +605,7 @@ Private registries are defined as those requiring authentication in order to pul
 
 ### Authentication
 
-In order for Kyverno to authenticate against a registry (private or otherwise), you must first create an [imagePullSecret](https://kubernetes.io/docs/concepts/containers/images/#using-a-private-registry) in the Kyverno Namespace and specify the Secret name as an argument to the Kyverno Deployment.
+In order for Kyverno to authenticate against a registry (private or otherwise), you must first create an [imagePullSecret](https://kubernetes.io/docs/concepts/containers/images/#using-a-private-registry) in the Kyverno Namespace and specify the Secret name as an argument to the Kyverno Deployment. Note that this is not a requirement in all cases, for example see [AWS with IRSA](#enabling-irsa-to-access-aws-kms).
 
 1. Configure the imagePullSecret: