Merge pull request #1331 from eclipse/che-16764

Change docs according self-signed certificate flag automation

src/main/_config.yml

@@ -54,7 +54,7 @@ asciidoc_attributes: &asciidoc_attributes
   prod-cli: chectl
   orch-cli: kubectl
   prod-checluster: eclipse-che
-  prod-namespace: default
+  prod-namespace: che
   prod-url: http(s)://che-host:che-port
   prod-url-secure: http(s)://che-che
   prod-host: che-host

src/main/pages/che-7/installation-guide/assembly_installing-che-in-tls-mode-with-self-signed-certificates.adoc

@@ -16,30 +16,27 @@ summary:
 
 :context: installing-{prod-id-short}-in-tls-mode-with-self-signed-certificates
 
-WARNING: This guide is for development only. Do not use self-signed certificates in production.
+The following section describes the deployment and configuration of {prod-short} with self-signed certificates. Self-signed certificates are certificates that are not signed by a commonly trusted certificate authority (CA), but instead signed by a locally created CA. Self-signed certificates are not trusted by default. For example, when a website owner uses a self-signed certificate to provide HTTPS services, users who visit that website see a warning in their browser.
 
-The following section describes the deployment and configuration of {prod} for use in TLS mode with self-signed certificates. It consists of following steps:
+WARNING: Self-signed certificates are usually used in development and evaluation environments. Use in production environments is not recommended.
 
-. link:{site-baseurl}che-7/installing-che-in-tls-mode-with-self-signed-certificates/#generating-self-signed-certificates_installing-che-in-tls-mode-with-self-signed-certificates[Generate needed keys and certificates if needed]
+ifeval::["{project-context}" == "che"]
+{prod-short} can be deployed on:
 
-. Prepare target deployment environment (one of the following):
-+
-* link:{site-baseurl}che-7/installing-che-in-tls-mode-with-self-signed-certificates/#deploying-{prod-id-short}-with-self-signed-tls-on-kubernetes_installing-{prod-id-short}-in-tls-mode-with-self-signed-certificates[Minikube] (Kubernetes)
+ * Kubernetes-family infrastructures
+ * OpenShift-family infrastructures
+endif::[]
 
-* link:{site-baseurl}che-7/installing-{prod-id-short}-in-tls-mode-with-self-signed-certificates/#deploying-{prod-id-short}-with-self-signed-tls-on-openshift3-using-operator_installing-{prod-id-short}-in-tls-mode-with-self-signed-certificates[Minishift] (OpenShift 3)
+include::proc_generating-self-signed-tls-certificates.adoc[leveloffset=+1]
 
-* link:{site-baseurl}che-7/installing-che-in-tls-mode-with-self-signed-certificates/#deploying-{prod-id-short}-with-self-signed-tls-on-openshift4-using-operator_installing-{prod-id-short}-in-tls-mode-with-self-signed-certificates[CodeReady Containers] (OpenShift 4)
+ifeval::["{project-context}" == "che"]
+include::proc_deploying-che-with-self-signed-tls-certificates-on-kubernetes.adoc[leveloffset=+1]
+endif::[]
 
-. link:{site-baseurl}che-7/installing-che-in-tls-mode-with-self-signed-certificates/#using-{prod-id-short}-with-tls_installing-{prod-id-short}-in-tls-mode-with-self-signed-certificates[Configure the browser]
+include::proc_deploying-che-with-self-signed-tls-certificates-on-openhift-4.adoc[leveloffset=+1]
 
-include::proc_deploying-che-with-self-signed-tls-on-openhift4-using-operator.adoc[leveloffset=+1]
+include::proc_deploying-che-with-self-signed-tls-certificates-on-openhift-3.adoc[leveloffset=+1]
 
