Skip to content

Commit

Permalink
Update import additional CA certificates chapter
Browse files Browse the repository at this point in the history 
Signed-off-by: Mykola Morhun <mmorhun@redhat.com>
  • Loading branch information
@mmorhun
mmorhun committed Dec 4, 2020
1 parent c1921c5 commit 8c17e5b
Showing 1 changed file with 69 additions and 115 deletions.
184 changes: 69 additions & 115 deletions modules/installation-guide/partials/proc_importing-untrusted-tls-certificates.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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]
====
Expand All @@ -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=__<certificate-file-path>__ -n=__<{project-context}-namespace-name>__
$ {orch-cli} create configmap custom-certs --from-file=__<bundle-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.
To apply more than one bundle, add another `--from-file=_<bundle-file-path>_` 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 __<config-map-name>__ --from-file=__<certificate-file-path>__ -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=_<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]
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": "<config-map-name>"}]'
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.
Expand All @@ -149,42 +121,27 @@ $ helm upgrade che -n che --set global.tls.serverTrustStoreConfigMapName=<config
----
+
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]
----
$ 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 __<name>__ -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]
----
Expand All @@ -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:
Expand Down Expand Up @@ -237,31 +191,31 @@ 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 __<workspace namespace>__ | 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]
----
$ {orch-cli} get -o json pod __<workspace pod name>__ -n __<workspace namespace>__ | \
jq -r '.spec.containers[] | select(.name | startswith("theia-ide")).name'
----

- Look for a `ca-certs` ConfigMap that should have been created inside the workspace namespace:
- Look for a `ca-certs` config map that should have been created inside the workspace namespace:
+
[subs="+attributes,+quotes",options="nowrap",role=white-space-pre]
----
$ {orch-cli} get cm ca-certs __<workspace namespace>__
----

- 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 __<workspace namespace>__ -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]
----
Expand Down Expand Up @@ -289,12 +243,12 @@ $ {orch-cli} get -o json pod __<workspace pod name>__ -n __<workspace namespace>
}
----

- 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 __<workspace pod name>__ -c __<theia ide container name>__ -n __<workspace namespace>__ -- ls /public-certs
ca-bundle.crt
manually-added-certificate.crt
source-config-map-name.data-key.crt
----
+

0 comments on commit 8c17e5b

Please sign in to comment.