Mounting a Secret or a ConfigMap as a file or an environment variable into a Che container

Secrets are Kubernetes or OpenShift objects that store sensitive data such as:

  • usernames

  • passwords

  • authentication tokens

in an encrypted form.

Users can mount a Kubernetes or OpenShift Secret that contains sensitive data or a ConfigMap that contains configuration in a Che managed containers as:

  • a file

  • an environment variable

The mounting process uses the standard Kubernetes or OpenShift mounting mechanism, but it requires additional annotations and labeling.

Mounting a Secret or a ConfigMap as a file into a Che container

Prerequisites

  • A running instance of Eclipse Che.

Procedure

  1. Create a new Kubernetes or OpenShift Secret or a ConfigMap in the Kubernetes or OpenShift namespace where Che is deployed. The labels of the object that is about to be created must match the set of labels:

    • app.kubernetes.io/part-of: che.eclipse.org

    • app.kubernetes.io/component: <DEPLOYMENT_NAME>-<OBJECT_KIND>

    • The <DEPLOYMENT_NAME> corresponds to the one following deployments:

      • che-dashboard

      • devfile-registry

      • plugin-registry

      • che

        and

    • <OBJECT_KIND> is either:

      • secret

        or

      • configmap

Example 1. Example:
apiVersion: v1
kind: Secret
metadata:
  name: custom-settings
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: che-secret
...

or

apiVersion: v1
kind: ConfigMap
metadata:
  name: custom-settings
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: che-configmap
...

  1. Configure the annotation values. Annotations must indicate that the given object is mounted as a file:

    • che.eclipse.org/mount-as: file - To indicate that a object is mounted as a file.

    • che.eclipse.org/mount-path: <TARGET_PATH> - To provide a required mount path.

Example 2. Example:
apiVersion: v1
kind: Secret
metadata:
  name: custom-data
  annotations:
    che.eclipse.org/mount-as: file
    che.eclipse.org/mount-path: /data
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: che-secret
...

or

apiVersion: v1
kind: ConfigMap
metadata:
  name: custom-data
  annotations:
    che.eclipse.org/mount-as: file
    che.eclipse.org/mount-path: /data
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: che-configmap
...

The Kubernetes object can contain several items whose names must match the desired file name mounted into the container.

Example 3. Example:
apiVersion: v1
kind: Secret
metadata:
  name: custom-data
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: che-secret
  annotations:
    che.eclipse.org/mount-as: file
    che.eclipse.org/mount-path: /data
data:
  ca.crt: <base64 encoded data content here>

or

apiVersion: v1
kind: ConfigMap
metadata:
  name: custom-data
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: che-configmap
  annotations:
    che.eclipse.org/mount-as: file
    che.eclipse.org/mount-path: /data
data:
  ca.crt: <data content here>

This results in a file named ca.crt being mounted at the /data path of the Che container.

To make the changes in the Che container visible, re-create the Secret or the ConfigMap object entirely.
Additional resources

Mounting a Secret or a ConfigMap as a subPath into a Che container

Prerequisites

  • A running instance of Eclipse Che.

Procedure

  1. Create a new Kubernetes or OpenShift Secret or a ConfigMap in the Kubernetes or OpenShift namespace where Che is deployed. The labels of the object that is about to be created must match the set of labels:

    • app.kubernetes.io/part-of: che.eclipse.org

    • app.kubernetes.io/component: <DEPLOYMENT_NAME>-<OBJECT_KIND>

    • The <DEPLOYMENT_NAME> corresponds to the one following deployments:

      • che-dashboard

      • devfile-registry

      • plugin-registry

      • che

        and

    • <OBJECT_KIND> is either:

      • secret

        or

      • configmap

Example 4. Example:
apiVersion: v1
kind: Secret
metadata:
  name: custom-settings
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: che-secret
...

or

apiVersion: v1
kind: ConfigMap
metadata:
  name: custom-settings
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: che-configmap
...

  1. Configure the annotation values. Annotations must indicate that the given object is mounted as a subPath.:

    • che.eclipse.org/mount-as: subpath - To indicate that an object is mounted as a subPath.

    • che.eclipse.org/mount-path: <TARGET_PATH> - To provide a required mount path.

