From 8c17e5ba829c16d263e789a2288f25fb3d493a91 Mon Sep 17 00:00:00 2001 From: Mykola Morhun Date: Fri, 4 Dec 2020 12:56:02 +0200 Subject: [PATCH] Update import additional CA certificates chapter Signed-off-by: Mykola Morhun --- ..._importing-untrusted-tls-certificates.adoc | 184 +++++++----------- 1 file changed, 69 insertions(+), 115 deletions(-) diff --git a/modules/installation-guide/partials/proc_importing-untrusted-tls-certificates.adoc b/modules/installation-guide/partials/proc_importing-untrusted-tls-certificates.adoc index 7a8703ca15..1b33b682f0 100644 --- a/modules/installation-guide/partials/proc_importing-untrusted-tls-certificates.adoc +++ b/modules/installation-guide/partials/proc_importing-untrusted-tls-certificates.adoc @@ -3,7 +3,9 @@ [id="importing-untrusted-tls-certificates_{context}"] = Importing untrusted TLS certificates to {prod-short} -Internal communications between {prod-short} components are, by default, encrypted with TLS. Communications of {prod-short} components with external services such as proxies, source code repositories, identity providers may require TLS tool. Those communications require the use of SSL certificates signed by trusted Certificate Authorities. +Internal communications between {prod-short} components are, by default, encrypted with TLS. +Communications of {prod-short} components with external services such as proxies, source code repositories, identity providers may require using of TLS. +Those communications require the use of SSL certificates signed by trusted Certificate Authorities. When the certificates used by {prod-short} components or by an external service are signed by an untrusted CA it can be necessary to import the CA certificate in the {prod-short} installation, so that every {prod-short} component will consider them as signed by a trusted CA. @@ -12,7 +14,8 @@ 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. +{prod-short} uses labeled config maps in {prod-short} namespace as sources for TLS certificates. +The config maps can have arbitrary number of data fields with arbitrary number of certificates each. [NOTE] ==== @@ -22,121 +25,90 @@ endif::[] ifeval::["{project-context}" != "che"] When endif::[] -the cluster contains cluster-wide trusted CA certificates added through the link:https://docs.openshift.com/container-platform/4.4/networking/configuring-a-custom-pki.html#nw-proxy-configure-object_configuring-a-custom-pki[cluster-wide-proxy configuration], {prod-short} Operator detects them and automatically injects them into this ConfigMap: +the cluster contains cluster-wide trusted CA certificates added through the link:https://docs.openshift.com/container-platform/4.4/networking/configuring-a-custom-pki.html#nw-proxy-configure-object_configuring-a-custom-pki[cluster-wide-proxy configuration], {prod-short} Operator detects them and automatically injects them into this config map: -- {prod-short} automatically labels the ConfigMap with the `config.openshift.io/inject-trusted-cabundle="true"` label. -- Based on this annotation, OpenShift automatically injects the cluster-wide trusted CA certificates inside the `ca-bundle.crt` key of ConfigMap +- {prod-short} automatically labels the config map with the `config.openshift.io/inject-trusted-cabundle="true"` label. +- Based on this annotation, OpenShift automatically injects the cluster-wide trusted CA certificates inside the `ca-bundle.crt` key of config map ==== -== At {prod-short} installation time +== Adding new CA certificates into {prod-short} + +This guide can be used before the installations of {prod-short} or when {prod-short} is already installed and running. + +include::example$snip_importing-untrusted-tls-certificates_1.adoc[] .Prerequisites * The `{orch-cli}` tool is available. -* You are ready to create `CheCluster` custom resource. +* Namespace for {prod-short} exists. .Procedure -include::example$snip_importing-untrusted-tls-certificates_1.adoc[] - -. Create a new ConfigMap with the required TLS certificates: +. Create a new config map with the required TLS certificates: + [subs="+attributes,+quotes"] ---- -$ {orch-cli} create configmap ca-certs --from-file=____ -n=__<{project-context}-namespace-name>__ +$ {orch-cli} create configmap custom-certs --from-file=____ -n=__<{project-context}-namespace-name>__ ---- + -To apply more than one certificate, add another `--from-file=__` option to the above command. +To apply more than one bundle, add another `--from-file=__` option to the above command. +Or you may create another config map. -. 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"] +. Label created config maps with both `app.kubernetes.io/part-of=che.eclipse.org` and `app.kubernetes.io/component=ca-bundle` labels: + -==== -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] +[subs="+attributes,+quotes"] ---- ---set global.tls.serverTrustStoreConfigMapName=ca-certs +$ {orch-cli} label configmap custom-certs app.kubernetes.io/part-of=che.eclipse.org -n che && kubectl label configmap custom-certs app.kubernetes.io/component=ca-bundle -n che ---- -==== -endif::[] -== On already-running {prod-short} installations +. Wait until rollout of {prod-short} components finishes. +If there are running workspaces, they should be restarted in order the changes take effect. -.Prerequisites - -* The `{orch-cli}` tool is available. - -* You should first gather the name of the ConfigMap used to import certificates: -+ +[NOTE] ==== -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: +On {prod-short} version below +ifeval::["{project-context}" == "che"] +v7.20.0 +endif::[] +ifeval::["{project-context}" != "che"] +2.5.0 +endif::[] +it is required to 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} get checluster {prod-checluster} -n __<{project-context}-namespace-name>__ -o jsonpath={.spec.server.serverTrustStoreConfigMapName} +$ kubectl rollout restart -n __<{project-context}-namespace-name>__ deployment/{prod-id-short}-operator +$ kubectl rollout restart -n __<{project-context}-namespace-name>__ deployment/{prod-id-short}/keycloak +$ kubectl rollout restart -n __<{project-context}-namespace-name>__ deployment/{prod-id-short} ---- ==== + 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`. -==== +== Adding CA certificates in case of Helm installer -.Procedure +For a {prod-short} link:https://helm.sh/[Helm Chart] deployment only one config map supported. It is reccomended to add the certificates at installation time. -include::example$snip_importing-untrusted-tls-certificates_1.adoc[] +=== At installation time -. Add the required TLS certificates in the ConfigMap: -+ -[subs="+attributes,+quotes"] +The config map should be pre-created in the {prod} installation namespace. +Ensure you override the `global.tls.serverTrustStoreConfigMapName` Helm Chart property with the name of the config map 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] ---- -$ {orch-cli} create configmap ____ --from-file=____ -n=__<{project-context}-namespace-name>__ -o yaml --dry-run | {orch-cli} apply -f - +--set global.tls.serverTrustStoreConfigMapName=custom-certs ---- + -To apply more than one certificate, add another `--from-file=__` 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] +Or, in case of `{prod-cli}` usage, provide a Helm patch `--helm-patch-yaml` parameter that points to an yaml file with: +[subs="+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": ""}]' +global: + tls: + enabled: true + serverTrustStoreConfigMapName: custom-certs ---- -+ -==== -ifeval::["{project-context}" == "che"] -+ -==== -For a {prod-short} link:https://helm.sh/[Helm Chart] deployment: + +=== On already running installations +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. @@ -149,42 +121,27 @@ $ helm upgrade che -n che --set global.tls.serverTrustStoreConfigMapName=_ 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] ----- -$ kubectl rollout restart -n __<{project-context}-namespace-name>__ deployment/{prod-id-short}-operator -$ kubectl rollout restart -n __<{project-context}-namespace-name>__ deployment/{prod-id-short}/keycloak -$ kubectl rollout restart -n __<{project-context}-namespace-name>__ deployment/{prod-id-short} ----- -+ -[NOTE] -==== -Restarting the {prod-short} components is not required anymore on {prod-short} -ifeval::["{project-context}" == "che"] -v7.20.0 endif::[] -ifeval::["{project-context}" != "che"] -2.5.0 -endif::[] -and higher. -==== == Verification at the {prod-short} installation level -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: +If after adding the certificates something does not work as expected, 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 : +- In case of a {prod-short} link:https://docs.openshift.com/container-platform/latest/operators/olm-what-operators-are.html[Operator] deployment, namespace where `CheCluster` located contains labeled config maps with right content: + [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 +$ {orch-cli} get cm --selector=app.kubernetes.io/component=ca-bundle,app.kubernetes.io/part-of=che.eclipse.org -n __<{project-context}-namespace-name>__ ---- + -- {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: +And to check content of config map: +---- +$ {orch-cli} get cm ____ -n __<{project-context}-namespace-name>__ -o yaml +---- + +- {prod-short} Pod Volumes list contains a volume that uses `ca-certs-merged` config map as data-source. +To get the list of Volumes of the {prod-short} Pod: + [subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ---- @@ -203,9 +160,6 @@ $ {orch-cli} exec -t __<{prod-id-short}-pod-name>__ -n __<{project-context}-name [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 truststore contains the certificates. The certificates SHA1 fingerprints are among the list of the SHA1 of the certificates included in the truststore returned by the following command: @@ -237,7 +191,7 @@ SHA1 Fingerprint=3F:DA:BF:E7:A7:A7:90:62:CA:CF:C7:55:0E:1D:7D:05:16:7D:45:60 $ {orch-cli} get pods -o=jsonpath='{.items[0].metadata.name}' -n ____ | grep '^workspace.*' ---- -- Get the name of the theia IDE container in the workspace POD with the following command: +- Get the name of the Theia IDE container in the workspace POD with the following command: + [subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ---- @@ -245,23 +199,23 @@ $ {orch-cli} get -o json pod ____ -n ____ ---- -- Check that the entries in the `ca-certs` config map contain all the additional entries you added in the certificate ConfigMap at the {prod-short} installation level, in addition to the the `ca-bundl.crt` entry which is a reserved one: +- Check that the entries in the `ca-certs` config map contain all the additional entries you added before. In addition it may contain `ca-bundl.crt` entry which is a reserved one: + [subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ---- $ {orch-cli} get cm ca-certs -n ____ -o json | jq -r '.data | keys[]' ca-bundle.crt -manually-added-certificate.crt +source-config-map-name.data-key.crt ---- -- Make sure that the `ca-certs` ConfigMap has been added as a volume in the workspace Pod: +- Make sure that the `ca-certs` config map has been added as a volume in the workspace Pod: + [subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ---- @@ -289,12 +243,12 @@ $ {orch-cli} get -o json pod ____ -n __ } ---- -- Inspect `/public-certs` folder on the Theia IDE container and check that its contents match the list of entries in the `ca-certs` ConfigMap: +- Inspect `/public-certs` folder in the Theia IDE container and check that its contents match the list of entries in the `ca-certs` config map: + [subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ---- $ {orch-cli} exec ____ -c ____ -n ____ -- ls /public-certs ca-bundle.crt -manually-added-certificate.crt +source-config-map-name.data-key.crt ---- +