Importing untrusted TLS certificates to Che

Che components communications with external services are encrypted with TLS. They require TLS certificates signed by trusted Certificate Authorities (CA). Therefore, you must import into Che all untrusted CA chains in use by an external service such as:

  • A proxy

  • An identity provider (OIDC)

  • A source code repositories provider (Git)

Che uses labeled ConfigMaps in Che 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 Che 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.

When an OpenShift cluster contains cluster-wide trusted CA certificates added through the cluster-wide-proxy configuration, Che 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

  • An active kubectl session with administrative permissions to the destination Kubernetes cluster. See Overview of kubectl.

  • The eclipse-che namespace exists.

  • For each CA chain to import: the root CA and intermediate certificates, in PEM format, in a ca-cert-for-che-<count>.pem file.

Procedure

  1. Concatenate all CA chains PEM files to import, into the custom-ca-certificates.pem file, and remove the return character that is incompatible with the Java truststore.

    $ cat ca-cert-for-che-*.pem | tr -d '\r' > custom-ca-certificates.pem

  2. Create the custom-ca-certificates ConfigMap with the required TLS certificates:

    $ kubectl create configmap custom-ca-certificates \
    --from-file=custom-ca-certificates.pem \
    --namespace=eclipse-che

  3. Label the custom-ca-certificates ConfigMap:

    $ kubectl label configmap custom-ca-certificates \
    app.kubernetes.io/component=ca-bundle \
    app.kubernetes.io/part-of=che.eclipse.org \
    --namespace=eclipse-che

  4. Deploy Che if it hasn’t been deployed before. Otherwise, wait until the rollout of Che components finishes.

  5. Restart running workspaces for the changes to take effect.

Verification steps

  1. Verify that the ConfigMap contains your custom CA certificates. This command returns CA bundle certificates in PEM format:

    $ kubectl get configmap \
    --namespace=eclipse-che \
    --output='jsonpath={.items[0:].data.custom-ca-certificates\.pem}' \
    --selector=app.kubernetes.io/component=ca-bundle,app.kubernetes.io/part-of=che.eclipse.org

  2. Verify in the Che server logs that the imported certificates count is not null:

    $ kubectl logs deploy/che --namespace=eclipse-che \
    | grep tls-ca-bundle.pem

  3. Start a workspace, get the namespace name in which it has been created: <workspace_namespace>, and wait for the workspace to be started.

  4. Verify that the ca-certs-merged ConfigMap contains your custom CA certificates. This command returns Che CA bundle certificates in PEM format:

    $ kubectl get configmap che-trusted-ca-certs \
    --namespace=<workspace_namespace> \
    --output='jsonpath={.data.tls-ca-bundle\.pem}'

  5. Verify that the workspace pod mounts the ca-certs-merged ConfigMap:

    $ kubectl get pod \
    --namespace=<workspace_namespace> \
    --selector='controller.devfile.io/devworkspace_name=<workspace_name>' \
    --output='jsonpath={.items[0:].spec.volumes[0:].configMap.name}' \
    | grep ca-certs-merged

  6. Get the workspace pod name <workspace_pod_name>:

    $ kubectl get pod \
    --namespace=<workspace_namespace> \
    --selector='controller.devfile.io/devworkspace_name=<workspace_name>' \
    --output='jsonpath={.items[0:].metadata.name}' \

  7. Verify that the workspace container has your custom CA certificates. This command returns Che CA bundle certificates in PEM format:

    $ kubectl exec <workspace_pod_name> \
    --namespace=<workspace_namespace> \
    -- cat /public-certs/tls-ca-bundle.pem
Additional resources