-include::proc_deploying-che-with-self-signed-tls-on-kubernetes.adoc[leveloffset=+1]
-
-include::proc_deploying-che-with-self-signed-tls-on-openhift3-using-operator.adoc[leveloffset=+1]
-
-include::proc_generating-self-signed-certificates.adoc[leveloffset=+1]
-
-include::proc_using-che-with-tls.adoc[leveloffset=+1]
+include::proc_importing-self-signed-tls-certificates-to-browsers.adoc[leveloffset=+1]
 
 :context: {parent-context-of-installing-che-in-tls-mode-with-self-signed-certificates}

src/main/pages/che-7/installation-guide/proc_deploying-che-with-self-signed-tls-certificates-on-kubernetes.adoc

@@ -0,0 +1,64 @@
+// Module included in the following assemblies:
+//
+// installing-{prod-id-short}-in-tls-mode-with-self-signed-certificates
+
+[id="deploying-{prod-id-short}-with-self-signed-tls-certificates-on-kubernetes_{context}"]
+= Deploying {prod-short} with self-signed TLS certificates on Kubernetes
+
+This section describes how to deploy {prod-short} on Kubernetes (including Minikube) with self-signed TLS certificates.
+
+By default, {prod-short} is deployed on Kubernetes infratructures with a self-signed certificate that is generated automatically during the {prod-short} installation process. There are no additional prerequisites for the deployment.
+
+To deploy {prod-short} with a self-signed certificate generated by the user, create a namespace for {prod-short} before the deployment and  two secrets in it:
+
+* The TLS secret: `che-tls`, which holds the server TLS certificate and key (using the `tls.crt` and `tls.key` files). This secret is signed by the self-signed CA certificate. `che-tls` is the default name of the {prod-short} server TLS secret. This can be changed in the configuration.
+
+* The public part of the self-signed CA certificate: `self-signed-certificate`, an opaque secret (based on the `ca.crt` key).
+
+To deploy {prod-short} with a commonly trusted TLS certificate, it is required to create a single `che-tls` secret in the corresponding namespace.
+
+WARNING: When intending to use a commonly trusted TLS certificate for the {prod-short} deployment, do not create the `self-signed-certificate` secret. {prod-short} detects that data from the `che-tls` secret does not match and replaces both secrets with autogenerated data.
+
+
+.Prerequisites
+
+* A running Kubernetes instance, version 1.9 or higher.
+* All required keys and certificates. See xref:generating-self-signed-tls-certificates_{context}[].
+
+
+.Procedure
+
+. Pre-create a namespace for {prod-short}:
++
+[subs="+quotes,attributes"]
+----
+$ kubectl create namespace {prod-namespace}
+----
+
+. Create a secret with the domain key and the certificate:
++
+[subs="+quotes,attributes"]
+----
+$ kubectl create secret tls che-tls --key=domain.key --cert=domain.crt -n {prod-namespace}
+----
+
+. Create a secret from the CA certificate:
++
+[subs="+quotes,attributes"]
+----
+$ kubectl create secret generic self-signed-certificate --from-file=ca.crt -n {prod-namespace}
+----
+
+. Deploy {prod-short} using `{prod-cli}`:
++
+[subs="+quotes,attributes"]
+----
+$ {prod-cli} server:start --platform=k8s
+----
++
+When using Minikube, substitute `k8s` in the above command with `minikube`.
+
+
+.Additional resources
+
+* xref:importing-self-signed-tls-certificates-to-browsers_{context}[]

src/main/pages/che-7/installation-guide/proc_deploying-che-with-self-signed-tls-certificates-on-openhift-3.adoc

