Inject files from Secrets and ConfigMaps into containers

Inject configuration from Kubernetes or OpenShift Secrets and ConfigMaps into workspace containers as files or environment variables, so that workspaces have access to credentials, tokens, and settings without hardcoding them in devfiles.

Secrets are Kubernetes or OpenShift objects that store sensitive data (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.

Inject files from Secrets and ConfigMaps

Prerequisites

A running instance of Eclipse Che.

Procedure

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>
Where:
- <DEPLOYMENT_NAME> is one of the following:
  
  che-dashboard
  
  devfile-registry
  
  plugin-registry
  
  che
- <OBJECT_KIND> is either secret or configmap
Example 1. Secret and ConfigMap with required labels
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 ...

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. Secret and ConfigMap with file-mount annotations

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
...

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. Secret with a data key that maps to a filename

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>

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

Add individual files without replacing directories

Prerequisites

A running instance of Eclipse Che.

Procedure

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>
Where:
- <DEPLOYMENT_NAME> is one of the following:
  
  che-dashboard
  
  devfile-registry
  
  plugin-registry
  
  che
- <OBJECT_KIND> is either secret or configmap
Example 4. Secret and ConfigMap with required labels
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 ...

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. Secret and ConfigMap with subPath annotations

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
...

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. Secret with a data key mounted as subPath

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>

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

Inject environment variables from Secrets and ConfigMaps

Prerequisites

A running instance of Eclipse Che.

Procedure

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>
Where:
- <DEPLOYMENT_NAME> is one of the following:
  
  che-dashboard
  
  devfile-registry
  
  plugin-registry
  
  che
- <OBJECT_KIND> is either secret or configmap
Example 7. Secret and ConfigMap with required labels
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 ...

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. Secret and ConfigMap with environment variable annotations

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

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 and 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. Secret with multiple environment variable mappings

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>

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 and 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