diff --git a/modules/administration-guide/pages/importing-untrusted-tls-certificates.adoc b/modules/administration-guide/pages/importing-untrusted-tls-certificates.adoc index 1a928f566c..e940f4ecb0 100644 --- a/modules/administration-guide/pages/importing-untrusted-tls-certificates.adoc +++ b/modules/administration-guide/pages/importing-untrusted-tls-certificates.adoc @@ -15,14 +15,14 @@ Therefore, you must import into {prod-short} all untrusted CA chains in use by a * An identity provider (OIDC) * A source code repositories provider (Git) -{prod-short} uses labeled config maps in {prod-short} {orch-namespace} as sources for TLS certificates. -The config maps can have an arbitrary amount of keys with a random amount of certificates each. +{prod-short} uses labeled ConfigMaps in {prod-short} {orch-namespace} as sources for TLS certificates. +The ConfigMaps can have an arbitrary amount of keys with a random amount of certificates each. Operator merges all ConfigMaps into a single one `ca-certs-merged` and mounts it as a volume in the {prod-short} server, dashboard and workspace pods. By default, the Operator mounts the `ca-certs-merged` ConfigMap in users' workspaces at two locations: `/public-certs` and `/etc/pki/ca-trust/extracted/pem`. The `/etc/pki/ca-trust/extracted/pem` directory is where the system stores extracted CA certificates for trusted certificate authorities on Red Hat (e.g., CentOS, Fedora). CLI tools automatically use certificates from system-trusted locations, when user's workspace is up and running. [NOTE] ==== When an OpenShift cluster contains cluster-wide trusted CA certificates added through the link:https://docs.openshift.com/container-platform/latest/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 a 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 the config map. +{prod-short} Operator detects them and automatically injects them into a 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 the ConfigMap. ==== .Prerequisites @@ -42,7 +42,7 @@ See {orch-cli-link}. $ cat ca-cert-for-{prod-id-short}-*.pem | tr -d '\r' > custom-ca-certificates.pem ---- -. Create the `custom-ca-certificates` config map with the required TLS certificates: +. Create the `custom-ca-certificates` ConfigMap with the required TLS certificates: + [subs="+attributes,+quotes"] ---- @@ -51,7 +51,7 @@ $ {orch-cli} create configmap custom-ca-certificates \ --namespace={prod-namespace} ---- -. Label the `custom-ca-certificates` config map: +. Label the `custom-ca-certificates` ConfigMap: + [subs="+attributes,+quotes"] ---- @@ -67,8 +67,8 @@ Otherwise, wait until the rollout of {prod-short} components finishes. . Restart running workspaces for the changes to take effect. .Verification steps -. Verify that the config map contains your custom CA certificates. -This command returns your custom CA certificates in PEM format: +. Verify that the ConfigMap contains your custom CA certificates. +This command returns CA bundle certificates in PEM format: + [subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ---- @@ -78,66 +78,27 @@ $ {orch-cli} get configmap \ --selector=app.kubernetes.io/component=ca-bundle,app.kubernetes.io/part-of=che.eclipse.org ---- -. Verify {prod-short} pod contains a volume mounting the `ca-certs-merged` config map: -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ {orch-cli} get pod \ - --selector=app.kubernetes.io/component={prod-id-short} \ - --output='jsonpath={.items[0].spec.volumes[0:].configMap.name}' \ - --namespace={prod-namespace} \ - | grep ca-certs-merged ----- - -. Verify the {prod-short} server container has your custom CA certificates. -This command returns your custom CA certificates in PEM format: -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ {orch-cli} exec -t deploy/{prod-id-short} \ - --namespace={prod-namespace} \ - -- cat /public-certs/custom-ca-certificates.pem ----- - . Verify in the {prod-short} server logs that the imported certificates count is not null: + [subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ---- $ {orch-cli} logs deploy/{prod-id-short} --namespace={prod-namespace} \ - | grep custom-ca-certificates.pem ----- - -. List the SHA256 fingerprints of your certificates: -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ for certificate in ca-cert*.pem ; - do openssl x509 -in $certificate -digest -sha256 -fingerprint -noout | cut -d= -f2; - done ----- - -. Verify that {prod-short} server Java truststore contains certificates with the same fingerprint: -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ {orch-cli} exec -t deploy/{prod-id-short} --namespace={prod-namespace} -- \ - keytool -list -keystore {prod-home}/cacerts \ - | grep --after-context=1 custom-ca-certificates.pem + | grep tls-ca-bundle.pem ---- . Start a workspace, get the {orch-namespace} name in which it has been created: ____, and wait for the workspace to be started. -. Verify that the `che-trusted-ca-certs` config map contains your custom CA certificates. -This command returns your custom CA certificates in PEM format: +. Verify that the `ca-certs-merged` ConfigMap contains your custom CA certificates. +This command returns {prod-short} CA bundle certificates in PEM format: + [subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ---- $ {orch-cli} get configmap che-trusted-ca-certs \ --namespace=____ \ - --output='jsonpath={.data.custom-ca-certificates\.custom-ca-certificates\.pem}' + --output='jsonpath={.data.tls-ca-bundle\.pem}' ---- -. Verify that the workspace pod mounts the `che-trusted-ca-certs` config map: +. Verify that the workspace pod mounts the `ca-certs-merged` ConfigMap: + [subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ---- @@ -145,18 +106,7 @@ $ {orch-cli} get pod \ --namespace=____ \ --selector='controller.devfile.io/devworkspace_name=____' \ --output='jsonpath={.items[0:].spec.volumes[0:].configMap.name}' \ - | grep che-trusted-ca-certs ----- - -. Verify that the `universal-developer-image` container (or the container defined in the workspace devfile) mounts the `che-trusted-ca-certs` volume: -+ -[subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ----- -$ {orch-cli} get pod \ - --namespace=____ \ - --selector='controller.devfile.io/devworkspace_name=____' \ - --output='jsonpath={.items[0:].spec.containers[0:]}' \ - | jq 'select (.volumeMounts[].name == "che-trusted-ca-certs") | .name' + | grep ca-certs-merged ---- . Get the workspace pod name ____: @@ -170,13 +120,13 @@ $ {orch-cli} get pod \ ---- . Verify that the workspace container has your custom CA certificates. -This command returns your custom CA certificates in PEM format: +This command returns {prod-short} CA bundle certificates in PEM format: + [subs="+attributes,+quotes",options="nowrap",role=white-space-pre] ---- $ {orch-cli} exec ____ \ --namespace=____ \ - -- cat /public-certs/custom-ca-certificates.custom-ca-certificates.pem + -- cat /public-certs/tls-ca-bundle.pem ---- .Additional resources