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.

Do not mount secrets that you define in a devfile.

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:

      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
      ...
    • The following example shows how to mount the secret as a file by including the <url>/mount-as: file annotation:

      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:
      ...
    • To define the default behavior for mounting secrets, use the /automount-workspace-secret annotation. Developers can override this default in a devfile. This annotation takes a boolean value:

      • 'true' enables automatic mounting into all workspace containers.

      • 'false' disables automatic mounting into all workspace containers. To mount a secret, a user must request it in the devfile component by 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:
        ...
    • The following example shows how to mount the settings.xml file at the /home/user/.m2/ path of all workspace containers:

      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>
      The data of the Kubernetes secret can contain several items. The names of these items must match the desired file name mounted into the container.
    • To override the mount path of the secret for a workspace component, edit the devfile as follows:

  2. Declare a component alias for the containers in the override path.

  3. Declare an additional volume for the component.

  4. Use the name of the secret as the name of the volume.

  5. Provide the new mount path for the secret as containerPath.

    See the following example:

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

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 or OpenShift project 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:

      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
      ...
  • The following example shows how to mount the secret as an environment variable by including the <url>/mount-as: env annotation:

    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

    In this example, the FOO_ENV environment variable and myvalue key value are provisioned into all workspace containers as follows:

    • The secret’s environment variable, env-name, is declared as FOO_ENV in the annotations.

    • The automount-workspace-secret annotation with a boolean value defines the default secret mounting behavior (that can be overridden in a devfile):

      • 'true' enables automatic mounting into all workspace containers.

      • 'false' disables the mounting process until it is explicitly requested in a devfile component using the automountWorkspaceSecrets:true property.

  • If the secret has more than one data key, declare an environment variable name using a <key>_env-name annotation for each data key, as shown in the following example. In this example, you provision the myvalue and othervalue data key values, and the environment variable names, FOO_ENV and OTHER_ENV, into all workspace containers.

    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
  • The maximum length of an annotation name in a Kubernetes secret is 63 characters, of which 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.