Mounting a secret as a file or an environment variable into a Eclipse Che container

Secrets are Kubernetes or OpenShift objects that store sensitive data such as user names, passwords, authentication tokens, and configurations in an encrypted form.

Users can mount a Kubernetes or OpenShift secret that contains sensitive data in a Eclipse Che container 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 as a file into a Eclipse Che container

Prerequisites
  • A running instance of Che. To install an instance of Che, see Installing Che.

Procedure
  1. Create a new Kubernetes or OpenShift secret in the Kubernetes or OpenShift namespace where a Che is deployed. The labels of the secret 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>-secret

Where <DEPLOYMENT_NAME> is one of the following deployments: postgres, keycloak, devfile-registry, plugin-registry or che

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

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

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

  • che.eclipse.org/mount-path: <FOO_ENV> - to provide a required mount path

apiVersion: v1
kind: Secret
metadata:
  name: custom-certificate
  annotations:
    che.eclipse.org/mount-path: /custom-certificates
    che.eclipse.org/mount-as: file
  labels:
...

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

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

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

Mounting a secret as an environment variable into a Eclipse Che container

Prerequisites
  • A running instance of Eclipse Che. To install an instance of Eclipse Che, see Installing Che.

Procedure
  1. Create a new Kubernetes or OpenShift secret in the Kubernetes or OpenShift namespace where a Che is deployed. The labels of the secret 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>-secret

Where <DEPLOYMENT_NAME> is one of the following deployments: postgres, keycloak, devfile-registry, plugin-registry or che

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

Annotations must indicate that the given secret is mounted as a environment variable. Configure the annotation values:

  • che.eclipse.org/mount-as: env - to indicate that a secret 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 secret key value

apiVersion: v1
kind: Secret
metadata:
  name: custom-settings
  annotations:
    che.eclipse.org/env-name: FOO_ENV
    che.eclipse.org/mount-as: env
  labels:
   ...
data:
  mykey: myvalue

This results in the environment variable named FOO_ENV and the value myvalue being provisioned into a Che container.

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

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:
   ...
data:
  mykey: myvalue
  otherkey: othervalue

This results in two environment variables with names FOO_ENV, OTHER_ENV, and values myvalue and othervalue, being provisioned into a Che container.

The maximum length of annotation names in a Kubernetes secret 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 secret.