do NOT use Istio discovery selectors

content/en/docs/Configuration/namespace-management.md

@@ -7,7 +7,7 @@ description: "Configuring the namespaces accessible and visible to Kiali."
 
 The default Kiali [installation]({{< ref "/docs/installation/installation-guide" >}}) gives Kiali access to all namespaces available in the cluster and will allow all namespaces to be visible.
 
-It is possible to restrict Kiali so that it can only access a specific set of namespaces by providing [discovery selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements) that match those namespaces. Kiali can also use [Istio's discovery selectors](https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/#MeshConfig) for this purpose.
+It is possible to restrict Kiali so that it can only access a specific set of namespaces by providing [discovery selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements) that match those namespaces. Note that Kiali will not use [Istio's discovery selectors](https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/#MeshConfig); if Istio has been configured with its own discovery selectors, you will likely want to configure Kiali with the same list of discovery selectors.
 
 {{% alert color="info" %}}
 This documentation makes a distinction between a namespace that is _accessible_ verses _visible_. Kiali can be given access to all namespaces in the cluster, or it can be given restricted permissions so that only certain namespaces are accessible to it. Of the accessible namespaces that Kiali is permitted to see, it can make some or all of them visible to end users.
@@ -51,10 +51,10 @@ spec:
           operator: Exists
 ```
 
-When `cluster_wide_access` is set to `false`, the Kiali Operator will examine the `default` selectors under `spec.deployment.discovery_selectors`, as the example above illustrates. If there are none defined, the Kiali Operator will examine the [Istio discovery selectors](https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/#MeshConfig) as a fallback. The Kiali Operator will then attempt to find all the namespaces that match the discovery selectors. For each namespace that matches the discovery selectors, the Kiali Operator will create a Role and assign that Role to the Kiali Service Account thus giving Kiali access to those namespaces. These namespaces are therefore called the "accessible namespaces".
+When `cluster_wide_access` is set to `false`, the Kiali Operator will examine the `default` selectors under `spec.deployment.discovery_selectors`, as the example above illustrates. The Kiali Operator will then attempt to find all the namespaces that match the discovery selectors. For each namespace that matches the discovery selectors, the Kiali Operator will create a Role and assign that Role to the Kiali Service Account thus giving Kiali access to those namespaces. These namespaces are therefore called the "accessible namespaces".
 
 {{% alert color="info" %}}
-The Kiali Operator will always give the Kiali Server access to the namespace where the Kiali Server is installed and to the Istio control plane namespace, whether those namespaces match a discovery selector or not. When `cluster_wide_access` is `false` and no discovery selectors are defined, the Kiali Server will only be given access to those namespaces.
+The Kiali Operator will always give the Kiali Server access to the namespace where the Kiali Server is installed and to the Istio control plane namespace (which may be the same namespace), whether those namespaces match a discovery selector or not. When `cluster_wide_access` is `false` and no discovery selectors are defined, the Kiali Server will only be given access to those two namespaces.
 {{% /alert %}}
 
 {{% alert color="info" %}}
@@ -75,7 +75,7 @@ When installing multiple Kiali instances into a single cluster, `deployment.disc
 
 ## Istio Discovery Selectors
 
-In Istio's [MeshConfig](https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/#MeshConfig), you can provide a list of discovery selectors that Istio will consider when processing namespaces. These Istio discovery selectors are utilized if there are no `deployment.discovery_selectors.default` discovery selectors configured in the Kiali CR (i.e. the Istio discovery selectors are the fallback defaults).
+In Istio's [MeshConfig](https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/#MeshConfig), a list of discovery selectors can be configured. These Istio discovery selectors define the namespaces that Istio will consider "in the mesh." (see [this blog post](https://istio.io/v1.13/blog/2021/discovery-selectors/) for details). These Istio discovery selectors are utilized only by Istio; they will be ignored by Kiali.
 
 ## Operator Namespace Watching
 
@@ -106,7 +106,7 @@ The `default` discovery selectors define the namespaces on the local cluster tha
 It is assumed Kiali will have access to the same set of namespaces on the remote clusters as well. So Kiali will make those remote namespaces visible to users. However, if a remote cluster has a different set of namespaces that should be visible to Kiali users, you can set discovery selector `overrides` in `deployment.discovery_selectors` to match those remote namespaces.
 
 {{% alert color="info" %}}
-Each remote cluster `overrides` section completely overrides the default discovery selectors. That is to say, if a remote cluster has discovery selector overrides defined, only those selectors are used to determine which remote namespaces are to be visible to users. Neither the `default` discovery selectors nor the Istio discovery selectors will be used when `overrides` are defined for a particular remote cluster.
+Each remote cluster `overrides` section completely overrides the default discovery selectors. That is to say, if a remote cluster has discovery selector overrides defined, only those selectors are used to determine which remote namespaces are to be visible to users. The `default` discovery selectors will not be used for a particular remote cluster when `overrides` are defined for that remote cluster.
 {{% /alert %}}
 
 Here is an example of defining discovery selectors for a remote cluster:
@@ -156,7 +156,7 @@ spec:
 
 ## Discovery Selectors
 
-The `default`, `overrides`, and Istio discovery selectors are all processed in the same manner, and all follow the Istio semantics as described in the [Istio discoverySelectors documentation](https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/#MeshConfig) (with one caveat: when `deployment.cluster_wide_access` is `false`, an empty list of discovery selectors does not mean all namespaces will be accessible - only the Istio control plane namespace and the Kiali deployment namespace will be accessible in this case).
+The `default` and `overrides` discovery selectors are processed in the same manner. They follow the same semantics as Istio as described in the [Istio discoverySelectors documentation](https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/#MeshConfig) (with one caveat: when `deployment.cluster_wide_access` is `false`, an empty list of discovery selectors does not mean all namespaces will be accessible - only the Istio control plane namespace and the Kiali deployment namespace will be accessible in this case).
 
 In short, the `default` discovery selectors and each remote cluster `overrides` are lists of equality-based and set-based label selectors, with each item in a list being disjunctive (that is, match results from each selector item in a selector list are OR'ed together).
 

content/en/docs/FAQ/general.md

@@ -277,9 +277,11 @@ See [here](https://github.com/kiali/kiali/blob/master/LICENSE) for the Kiali lic
 
 ### Why isn't my namespace in the Namespace Selection dropdown?
 
-Kiali can be told to restrict the namespaces it has access to via the Kiali CR `spec.deployment.discovery_selectors` field. If there are no discovery selectors defined, Kiali will default to using the Istio MeshConfig `discoverySelectors`. If a namespace is not matched to those discovery selectors, it will not be visible in the Namespace Selection dropdown. See the [Namespace Management]({{< ref "/docs/configuration/namespace-management" >}}) guide for more information.
+Kiali can be told to restrict the namespaces users can see via the Kiali CR `spec.deployment.discovery_selectors` field. If there are no discovery selectors defined, Kiali will allow all namespaces _unless_ `deployment.cluster_wide_access` is false, in which case only Kiali's own namespace and the Istio control plane namespace will be accessible. If a namespace does not match one of the discovery selectors defined in the Kiali CR `spec.deployment.discovery_selectors` field at the time Kiali is installed by the operator it will not be visible in the Namespace Selection dropdown; if a new namespace is created after Kiali is installed and that namespace matches one of the discovery selectors, it will only be visible in the Namespace Selection dropdown after the operator creates the necessary Roles for the Kiali Server and restarts the Kiali Server pod (see [Operator Namespace Watching]({{< ref "/docs/configuration/namespace-management#operator-namespace-watching" >}})). See the [Namespace Management]({{< ref "/docs/configuration/namespace-management" >}}) documentation for more information.
 
-Kiali also [caches namespaces](/docs/configuration/kialis.kiali.io/#.spec.kubernetes_config.cache_token_namespace_duration) by default for [10 seconds](https://github.com/kiali/kiali-operator/blob/v1.88.0/crd-docs/cr/kiali.io_v1alpha1_kiali.yaml#L447). Therefore, it might take up to the number of sections specified by `spec.kubernetes_config.cache_token_namespace_duration` in order for a newly added namespace to be seen by Kiali.
+Note that Istio has its own set of optional discovery selectors that can be configured in the Istio MeshConfig `discoverySelectors` field, but these Istio discovery selectors are ignored by Kiali.
+
+Kiali also [caches namespaces](/docs/configuration/kialis.kiali.io/#.spec.kubernetes_config.cache_token_namespace_duration) by default for [10 seconds](https://github.com/kiali/kiali-operator/blob/v1.88.0/crd-docs/cr/kiali.io_v1alpha1_kiali.yaml#L447). Therefore, it might take up to the number of seconds specified by `spec.kubernetes_config.cache_token_namespace_duration` in order for a newly added namespace to be seen by Kiali.
 
 ### Workload "is not found as" messages