Rename --k8s-exclude-resource to --k8s-unsafe-exclude-resource

cmd/fluxd/main.go

@@ -178,7 +178,7 @@ func main() {
 		k8sNamespaceWhitelist = fs.StringSlice("k8s-namespace-whitelist", []string{}, "restrict the view of the cluster to the namespaces listed. All namespaces are included if this is not set")
 		k8sAllowNamespace     = fs.StringSlice("k8s-allow-namespace", []string{}, "restrict all operations to the provided namespaces")
 		k8sDefaultNamespace   = fs.String("k8s-default-namespace", "", "the namespace to use for resources where a namespace is not specified")
-		k8sExcludeResource    = fs.StringSlice("k8s-exclude-resource", []string{"*metrics.k8s.io/*", "webhook.certmanager.k8s.io/*", "v1/Event"}, "do not attempt to obtain cluster resources whose group/version/kind matches these glob expressions")
+		k8sExcludeResource    = fs.StringSlice("k8s-unsafe-exclude-resource", []string{"*metrics.k8s.io/*", "webhook.certmanager.k8s.io/*", "v1/Event"}, "do not attempt to obtain cluster resources whose group/version/kind matches these glob expressions. Potentially unsafe, please read its documentation first")
 		k8sVerbosity          = fs.Int("k8s-verbosity", 0, "klog verbosity level")
 
 		// SSH key generation

docs/references/daemon.md

@@ -87,7 +87,7 @@ Version controlling of cluster manifests provides reproducibility and a historic
 | **k8s configuration**
 | --k8s-allow-namespace                            |                                    | restrict all operations to the provided namespaces
 | --k8s-default-namespace                          |                                    | the namespace to use for resources where a namespace is not specified
-| --k8s-exclude-resource                           | `["*metrics.k8s.io/*", "webhook.certmanager.k8s.io/*", "v1/Event"]` | do not attempt to obtain cluster resources whose group/version/kind matches these glob expressions, e.g. `coordination.k8s.io/v1beta1/Lease`, `coordination.k8s.io/*/Lease` or `coordination.k8s.io/*`
+| --k8s-unsafe-exclude-resource                    | `["*metrics.k8s.io/*", "webhook.certmanager.k8s.io/*", "v1/Event"]` | do not attempt to obtain cluster resources whose group/version/kind matches these glob expressions, e.g. `coordination.k8s.io/v1beta1/Lease`, `coordination.k8s.io/*/Lease` or `coordination.k8s.io/*`. Potentially unsafe, please read Flux's troubleshooting section on `--k8s-unsafe-exclude-resource` before using it.
 | **upstream service**
 | --connect                                        |                                    | connect to an upstream service e.g., Weave Cloud, at this base address
 | --token                                          |                                    | authentication token for upstream service

docs/troubleshooting.md

@@ -149,3 +149,41 @@ releases (including automated upgrades) it has applied, and that only
 matters if it has been asked to report those with the `--connect`
 flag. Future versions of Flux may be more sparing in use of the sync
 tag.
+
+### Flux fails with an error log similar to _couldn't get resource list for example.com/version: the server is currently unable to handle the request_
+
+This means your Kubernetes cluster fails to respond to list queries
+for resources in _example.com/version_.
+
+If the error is transient, Flux will work once the error recedes.
+
+However, the error won't normally go away since most of the time it's caused by 
+a misconfiguration of your cluster.
+
+For instance, you can run into this problem:
+  * When a
+    [Kubernetes Webhook server](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/)
+    is removed without removing its Webhook definition.
+  * When a custom resource definition (CRD) is not available due to
+    a `FailedDiscoveryCheck` error.
+
+We recommend trying to address the root cause by fixing your cluster
+configuration. In the examples above, you would need to remove the Webhook
+definition or add the CRD.
+
+However, fixing your cluster configuration may not always be possible. The
+problem is common enough that Flux provides a flag called
+`--k8s-unsafe-exclude-resource`. The name says it all, you should only use it
+if you know what you are doing.
+
+`--k8s-unsafe-exclude-resource` will tell Flux to avoid querying the cluster
+for those resources. This in turn means that Flux won't take into account those
+excluded cluster resources when syncing. This can cause excluded resources:
+  * to be unexpectedly overwritten by their corresponding definition in
+    Git during a sync (even if they are annotated with
+    `flux.weave.works/ignore: "true"` on the cluster-side).
+  * not to be garbage-collected.
+
+The rule of thumb is that you can use `--k8s-unsafe-exclude-resource` on
+resources not matching any manifests in your Git repository. 
+