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 a 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 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 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 a 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 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 a 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 a 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 a Che container visible, re-create the Secret or the ConfigMap object entirely.
Additional resources