Add troubleshooting note; etc. (#1178)

* add note

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

* fix sentence on resource filters

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

* Documents `--webhookServerPort` flag

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

* tweak

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

* fix link

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

---------

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

content/en/docs/Installation/customization.md

@@ -282,7 +282,7 @@ The following keys are used to control the behavior of Kyverno and must be set i
 
 ### Container Flags
 
-The following flags can be used to control the advanced behavior of the various Kyverno controllers and should be set on the main container in the form of arguments. All container flags can be prefaced with one or two dashes (ex., `-admissionReports` or `--admissionReports`). Where each flag is accepted is given in parenthesis.
+The following flags can be used to control the advanced behavior of the various Kyverno controllers and should be set on the main container in the form of arguments. All container flags can be prefaced with one or two dashes (ex., `-admissionReports` or `--admissionReports`). The controller(s) to which a given flag is applicable is shown in parenthesis.
 
 * A: Admission controller
 * B: Background controller
@@ -362,6 +362,7 @@ The following flags can be used to control the advanced behavior of the various
 | `validatingAdmissionPolicyReports` (R) | false | Specifies whether to enable generating Policy Reports for Kubernetes ValidatingAdmissionPolicies. |
 | `vmodule` (ABCR) | | Comma-separated list of pattern=N settings for file-filtered logging. |
 | `webhookRegistrationTimeout` (A) | `120s` | Specifies the length of time Kyverno will try to register webhooks with the API server. |
+| `webhookServerPort` (AC) | `9443` | Specifies the port to use for webhook call-backs. |
 | `webhookTimeout` (A) | `10` | Specifies the timeout for webhooks, in seconds. After the timeout passes, the webhook call will be ignored or the API call will fail based on the failure policy. The timeout value must be an integer number between 1 and 30 (seconds). |
 
 ### Policy Report access
@@ -441,7 +442,7 @@ graph LR
   id3 --> id4["Kyverno engine"]
 ```
 
-Resource filters, unlike webhooks, may effect more than just admission requests--they have the ability to effect policy reports in background scans as well. By default, however, the configured resource filters are taken into account during background reporting scans. Filters listed will prevent policy report results from being created. Also note that resource filters do not effect mutations for existing resources.
+Resource filters, unlike webhooks, may effect more than just admission requests--they have the ability to effect policy reports in background scans as well. By default, however, the configured resource filters are not taken into account during background reporting scans. This behavior may be configured with the `--skipResourceFilters` container flag as described in the [Container Flags](#container-flags) section. Also note that resource filters do not effect mutations for existing resources.
 
 The Kubernetes kinds that should be ignored by policies can be filtered out by modifying the value of `data.resourceFilters` in Kyverno's ConfigMap stored in its Namespace. The default name of this ConfigMap is `kyverno` but can be changed by modifying the value of the environment variable `INIT_CONFIG` in the Kyverno deployment spec. `data.resourceFilters` must be a sequence of one or more `[<Kind>,<Namespace>,<Name>]` entries with `*` as a wildcard (`*/*` indicates all subresources within all kinds). Thus, an item `[Secret,*,*]` means that admissions of kind `Secret` in any Namespace and with any name will be ignored. Wildcards are also supported in each of these sequences. For example, the sequence `[Pod,foo-system,redis*]` filters out kind `Pod` in Namespace `foo-system` having names beginning with `redis`.
 

content/en/docs/Troubleshooting/_index.md

@@ -169,4 +169,16 @@ The second most common reason policies may fail to operate per design is due to
 **Diagnose**: Please follow the [troubleshooting docs](https://github.com/kyverno/kyverno/blob/main/docs/dev/troubleshooting/reports.md) to determine if you are affected by this issue.
 
 **Solution**: Admission reports can accumulate if the reports controller is not working properly so the first thing to check is if the reports controller is running and does not continuously restarts. If the controller works as expected, another potential cause is that it fails to aggregate admission reports fast enough. This usually happens when the controller is throttled. You can fix this by increasing QPS and burst rates for the controller by setting `--clientRateLimitQPS=500` and `--clientRateLimitBurst=500`.
-Note that starting with Kyverno 1.10, two cron jobs are responsible for deleting admission reports automatically if they accumulate over a certain threshold.
+Note that starting with Kyverno 1.10, two cron jobs are responsible for deleting admission reports automatically if they accumulate over a certain threshold.
+
+## Kyverno says it does not have permissions when creating a policy
+
+**Symptom**: Attempting to create a [mutate existing](/docs/writing-policies/mutate/#mutate-existing-resources) or [generate](/docs/writing-policies/generate/) policy and Kyverno throws an error similar to the one below:
+
+```
+Error from server: error when creating "my_cluster_policy.yaml": admission webhook "validate-policy.kyverno.svc" denied the request: path: spec.rules[0].generate..: system:serviceaccount:kyverno:kyverno-background-controller does not have permissions to 'create' resource source.toolkit.fluxcd.io/v1beta2/helmrepository//{{request.object.metadata.name}}. Grant proper permissions to the background controller
+```
+
+**Diagnose**: Use `kubectl` to assess whether the Kyverno background controller has the necessary permissions: `kubectl auth can-i create helmrepositories --as system:serviceaccount:kyverno:kyverno-background-controller`. If the response you get from this command is "no" then Kyverno will also receive the same.
+
+**Solution**: The background controller processes all mutations on existing resources and generations. It ships with only a minimal set of permissions. Any additional permissions are up to the user to add. Kyverno performs permissions checks upon creation/update of policies processed by the background controller. If the required permissions are not found, the operation is prevented. This is to ensure a good user experience is maintained. See the page on customizing permissions [here](/docs/installation/customization/#customizing-permissions) for instructions on how to easily add the permissions you require. If you have done this and still cannot proceed, likely causes include you targeting the wrong controller, one or more labels is wrong causing aggregation to not occur, or the permissions you have defined in the (Cluster)Role are incorrect (ex., specifying the resource name(s) using their singular form rather than plural). Fix the issues and re-run the `kubectl auth` command. Until it returns with a "yes" the permissions are not correct.

content/en/docs/Writing policies/external-data-sources.md

@@ -773,7 +773,7 @@ context:
       jmesPath: "to_string(sum(manifest.layers[*].size))"
 ```
 
-To access images stored on private registries, see [using private registries](/docs/writing-policies/verify-images#using-private-registries)
+To access images stored on private registries, see [using private registries](/docs/writing-policies/verify-images/sigstore/#using-private-registries)
 
 For more examples of using an imageRegistry context, see the [samples page](/policies).