Skip to content

chore: Update importing-untrusted-tls-certificates article #2805

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 22, 2024
Merged

chore: Update importing-untrusted-tls-certificates article #2805

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
89eaf35
chore: Update importing-untrusted-tls-certificates article
tolusha Oct 21, 2024
d66f2c9
Update modules/administration-guide/pages/importing-untrusted-tls-cer…
tolusha Oct 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 17 additions & 66 deletions modules/administration-guide/pages/importing-untrusted-tls-certificates.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,14 +15,15 @@ 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 titled `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 a user's workspace 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 the system-trusted locations, when the 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
Expand All @@ -42,7 +43,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"]
----
Expand All @@ -51,7 +52,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"]
----
Expand All @@ -67,8 +68,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]
----
Expand All @@ -78,85 +79,35 @@ $ {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: __<workspace_namespace>__, 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=__<workspace_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]
----
$ {orch-cli} get pod \
--namespace=__<workspace_namespace>__ \
--selector='controller.devfile.io/devworkspace_name=__<workspace_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=__<workspace_namespace>__ \
--selector='controller.devfile.io/devworkspace_name=__<workspace_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 __<workspace_pod_name>__:
Expand All @@ -170,13 +121,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 __<workspace_pod_name>__ \
--namespace=__<workspace_namespace>__ \
-- cat /public-certs/custom-ca-certificates.custom-ca-certificates.pem
-- cat /public-certs/tls-ca-bundle.pem
----

.Additional resources
Expand Down
Loading