Update the documentation about importing external certificates

modules/installation-guide/nav.adoc

@@ -40,7 +40,7 @@
 ** xref:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[]
 ** xref:installing-che-using-storage-classes.adoc[]
 ** xref:configuring-storage-types.adoc[]
-** xref:importing-tls-certificates-to-che-server-java-truststore.adoc[]
+** xref:importing-external-or-additional-tls-certificates.adoc[]
 
 * xref:upgrading-che.adoc[]
 

modules/installation-guide/pages/importing-external-or-additional-tls-certificates.adoc

@@ -0,0 +1,7 @@
+[id="importing-external-or-additional-tls-certificates"]
+// = Importing external or additional TLS certificates
+:navtitle: Importing external or additional certificates to {prod-short}
+:keywords: installation-guide, tls, certificate
+:page-aliases: .:importing-external-or-additional-tls-certificates
+
+include::partial$proc_importing-external-or-additional-tls-certificates.adoc[]

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

@@ -30,7 +30,7 @@ The next sections describe some specific user stories.
 
 * xref:configuring-storage-types.adoc[]
 
-* xref:importing-tls-certificates-to-che-server-java-truststore.adoc[]
+* xref:importing-external-or-additional-tls-certificates.adoc[]
 
 
 :context: {parent-context-of-configuring-che}

modules/installation-guide/partials/proc_importing-external-or-additional-tls-certificates.adoc