Example 5. Example:
apiVersion: v1
kind: Secret
metadata:
  name: custom-data
  annotations:
    che.eclipse.org/mount-as: subpath
    che.eclipse.org/mount-path: /data
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: che-secret
...

or

apiVersion: v1
kind: ConfigMap
metadata:
  name: custom-data
  annotations:
    che.eclipse.org/mount-as: subpath
    che.eclipse.org/mount-path: /data
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: che-configmap
...

The Kubernetes object can contain several items whose names must match the file name mounted into the container.

Example 6. Example:
apiVersion: v1
kind: Secret
metadata:
  name: custom-data
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: che-secret
  annotations:
    che.eclipse.org/mount-as: subpath
    che.eclipse.org/mount-path: /data
data:
  ca.crt: <base64 encoded data content here>

or

apiVersion: v1
kind: ConfigMap
metadata:
  name: custom-data
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: che-configmap
  annotations:
    che.eclipse.org/mount-as: subpath
    che.eclipse.org/mount-path: /data
data:
  ca.crt: <data content here>

This results in a file named ca.crt being mounted at the /data path of Che container.

To make the changes in a Che container visible, re-create the Secret or the ConfigMap object entirely.
Additional resources

Mounting a Secret or a ConfigMap as an environment variable into Che container

Prerequisites

  • A running instance of Eclipse Che.

Procedure

  1. Create a new Kubernetes or OpenShift Secret or a ConfigMap in the Kubernetes or OpenShift namespace where Che is deployed. The labels of the object that is about to be created must match the set of labels:

    • app.kubernetes.io/part-of: che.eclipse.org

    • app.kubernetes.io/component: <DEPLOYMENT_NAME>-<OBJECT_KIND>

    • The <DEPLOYMENT_NAME> corresponds to the one following deployments:

      • che-dashboard

      • devfile-registry

      • plugin-registry

      • che

        and

    • <OBJECT_KIND> is either:

      • secret

        or

      • configmap

Example 7. Example:
apiVersion: v1
kind: Secret
metadata:
  name: custom-settings
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: che-secret
...

or

apiVersion: v1
kind: ConfigMap
metadata:
  name: custom-settings
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: che-configmap
...

  1. Configure the annotation values. Annotations must indicate that the given object is mounted as an environment variable:

    • che.eclipse.org/mount-as: env - to indicate that a object is mounted as an environment variable

    • che.eclipse.org/env-name: <FOO_ENV> - to provide an environment variable name, which is required to mount a object key value

Example 8. Example:
apiVersion: v1
kind: Secret
metadata:
  name: custom-settings
  annotations:
    che.eclipse.org/env-name: FOO_ENV
    che.eclipse.org/mount-as: env
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: che-secret
data:
  mykey: myvalue

or

apiVersion: v1
kind: ConfigMap
metadata:
  name: custom-settings
  annotations:
    che.eclipse.org/env-name: FOO_ENV
    che.eclipse.org/mount-as: env
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: che-configmap
data:
  mykey: myvalue

This results in two environment variables:

  • FOO_ENV

  • myvalue

being provisioned into the Che container.

If the object provides more than one data item, the environment variable name must be provided for each of the data keys as follows:

Example 9. Example:
apiVersion: v1
kind: Secret
metadata:
  name: custom-settings
  annotations:
    che.eclipse.org/mount-as: env
    che.eclipse.org/mykey_env-name: FOO_ENV
    che.eclipse.org/otherkey_env-name: OTHER_ENV
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: che-secret
stringData:
  mykey: <data_content_here>
  otherkey: <data_content_here>

or

apiVersion: v1
kind: ConfigMap
metadata:
  name: custom-settings
  annotations:
    che.eclipse.org/mount-as: env
    che.eclipse.org/mykey_env-name: FOO_ENV
    che.eclipse.org/otherkey_env-name: OTHER_ENV
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: che-configmap
data:
  mykey: <data content here>
  otherkey: <data content here>

This results in two environment variables:

  • FOO_ENV

  • OTHER_ENV

being provisioned into a Che container.

The maximum length of annotation names in a Kubernetes object is 63 characters, where 9 characters are reserved for a prefix that ends with /. This acts as a restriction for the maximum length of the key that can be used for the object.
To make the changes in the Che container visible, re-create the Secret or the ConfigMap object entirely.
Additional resources