fix: Improve language and structure of Switching between external and…

… internal communication (#2110)

* Rewrite inter-component communication procedure

* Improve formatting

* Add verification steps

* Add sentence to the list

* Improve verification, remove helm procedure

* Remove redundant assembly file

* Implement suggestions from peer review

* Fix vale

* Add note about default behavior

* Fix incorrect information

* Fact corrections

* Fact corrections

* Small language change

* Small language change

modules/installation-guide/nav.adoc

@@ -45,7 +45,7 @@
 ** xref:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[]
 ** xref:installing-che-using-storage-classes.adoc[]
 ** xref:importing-untrusted-tls-certificates.adoc[]
-** xref:switching-between-external-and-internal-communication.adoc[]
+** xref:configuring-communication-between-che-components.adoc[]
 ** xref:setting-up-the-keycloak-che-username-readonly-theme-for-the-eclipse-che-login-page.adoc[]
 ** xref:mounting-a-secret-as-a-file-or-an-environment-variable-into-a-container.adoc[]
 ** xref:enabling-dev-workspace-engine.adoc[]

modules/installation-guide/pages/configuring-communication-between-che-components.adoc

@@ -0,0 +1,6 @@
+[id="configuring-communication-between-che-components"]
+:navtitle: Configuring communication between Che components
+:keywords: installation-guide
+:page-aliases: .:configuring-communication-between-che-components, .:switching-between-external-and-internal-communication, switching-between-external-and-internal-communication
+
+include::partial$proc_configuring-communication-between-che-components.adoc[]

modules/installation-guide/partials/assembly_advanced-configuration.adoc

@@ -36,7 +36,7 @@ The next sections describe some specific user stories.
 
 * xref:importing-untrusted-tls-certificates.adoc[]
 
-* xref:switching-between-external-and-internal-communication.adoc[]
+* xref:configuring-communication-between-che-components.adoc[]
 
 * xref:setting-up-the-keycloak-che-username-readonly-theme-for-the-eclipse-che-login-page.adoc[]
 

modules/installation-guide/partials/proc_configuring-communication-between-che-components.adoc

@@ -0,0 +1,65 @@
+[id="configuring-communication-between-{prod-id-short}-components_{context}"]
+= Configuring communication between {prod-short} components
+
+You can select whether {prod-short} components communicate by using the internal network or external {platforms-ingress}. 
+
+By default, {prod-short} components communicate by using the internal network. {prod-short} components use their internal services names, which are exposed in the internal {platforms-name} network.
+
+As the administrator, disable the use of the internal services names to force the {prod-short} components to use external {platforms-ingress} in the following situations:
+
+* To deploy {prod-short} on a cluster where NetworkPolicies restricts communications between namespaces.
+* To deploy {prod-short} with the multitenant network plugin.
+
+[IMPORTANT]
+====
+Using the external {platforms-ingress} might slow the traffic and lead to issues because it uses proxies, certificates, and firewalls.
+====
+
+.Prerequisites
+
+* An instance of {prod-short} running on {platforms-name}.
+
+.Procedure
+
+* In the CheCluster Custom Resource server settings, for the `disableInternalClusterSVCNames` property, set `__<property-value>__` to:
+[horizontal]
+`true`:: To use external {platforms-ingress}.
+`false`:: To use internal {orch-name} DNS names.
+
++
+====
+[source,yaml,subs="+quotes"]
+----
+apiVersion: org.eclipse.che/v1
+kind: CheCluster
+# ...
+spec:
+  server:
+    # ...
+    disableInternalClusterSVCNames: __<property-value>__
+----
+====
+
+.Verification steps
+. Specify {prod-short} as the default project:
++
+[subs="+quotes,attributes"]
+----
+$ {orch-cli} project {prod-namespace}
+----
+. Inspect the ConfigMap properties to determine which communication method {prod-short} uses:
++
+[subs="+quotes,attributes,macros"]
+----
+$ {orch-cli} get configmap che -o \ 
+jsonpath='{.data.pass:[CHE_KEYCLOAK_AUTH__INTERNAL__SERVER__URL]}'
+$ {orch-cli} get configmap che -o \ 
+jsonpath='{.data.pass:[CHE_WORKSPACE_PLUGIN__REGISTRY__INTERNAL__URL]}'
+----
+* If {prod-short} components communicate internally, the output is following:
++
+----
+http://keycloak.eclipse-che.svc:8080/auth
+http://plugin-registry.eclipse-che.svc:8080/v3
+----
+* Otherwise, if the components communicate externally, the output is empty.