Mount Secrets

Mount Kubernetes Secrets into workspace containers to provide sensitive configuration data such as credentials, API keys, and certificates.

Prerequisites

You have an active kubectl session with your namespace. See Overview of kubectl.

By default, applying a Secret with the controller.devfile.io/mount-to-devworkspace: 'true' label restarts all running workspaces in the namespace. To mount the Secret only at workspace start and prevent automatic restarts, add the controller.devfile.io/mount-on-start: 'true' annotation.

Procedure

Create a Secret with the required labels and annotations:
```
kind: Secret
apiVersion: v1
metadata:
  name: my-credentials
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-secret: 'true'
  annotations:
    controller.devfile.io/mount-as: file
    controller.devfile.io/mount-path: /etc/my-credentials
type: Opaque
data:
  api-key: <base64_encoded_api_key>
```
where:

controller.devfile.io/mount-to-devworkspace

Required label to mount the Secret to all workspaces.

controller.devfile.io/watch-secret

Watch the Secret for changes and update mounted files.

controller.devfile.io/mount-as

Mount type: file, subpath, or env.

controller.devfile.io/mount-path

Path where the Secret data is mounted.

Apply the Secret to your namespace:

$ kubectl apply -f my-credentials.yaml -n <your_namespace>

Optional: Add annotations to the Secret to customize the mounting behavior.

Table 1. Secret mounting annotations
Annotation	Description
`controller.devfile.io/mount-path: <path>`	Overrides the default mount path. The default mount path is `/etc/secret/<Secret_name>`.
`controller.devfile.io/mount-as: file`	Each key in the Secret data becomes a file in the mount path directory.
`controller.devfile.io/mount-as: subpath`	Similar to `file`, but uses subPath volumes for better compatibility.
`controller.devfile.io/mount-as: env`	Each key-value pair becomes an environment variable in all workspace containers.
`controller.devfile.io/mount-on-start: 'true'`	When set to `true`, the Secret is mounted only when a workspace starts, not while it is already running. This prevents workspace restarts when the Secret is created.
`controller.devfile.io/mount-to-devworkspace-include:`	Specifies a comma-separated list of `DevWorkspace` name patterns. When set, the Secret is mounted only to workspaces whose names match at least one pattern.
`controller.devfile.io/mount-to-devworkspace-exclude:`	Specifies a comma-separated list of `DevWorkspace` name patterns. When set, the Secret is mounted to all workspaces except those whose names match a pattern.

When both controller.devfile.io/mount-to-devworkspace-include and controller.devfile.io/mount-to-devworkspace-exclude annotations are set, the Secret is mounted only to workspaces that match the include pattern and do not match the exclude pattern.

For example, to mount Secret data as environment variables:

kind: Secret
apiVersion: v1
metadata:
  name: my-env-secret
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-secret: 'true'
  annotations:
    controller.devfile.io/mount-as: env
type: Opaque
stringData:
  DATABASE_URL: postgresql://localhost:5432/mydb
  API_SECRET: my-secret-key

For example, to mount a Maven settings.xml file to the /home/user/.m2/ path using subpath:

kind: Secret
apiVersion: v1
metadata:
  name: maven-settings
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-secret: 'true'
  annotations:
    controller.devfile.io/mount-path: /home/user/.m2/
    controller.devfile.io/mount-as: subpath
type: Opaque
stringData:
  settings.xml: |
    <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    </settings>

After the workspace starts, the /home/user/.m2/settings.xml file is available in the DevWorkspace containers. To use a custom path with Maven, run mvn --settings /home/user/.m2/settings.xml clean install.

Start or restart your workspace to apply the mounted Secret.

Verification

For file or subpath mounts, verify the Secret data is available at the mount path:
```
$ ls /etc/my-credentials
```
For env mounts, verify the environment variables are set:
```
$ echo $DATABASE_URL
```

Additional resources