From 567e18e3713267d33b3752bb314a521c671edd4a Mon Sep 17 00:00:00 2001 From: Alfonso Acosta Date: Thu, 16 Jan 2020 19:24:06 +0100 Subject: [PATCH] Rename --k8s-exclude-resource to --k8s-unsafe-exclude-resource Also, add a troubleshooting section explaning its implications. --- cmd/fluxd/main.go | 2 +- docs/references/daemon.md | 2 +- docs/troubleshooting.md | 38 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 40 insertions(+), 2 deletions(-) diff --git a/cmd/fluxd/main.go b/cmd/fluxd/main.go index cb142609c..1235c9131 100644 --- a/cmd/fluxd/main.go +++ b/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 diff --git a/docs/references/daemon.md b/docs/references/daemon.md index 4a7f821ed..86c79fdd8 100644 --- a/docs/references/daemon.md +++ b/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 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 68638f446..d461170a7 100644 --- a/docs/troubleshooting.md +++ b/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. +