@@ -0,0 +1,218 @@
+
+
+[id="importing-external-or-additional-tls-certificates_{context}"]
+= Importing external or additional TLS certificates to {prod-short}
+
+Network communications between the components of a {prod-short} installation and the started workspaces, are all secured through the TLS protocol, and thus require the use of trusted certificate authorities. 
+
+In some cases it can be necessary to add TLS certificates to the {prod-short} installation, so that every {prod-short} component will consider them as signed by a trusted CA.
+
+Typical cases that may require this addition are:
+
+* when the underlying Kubernetes cluster uses TLS certificates signed by a CA that is not trusted,
+* when {prod-short} server or workspace components connect to external services such as {identity-provider} or a Git server that use TLS certificates signed by an untrusted CA.
+
+To store those certificates, {prod-short} uses a dedicated ConfigMap. Its default name is `ca-certs` but {prod-short} allows configuring its name.
+On OpenShift, the {prod-short} operator even injects cluster trusted certificates into this ConfigMap automatically.
+
+== At {prod-short} installation time
+
+.Prerequisites
+
+* The `{orch-cli}` tool is available.
+* You are ready to create `CheCluster` custom resource.
+
+.Procedure
+
+. Save the certificates you need to import, to a local file system.
++
+[CAUTION]
+====
+* Certificate files are typically stored as Base64 ASCII files, such as `.pem`, `.crt`, `.ca-bundle`. But, they can also be binary-encoded, for example, as `.cer` files. All Secrets that hold certificate files should use the Base64 ASCII certificate rather than the binary-encoded certificate.
+* {prod-short} already uses some reserved file names to automatically inject certificates into the ConfigMap, so you should avoid using the following reserved file names to save your certificates:
+  ** `ca-bundle.crt`
+  ** `ca.crt`
+====
+
+. Create a new ConfigMap with the required TLS certificates:
++
+[subs="+attributes,+quotes"]
+----
+$ {orch-cli} create configmap ca-certs --from-file=__<certificate-file-path>__ -n=__<{project-context}-namespace-name>__
+----
++
+To apply more than one certificate, add another `--from-file=_<certificate-file-path>_` option to the above command.
+
+. During the installation process, when creating the `CheCluster` custom resource, take care of configuring the right name for the created ConfigMap.
++
+====
+For a {prod-short} link:https://docs.openshift.com/container-platform/latest/operators/olm-what-operators-are.html[Operator] deployment,
+ensure you add the `spec.server.ServerTrustStoreConfigMapName` field with the name of the ConfigMap, to the `CheCluster` Custom Resource you will create during the installation:
+
+[source,yaml,subs="+quotes",options="nowrap",role=white-space-pre]
+----
+spec:
+  server:
+    ...
+    spec.server.ServerTrustStoreConfigMapName: ca-certs
+----
+====
+ifeval::["{project-context}" == "che"]
++
+====
+For a {prod-short} link:https://helm.sh/[Helm Chart] deployment, ensure you override the `global.tls.serverTrustStoreConfigMapName` Helm Chart property with the name of the ConfigMap when installing the {prod-short} Helm Chart. For this you should add the following arguments to the Helm command line:
+[subs="+quotes",options="nowrap",role=white-space-pre]
+----
+--set global.tls.serverTrustStoreConfigMapName=ca-certs
+----
+====
+endif::[]
+
+== On already-running {prod-short} installations
+
+.Prerequisites
+
+* The `{orch-cli}` tool is available.
+
+* You should first define the name of the ConfigMap you will use to import certificates:
++
+====
+On instances of {prod-short} deployed with the {prod-short} link:https://docs.openshift.com/container-platform/latest/operators/olm-what-operators-are.html[Operator],
+retrieve the name of the ConfigMap by reading the `spec.server.ServerTrustStoreConfigMapName` `CheCluster` Custom Resource property:
+
+[subs="+attributes,+quotes",options="nowrap",role=white-space-pre]
+----
+$ get checluster {prod-checluster} -n __<{project-context}-namespace-name>__ -o json-path --jsonpath={.spec.server.serverTrustStoreConfigMapName}
+----
+====
+ifeval::["{project-context}" == "che"]
++
+====
+On instances of {prod-short} deployed with the {prod-short} link:https://helm.sh/[Helm Chart] deployment, retrieve the name of the ConfigMap by reading the `global.tls.serverTrustStoreConfigMapName` property from the Helm Chart:
+
+[subs="+quotes",options="nowrap",role=white-space-pre]
+----
+$ helm get values che --all --output json | jq -r '.global.tls.serverTrustStoreConfigMapName'
+----
+====
+endif::[]
++
+[NOTE]
+====
+If the existing installation did not define any name for the ConfigMap, just use `ca-certs`.
+====
+
+.Procedure
+
+. Save the certificates you need to import, to a local file system.
++
+[CAUTION]
+====
+* Certificate files are typically stored as Base64 ASCII files, such as `.pem`, `.crt`, `.ca-bundle`. But, they can also be binary-encoded, for example, as `.cer` files. All Secrets that hold certificate files should use the Base64 ASCII certificate rather than the binary-encoded certificate.
+* {prod-short} already uses some reserved file names to automatically inject certificates into the ConfigMap, so you should avoid using the following reserved file names to save your certificates:
+  ** `ca-bundle.crt`
+  ** `ca.crt`
+====
+
+. Add the required TLS certificates in the ConfigMap:
++
+[subs="+attributes,+quotes"]
+----
+$ {orch-cli} create configmap __<config-map-name>__ --from-file=__<certificate-file-path>__ -n=__<{project-context}-namespace-name>__ -o yaml --dry-run | {orch-cli} apply -f -
+----
++
+To apply more than one certificate, add another `--from-file=_<certificate-file-path>_` option to the above command.
+
+. Configure the {prod-short} installation to use the ConfigMap:
++
+====
+For a {prod-short} link:https://docs.openshift.com/container-platform/latest/operators/olm-what-operators-are.html[Operators] deployment:
+
+. Edit the `spec.server.ServerTrustStoreConfigMapName` `CheCluster` Custom Resource property to match the name of the ConfigMap:
++
+[subs="+attributes,+quotes",options="nowrap",role=white-space-pre]
+----
+$ {orch-cli} patch checluster {prod-checluster} -n __<{project-context}-namespace-name>__ --type=json -p '[{"op": "replace", "path": "/spec/server/serverTrustStoreConfigMapName", "value": "<config-map-name>"}]'
+----
++
+====
+ifeval::["{project-context}" == "che"]
++
+====
+For a {prod-short} link:https://helm.sh/[Helm Chart] deployment: 
+
+. Clone the https://github.com/eclipse/che[che] project.
+. Go to the `deploy/kubernetes/helm/che` directory.
+. Update the name of the configMap {prod-short} will use, by editing the `global.tls.serverTrustStoreConfigMapName` Helm Chart property to match the created or updated ConfigMap:
++
+[subs="+quotes",options="nowrap",role=white-space-pre]
+----
+$ helm upgrade che -n che --set global.tls.serverTrustStoreConfigMapName=<config-map-name> \
+   --set global.ingressDomain=__<kubernetes-cluster-domain>__ .
+----
++
+When using Minikube to run {prod-short}, substitute _<kubernetes-cluster-domain>_ with `$(minikube ip).nip.io`.
+====
+endif::[]
+
+. Restart the {prod-short} operator, the {prod-short} server and {identity-provider} to load the new certificates:
++
+[subs="+attributes,+quotes",options="nowrap",role=white-space-pre]
+----
+$ {orch-cli} rollout restart -n __<{project-context}-namespace-name>__ deployment/{prod-id-short}-operator
+$ {orch-cli} rollout restart -n __<{project-context}-namespace-name>__ deployment/{prod-id-short}/keycloak
+$ {orch-cli} rollout restart -n __<{project-context}-namespace-name>__ deployment/{prod-id-short}
+----
+
+== Verification 
+
+If you added the certificates without error, the {prod-short} server starts and obtains {identity-provider} configuration over HTTPS. Otherwise here is a list of things to verify: 
+
+- In case of a {prod-short} link:https://docs.openshift.com/container-platform/latest/operators/olm-what-operators-are.html[Operator] deployment, the `CheCluster` attribute `serverTrustStoreConfigMapName` value matches the name of the ConfigMap. Get the value using the following command :
++
+[subs="+attributes,+quotes",options="nowrap",role=white-space-pre]
+----
+$ {orch-cli} get -o json checluster/{prod-checluster} -n __<{project-context}-namespace-name>__ | jq .spec.server.serverTrustStoreConfigMapName
+----
++
+- {prod-short} Pod Volumes list contains one Volume that uses the ConfigMap as data-source. To get the list of Volumes of the {prod-short} Pod:
++
+[subs="+attributes,+quotes",options="nowrap",role=white-space-pre]
+----
+$ {orch-cli} get pod -o json __<{prod-id-short}-pod-name>__ -n __<{project-context}-namespace-name>__ | jq .spec.volumes
+----
++
+- {prod-short} mounts certificates in folder `/public-certs/` of the {prod-short} server container. This command returns the list of files in that folder:
++
+[subs="+attributes,+quotes",options="nowrap",role=white-space-pre]
+----
+$ {orch-cli} exec -t __<{prod-id-short}-pod-name>__ -n __<{project-context}-namespace-name>__ -- ls /public-certs/
+----
++
+- In the {prod-short} server logs there is a line for every certificate added to the Java truststore, including configured {prod-short} certificates.
++
+[subs="+attributes,+quotes",options="nowrap",role=white-space-pre]
+----
+$ {orch-cli} logs __<{prod-id-short}-pod-name>__ -n __<{project-context}-namespace-name>__
+(...)
+Found a custom cert. Adding it to java trust store based on /usr/lib/jvm/java-1.8.0/jre/lib/security/cacerts
+(...)
+----
++
+- ${prod-short} server Java trustore contains the certificates. The certificates SHA1 fingerpints are among the list of the SHA1 of the certificates included in the trustore returned by the following command:
++
+[subs="+attributes,+quotes",options="nowrap",role=white-space-pre]
+----
+$ {orch-cli} exec -t __<{prod-id-short}-pod-name>__ -n {prod-namespace} -- keytool -list -keystore /home/che/cacerts
+Your keystore contains 141 entries
+
+(...)
+----
++
+To get the SHA1 hash of a certificate on the local filesystem:
++
+[subs="+attributes,+quotes",options="nowrap",role=white-space-pre]
+----
+$ openssl x509 -in __<certificate-file-path>__ -fingerprint -noout
+SHA1 Fingerprint=3F:DA:BF:E7:A7:A7:90:62:CA:CF:C7:55:0E:1D:7D:05:16:7D:45:60
+----