Mounting a secret as a file or an environment variable into a workspace 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 secret that contains sensitive data in a workspace container. This reapplies the stored data from the secret automatically for every newly created workspace. As a result, the user does not have to provide these credentials and configuration settings manually.

The following section describes how to automatically mount a Kubernetes or OpenShift secret in a workspace container and create permanent mount points for components such as:

  • Maven configuration, the settings.xml file

  • SSH key pairs

  • AWS authorization tokens

  • Git credentials store file

A Kubernetes or OpenShift secret can be mounted into a workspace container as:

  • A file - This creates automatically mounted Maven settings that will be applied to every new workspace with Maven capabilities.

  • An environment variable - This uses SSH key pairs and AWS authorization tokens for automatic authentication.

    SSH key pairs can also be mounted as a file, but this format is primarily aimed at the settings of the Maven configuration.

The mounting process uses the standard Kubernetes or OpenShift mounting mechanism, but it requires additional annotations and labeling for a proper bound of a secret with the required Che workspace container.

Mounting a secret as a file into a workspace container

On Kubernetes or OpenShift older than v1.13 and OpenShift 3.11, secrets mounted as file overrides volume mounts defined in the devfile.

This section describes how to mount a secret from the user’s namespace as a file in single-workspace or multiple-workspace containers of Che.

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 workspace will be created.

    • The labels of the secret that is about to be created must match the set of labels configured in che.workspace.provision.secret.labels property of Che. The default labels are:

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

    • app.kubernetes.io/component: workspace-secret:

      Note that the following example describes variations in the usage of the target-container annotation in versions 7.14 and 7.15 of Eclipse Che.

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

      Annotations must indicate the given secret is mounted as a file, provide the mount path, and, optionally, specify the name of the container in which the secret is mounted. If there is no target-container annotation, the secret will be mounted into all user containers of the Che workspace, but this is applicable only for the Che version 7.14.

      apiVersion: v1
      kind: Secret
      metadata:
        name: mvn-settings-secret
        annotations:
          che.eclipse.org/target-container: maven
          che.eclipse.org/mount-path: /home/user/.m2/
          che.eclipse.org/mount-as: file
        labels:
      ...

      Since the Che version 7.15, the target-container annotation is deprecated and automount-workspace-secret annotation with boolean values is introduced. Its purpose is to define the default secret mounting behavior, with the ability to be overridden in a devfile. The true value enables the automatic mounting into all workspace containers. In contrast, the false value disables the mounting process until it is explicitly requested in a devfile component using the automountWorkspaceSecrets:true property.

      apiVersion: v1
      kind: Secret
      metadata:
        name: mvn-settings-secret
        annotations:
          che.eclipse.org/automount-workspace-secret: 'true'
          che.eclipse.org/mount-path: /home/user/.m2/
          che.eclipse.org/mount-as: file
        labels:
      ...

      Data of 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: mvn-settings-secret
        labels:
          app.kubernetes.io/part-of: che.eclipse.org
          app.kubernetes.io/component: workspace-secret
        annotations:
          che.eclipse.org/automount-workspace-secret: 'true'
          che.eclipse.org/mount-path: /home/user/.m2/
          che.eclipse.org/mount-as: file
      data:
        settings.xml: <base64 encoded data content here>

      This results in a file named settings.xml being mounted at the /home/user/.m2/ path of all workspace containers.

      The secret-s mount path can be overridden for specific components of the workspace using devfile. To change mount path, an additional volume should be declared in a component of the devfile, with name matching overridden secret name, and desired mount path.

      apiVersion: 1.0.0
      metadata:
        ...
      components:
       - type: dockerimage
         alias: maven
         image: maven:3.11
         volumes:
           - name: <secret-name>
             containerPath: /my/new/path
         ...

      Note that for this kind of overrides, components must declare an alias to be able to distinguish containers which belong to them and apply override path exclusively for those containers.

Mounting a secret as an environment variable into a workspace container

The following section describes how to mount a Kubernetes or OpenShift secret from the user’s namespace as an environment variable, or variables, into single-workspace or multiple-workspace containers of Che.

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

