Documentation Improvement Request: Multi-Primary Cluster Set-Up and Service Discovery

[JacobAmar]

Describe the feature request
The Istio's documentation for the setup of multi-primary service mesh needs improvement. The current documentation suggests that DNS proxying or admiral is necessary for service discovery on the target clusters. However, actual experience shows that while DNS proxying is needed, auto address allocation is not required for successful service discovery.

The references to this issue are in the following links:

Multi-primary cluster setup
DNS with multiple clusters

Describe alternatives you've considered

The clarification in the documentation is needed to emphasize that DNS proxying is necessary but not the auto address allocation. The documentation should make it clear that service IPs should not overlap, and indicate that Istio automatically creates a service entry for services found in the remote clusters.

Also, adjustments to the documentation for network name specification during the installation of Istio on a flat network would be useful, since the network name wasn't required in the actual process.

In addition, there should be information detailing the remote-secret creation, particularly mentioning how Istio generates the remote secret from the default service account named "istio-reader-service-account". Also, more information about the required RBACs for automating the process of clusters joining the mesh will be beneficial.

Affected product area (please put an X in all that apply)

[ ] Ambient
[ X ] Docs
[ ] Dual Stack
[ ] Installation
[ ] Networking
[ ] Performance and Scalability
[ ] Extensions and Telemetry
[ ] Security
[ ] Test and Release
[ ] User Experience
[ ] Developer Infrastructure

Affected features (please put an X in all that apply)

[ X ] Multi Cluster
[ ] Virtual Machine
[ X ] Multi Control Plane

[howardjohn]

The doc says: "This can also be achieved with Istio ServiceEntry, rather than Kubernetes Service. However, a ServiceEntry does not configure the Kubernetes DNS server. This means that DNS will need to be configured either manually or with automated tooling such as the Address auto allocation feature of Istio DNS Proxying." I agree this is wrong and does not require the auto allocation feature in all cases and should be fixed to explain it is only when spec.address is unset.

The documentation should make it clear that service IPs should not overlap

"Note, however, that for a single network across multiple clusters, services and endpoints cannot have overlapping IP addresses." - this seems to account for this?

and indicate that Istio automatically creates a service entry for services found in the remote clusters.

This is not something Istio does

Also, adjustments to the documentation for network name specification during the installation of Istio on a flat network would be useful, since the network name wasn't required in the actual process.

👍

In addition, there should be information detailing the remote-secret creation, particularly mentioning how Istio generates the remote secret from the default service account named "istio-reader-service-account". Also, more information about the required RBACs for automating the process of clusters joining the mesh will be beneficial.

👍