@@ -0,0 +1,66 @@
+// Module included in the following assemblies:
+//
+// installing-{prod-id-short}-in-tls-mode-with-self-signed-certificates
+
+[id="deploying-{prod-id-short}-with-self-signed-tls-certificates-on-openshift-3_{context}"]
+= Deploying {prod-short} with self-signed TLS certificates on OpenShift 3
+
+This section describes how to deploy {prod-short} with self-signed TLS certificates generated by the user on the OpenShift 3 platform.
+
+NOTE: This method involves reconfiguration of OpenShift router to use user-provided TLS certificates.
+
+
+.Prerequisites
+
+* A running OpenShift 3 instance, version 3.11 or higher.
+* All required keys and certificates. See xref:generating-self-signed-tls-certificates_{context}[].
+
+
+.Procedure
+
+. Log in to the default OpenShift project:
++
+----
+$ oc login -u system:admin --insecure-skip-tls-verify=true
+$ oc project default
+----
+
+. Reconfigure the router with the generated certificate:
++
+[subs="+quotes,+attributes"]
+----
+$ oc delete secret router-certs
+$ cat domain.crt domain.key > openshift.crt
+$ oc create secret tls router-certs --key=domain.key --cert=openshift.crt
+$ oc rollout latest router
+----
+
+. Create a namespace for {prod-short}:
++
+[subs="+quotes,+attributes"]
+----
+$ oc create namespace {prod-namespace}
+----
+
+. Create a secret from the CA certificate:
++
+[subs="+quotes,+attributes"]
+----
+$ oc create secret generic self-signed-certificate --from-file=ca.crt -n={prod-namespace}
+----
+
+. Deploy {prod-short} using `{prod-cli}`. {prod} is installed with TLS mode by default:
++
+[subs="+quotes,+attributes"]
+----
+$ {prod-cli} server:start --platform=openshift --installer=operator
+----
+ifeval::["{project-context}" == "che"]
++
+When using Minishift, substitute `openshift` in the above command with `minishift`.
+endif::[]
+
+
+.Additional resources
+
+* xref:importing-self-signed-tls-certificates-to-browsers_{context}[]

src/main/pages/che-7/installation-guide/proc_deploying-che-with-self-signed-tls-certificates-on-openhift-4.adoc

@@ -0,0 +1,62 @@
+// Module included in the following assemblies:
+//
+// installing-{prod-id-short}-in-tls-mode-with-self-signed-certificates
+
+[id="deploying-{prod-id-short}-with-self-signed-tls-certificates-on-openshift-4_{context}"]
+= Deploying {prod-short} with self-signed TLS certificates on OpenShift 4
+
+This section describes how to deploy {prod-short} with self-signed TLS certificates on a local OpenShift 4 cluster.
+
+{prod-short} uses a default router certificate to secure its endpoints. Therefore, it depends on the OpenShift cluster configuration whether a self-signed certificate is used or not. {prod-short} automatically detects if the OpenShift default router uses a self-signed certificate by analyzing its certificate chain.
+
+
+.Prerequisites
+
+* A running OpenShift 4 instance, version 4.2 or higher.
+* All required keys and certificates. See xref:generating-self-signed-tls-certificates_{context}[].
+
+
+.Procedure
+
+. Log in to the default OpenShift project:
++
+[subs="+quotes"]
+----
+$ oc login -u _<username> -p _<password>_
+----
+
+. Get the OpenShift 4 self-signed certificate:
++
+[subs="+quotes"]
+----
+$ oc get secret router-ca -n openshift-ingress-operator -o jsonpath="{.data.tls\.crt}" | \
+  base64 -d > ca.crt
+----
+
+. Pre-create a namespace for {prod-short}:
++
+[subs="+quotes"]
+----
+$ oc create namespace {prod-namespace}
+----
+
+. Create a secret from the CA certificate:
++
+[subs="+quotes"]
+----
+$ oc create secret generic self-signed-certificate --from-file=ca.crt -n={prod-namespace}
+----
+
+. Deploy {prod-short} using `{prod-cli}`:
++
+[subs="+quotes,+attributes"]
+----
+$ {prod-cli} server:start --platform=openshift --installer=operator
+----
++
+When using CodeReady Containers, substitute `openshift` in the above command with `crc`.
+
+
+.Additional resources
+
+* xref:importing-self-signed-tls-certificates-to-browsers_{context}[]