Procedure
  1. In the Kubernetes namespace where a Che workspace will be created, generate a new Kubernetes or OpenShift secret .

    • The labels of the secret that is about to be generated must match the set of labels configured in che.workspace.provision.secret.labels property of Che. By default, it is a set of two labels:

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

    • app.kubernetes.io/component: workspace-secret:

      Note that the following example describes variations in the usage of the target-container annotation in versions 7.14 and 7.15 of Eclipse Che.

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

      Annotations must indicate that the given secret is mounted as an environment variable, provides variable names, and optionally, specifies the container name where this mount will be applied. If there is no target-container annotation defined, the secret will be mounted into all user containers of the Che workspace, but this is applicable only for the Che version 7.14.

      apiVersion: v1
      kind: Secret
      metadata:
        name: mvn-settings-secret
        annotations:
          che.eclipse.org/target-container: maven
          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 the maven container.

      Since the Che version 7.15, the target-container annotation is deprecated and automount-workspace-secret annotation with boolean values is introduced. Its purpose is to define the default secret mounting behavior, with the ability to be overridden in a devfile. The true value enables automatic mounting into all workspace containers. In contrast, the false value disables the mounting process until it is explicitly requested in a devfile component using the automountWorkspaceSecrets:true property.

      apiVersion: v1
      kind: Secret
      metadata:
        name: mvn-settings-secret
        annotations:
          che.eclipse.org/automount-workspace-secret: 'true'
          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 all workspace containers.

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

      apiVersion: v1
      kind: Secret
      metadata:
        name: mvn-settings-secret
        annotations:
          che.eclipse.org/automount-workspace-secret: 'true'
          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 all workspace containers.

      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.

Mounting a git credentials store into a workspace container

This section describes how to mount git credentials store as secret from the user’s namespace into the file in single-workspace or multiple-workspace containers of Che.

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

Procedure
  1. Prepare git credential file in the Storage format.

  2. Encode content of the file to the base64 format.

  3. Create a new Kubernetes or OpenShift secret in the Kubernetes or OpenShift namespace where a Che workspace will be created.

    • The labels of the secret that is about to be created must match the set of labels configured in che.workspace.provision.secret.labels property of Che. The default labels are:

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

    • app.kubernetes.io/component: workspace-secret:

      Example:
      apiVersion: v1
      kind: Secret
      metadata:
        name: git-credentials-secret
        labels:
          app.kubernetes.io/part-of: che.eclipse.org
          app.kubernetes.io/component: workspace-secret
        annotations:
          che.eclipse.org/automount-workspace-secret: 'true'
          che.eclipse.org/mount-path: /home/theia/.git-credentials
          che.eclipse.org/mount-as: file
          che.eclipse.org/git-credential: 'true'
      data:
        credentials: aHR0cHM6Ly91c2VyOnBhc3NAZXhhbXBsZS5jb20K

      Content of the credential field has to be bas64 encoded to avoid collision with special characters in password. This results in a file named credentials being mounted at the /home/theia/.git-credentials path of all workspace containers. Also, the system configuration of git would be linked to the mounted file.

The use of annotations in the process of mounting a secret into a workspace container

Kubernetes annotations and labels are tools used by libraries, tools, and other clients, to attach arbitrary non-identifying metadata to Kubernetes or OpenShift native objects.

Labels select objects and connect them to a collection that satisfies certain conditions, where annotations are used for non-identifying information that is not used by Kubernetes or OpenShift objects internally.

This section describes Kubernetes or OpenShift annotation values used in the process of Kubernetes or OpenShift secret mounting in a Che workspace.

Annotations must contain items that help identify the proper mounting configuration. These items are:

  • che.eclipse.org/target-container: Valid till the version 7.14. The name of the mounting container. If the name is not defined, the secret mounts into all user’s containers of the Che workspace.

  • che.eclipse.org/automount-workspace-secret: Introduced in the version 7.15. The main mount selector. When set to true, the secret mounts into all user’s containers of the Che workspace. When set to false, the secret does not mount into containers by default. The value of this attribute can be overridden in devfile components, using the automountWorkspaceSecrets boolean property that gives more flexibility to workspace owners. This property requires an alias to be defined for the component that uses it.

  • che.eclipse.org/env-name: The name of the environment variable that is used to mount a secret.

  • che.eclipse.org/mount-as: Describes if a secret will be mounted as an environmental variable or a file. Options: env or file.

  • che.eclipse.org/<mykeyName>-env-name: FOO_ENV: The name of the environment variable used when data contains multiple items. mykeyName is used as an example.

  • che.eclipse.org/git-credential: 'true': The flag indicates that the secret contains git credential file.