Chapter 6. Using credentials and configurations in workspaces

You can use your credentials and configurations in your workspaces.

To do so, mount your credentials and configurations to the Dev Workspace containers in the OpenShift cluster of your organization’s OpenShift Dev Spaces instance:

Mount your credentials and sensitive configurations as Kubernetes Secrets.
Mount your non-sensitve configurations as Kubernetes ConfigMaps.

If you need to allow the Dev Workspace Pods in the cluster to access container registries that require authentication, create an image pull Secret for the Dev Workspace Pods.

The mounting process uses the standard Kubernetes mounting mechanism and requires applying additional labels and annotations to your existing resources. Resources are mounted when starting a new workspace or restarting an existing one.

You can create permanent mount points for various components:

Maven configuration, such as the user-specific settings.xml file
SSH key pairs
Git-provider access tokens
AWS authorization tokens
Configuration files
Persistent storage

Additional resources

6.1. Mounting Secrets

To mount confidential data into your workspaces, use Kubernetes Secrets.

Using Kubernetes Secrets, you can mount usernames, passwords, SSH key pairs, authentication tokens (for example, for AWS), and sensitive configurations.

Mount Kubernetes Secrets to the Dev Workspace containers in the OpenShift cluster of your organization’s OpenShift Dev Spaces instance.

Prerequisites

An active oc session with administrative permissions to the destination OpenShift cluster. See Getting started with the CLI.
In your user project, you created a new Secret or determined an existing Secret to mount to all Dev Workspace containers.

Procedure

Add the labels, which are required for mounting the Secret, to the Secret.

$ oc label secret <Secret_name> \
        controller.devfile.io/mount-to-devworkspace=true \
        controller.devfile.io/watch-secret=true

Optional: Use the annotations to configure how the Secret is mounted.

Table 6.1. Optional annotations
Annotation	Description
`controller.devfile.io/mount-path:`	Specifies the mount path. Defaults to `/etc/secret/<Secret_name>`.
`controller.devfile.io/mount-as:`	Specifies how the resource should be mounted: `file`, `subpath`, or `env`. Defaults to `file`. `mount-as: file` mounts the keys and values as files within the mount path. `mount-as: subpath` mounts the keys and values within the mount path using subpath volume mounts. `mount-as: env` mounts the keys and values as environment variables in all `Dev Workspace` containers.

Example 6.1. Mounting a Secret as a file

apiVersion: v1
kind: Secret
metadata:
  name: mvn-settings-secret
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-secret: 'true'
  annotations:
    controller.devfile.io/mount-path: '/home/user/.m2'
data:
  settings.xml: <Base64_encoded_content>

When you start a workspace, the /home/user/.m2/settings.xml file will be available in the Dev Workspace containers.

With Maven, you can set a custom path for the settings.xml file. For example:

$ mvn --settings /home/user/.m2/settings.xml clean install

6.1.1. Creating image pull Secrets

To allow the Dev Workspace Pods in the OpenShift cluster of your organization’s OpenShift Dev Spaces instance to access container registries that require authentication, create an image pull Secret.

You can create image pull Secrets by using oc or a .dockercfg file or a config.json file.

6.1.1.1. Creating an image pull Secret with `oc`

Prerequisites

An active oc session with administrative permissions to the destination OpenShift cluster. See Getting started with the CLI.

Procedure

In your user project, create an image pull Secret with your private container registry details and credentials:

$ oc create secret docker-registry <Secret_name> \
    --docker-server=<registry_server> \
    --docker-username=<username> \
    --docker-password=<password> \
    --docker-email=<email_address>

Add the following label to the image pull Secret:

$ oc label secret <Secret_name> controller.devfile.io/devworkspace_pullsecret=true controller.devfile.io/watch-secret=true

6.1.1.2. Creating an image pull Secret from a `.dockercfg` file

If you already store the credentials for the private container registry in a .dockercfg file, you can use that file to create an image pull Secret.

Prerequisites

An active oc session with administrative permissions to the destination OpenShift cluster. See Getting started with the CLI.
base64 command line tools are installed in the operating system you are using.

Procedure

Encode the .dockercfg file to Base64:
```
$ cat .dockercfg | base64 | tr -d '\n'
```

Create a new OpenShift Secret in your user project:

apiVersion: v1
kind: Secret
metadata:
  name: <Secret_name>
  labels:
    controller.devfile.io/devworkspace_pullsecret: 'true'
    controller.devfile.io/watch-secret: 'true'
data:
  .dockercfg: <Base64_content_of_.dockercfg>
type: kubernetes.io/dockercfg

Apply the Secret:

$ oc apply -f - <<EOF
<Secret_prepared_in_the_previous_step>
EOF

6.1.1.3. Creating an image pull Secret from a `config.json` file

If you already store the credentials for the private container registry in a $HOME/.docker/config.json file, you can use that file to create an image pull Secret.

Prerequisites

An active oc session with administrative permissions to the destination OpenShift cluster. See Getting started with the CLI.
base64 command line tools are installed in the operating system you are using.

Procedure

Encode the $HOME/.docker/config.json file to Base64.
```
$ cat config.json | base64 | tr -d '\n'
```

Create a new OpenShift Secret in your user project:

apiVersion: v1
kind: Secret
metadata:
  name: <Secret_name>
  labels:
    controller.devfile.io/devworkspace_pullsecret: 'true'
    controller.devfile.io/watch-secret: 'true'
data:
  .dockerconfigjson: <Base64_content_of_config.json>
type: kubernetes.io/dockerconfigjson

Apply the Secret:

$ oc apply -f - <<EOF
<Secret_prepared_in_the_previous_step>
EOF

6.1.2. Using a Git-provider access token

OAuth for GitHub, GitLab, or Bitbucket needs to be configured by the administrator of your organization’s OpenShift Dev Spaces instance. If your administrator could not configure it for OpenShift Dev Spaces users, the workaround is for you to apply your personal access token as a Kubernetes Secret.

Mounting your access token as a Secret enables the OpenShift Dev Spaces Server to access the remote repository that is cloned during workspace creation, including access to the repository’s /.che and /.vscode folders.

Apply the Secret in your user project of the OpenShift cluster of your organization’s OpenShift Dev Spaces instance.

After applying the Secret, you can create new workspaces from a private GitHub, GitLab, or Bitbucket-server repository.

You can create and apply multiple access-token Secrets per a Git provider. You must apply each of those Secrets in your user project.

Prerequisites

You have cluster administrator permissions for the cluster on which your organization’s OpenShift Dev Spaces instance is running.
You have logged in to the cluster.
Tip
On OpenShift, you can use the oc command-line tool to log in to the cluster:
$ oc login "https://devspaces-<openshift_deployment_name>.<domain_name>" --username=<my_user>

Procedure

Generate your access token on your Git provider’s website.
Encode your access token to Base64.
Tip
If you have the base64 command-line tools installed in the operating system, you can use the command line:
$ echo -n '<your_access_token_string>' | base64
Visit "https://devspaces-<openshift_deployment_name>.<domain_name>"/api/user in the web browser and copy the id value from the response. This is your OpenShift Dev Spaces user ID.
Get your Git provider user ID by following the Git provider’s API documentation:
- GitHub: Get a user. See the id value in the response.
- GitLab: List users: For normal users, use the username filter: /users?username=:username. See the id value in the response.
- Bitbucket Server: Get users. See the id value in the response.

Prepare a new OpenShift Secret.

kind: Secret
apiVersion: v1
metadata:
  name: personal-access-token-<your_choice_of_name_for_this_token>
  labels:
    app.kubernetes.io/component: scm-personal-access-token
    app.kubernetes.io/part-of: che.eclipse.org
  annotations:
    che.eclipse.org/che-userid: <devspaces_user_id>1
    che.eclipse.org/scm-personal-access-token-name: <git_provider_name>2
    che.eclipse.org/scm-url: <git_provider_endpoint>3
    che.eclipse.org/scm-userid: '<git_provider_user_id>'4
    che.eclipse.org/scm-username: <git_provider_username>
data:
  token: <Base64_encoded_access_token>
type: Opaque

1: Your OpenShift Dev Spaces user ID.
2: The Git provider name: github or gitlab or bitbucket-server.
3: The Git provider URL.
4: Your Git provider user ID.

Visit "https://devspaces-<openshift_deployment_name>.<domain_name>"/api/kubernetes/namespace to get your OpenShift Dev Spaces user namespace as name.
Switch to your OpenShift Dev Spaces user namespace in the cluster.
Tip
On OpenShift:
- The oc command-line tool can return the namespace you are currently on in the cluster, which you can use to check your current namespace:
  $ oc project
- You can switch to your OpenShift Dev Spaces user namespace on a command line if needed:
  $ oc project <your_user_namespace>
Apply the Secret.
Tip
On OpenShift, you can use the oc command-line tool:
```
$ oc apply -f - <<EOF
<Secret_prepared_in_step_5>
EOF
```

Verification

Start a new workspace by using the URL of a remote Git repository that the Git provider hosts.
Make some changes and push to the remote Git repository from the workspace.

6.2. Mounting ConfigMaps

To mount non-confidential configuration data into your workspaces, use Kubernetes ConfigMaps.

Using Kubernetes ConfigMaps, you can mount non-sensitive data such as configuration values for an application.

Mount Kubernetes ConfigMaps to the Dev Workspace containers in the OpenShift cluster of your organization’s OpenShift Dev Spaces instance.

Prerequisites

An active oc session with administrative permissions to the destination OpenShift cluster. See Getting started with the CLI.
In your user project, you created a new ConfigMap or determined an existing ConfigMap to mount to all Dev Workspace containers.

Procedure

Add the labels, which are required for mounting the ConfigMap, to the ConfigMap.

$ oc label configmap <ConfigMap_name> \
        controller.devfile.io/mount-to-devworkspace=true \
        controller.devfile.io/watch-configmap=true

Optional: Use the annotations to configure how the ConfigMap is mounted.

Table 6.2. Optional annotations
Annotation	Description
`controller.devfile.io/mount-path:`	Specifies the mount path. Defaults to `/etc/config/<ConfigMap_name>`.
`controller.devfile.io/mount-as:`	Specifies how the resource should be mounted: `file`, `subpath`, or `env`. Defaults to `file`. `mount-as:file` mounts the keys and values as files within the mount path. `mount-as:subpath` mounts the keys and values within the mount path using subpath volume mounts. `mount-as:env` mounts the keys and values as environment variables in all `Dev Workspace` containers.

Example 6.2. Mounting a ConfigMap as environment variables

kind: ConfigMap
apiVersion: v1
metadata:
  name: my-settings
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-configmap: 'true'
  annotations:
    controller.devfile.io/mount-as: env
data:
  <env_var_1>: <value_1>
  <env_var_2>: <value_2>

When you start a workspace, the <env_var_1> and <env_var_2> environment variables will be available in the Dev Workspace containers.

6.3. Enabling artifact repositories in a restricted environment

By configuring technology stacks, you can work with artifacts from in-house repositories using self-signed certificates:

6.3.1. Maven

You can enable a Maven artifact repository in Maven workspaces that run in a restricted environment.

Prerequisites

You are not running any Maven workspace.
You know your user namespace, which is <username>-devspaces where <username> is your OpenShift Dev Spaces username.

Procedure

In the <username>-devspaces namespace, apply the Secret for the TLS certificate:

kind: Secret
apiVersion: v1
metadata:
  name: tls-cer
  annotations:
    controller.devfile.io/mount-path: /home/user/certs
    controller.devfile.io/mount-as: file
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-secret: 'true'
data:
  tls.cer: >-
    <Base64_encoded_content_of_public_cert> 1

1: Base64 encoding with disabled line wrapping.

In the <username>-devspaces namespace, apply the ConfigMap to create the settings.xml file:

kind: ConfigMap
apiVersion: v1
metadata:
  name: settings-xml
  annotations:
    controller.devfile.io/mount-as: subpath
    controller.devfile.io/mount-path: /home/user/.m2
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-configmap: 'true'
data:
  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">
      <localRepository/>
      <interactiveMode/>
      <offline/>
      <pluginGroups/>
      <servers/>
      <mirrors>
        <mirror>
          <id>redhat-ga-mirror</id>
          <name>Red Hat GA</name>
          <url>https://<maven_artifact_repository_route>/repository/redhat-ga/</url>
          <mirrorOf>redhat-ga</mirrorOf>
        </mirror>
        <mirror>
          <id>maven-central-mirror</id>
          <name>Maven Central</name>
          <url>https://<maven_artifact_repository_route>/repository/maven-central/</url>
          <mirrorOf>maven-central</mirrorOf>
        </mirror>
        <mirror>
          <id>jboss-public-repository-mirror</id>
          <name>JBoss Public Maven Repository</name>
          <url>https://<maven_artifact_repository_route>/repository/jboss-public/</url>
          <mirrorOf>jboss-public-repository</mirrorOf>
        </mirror>
      </mirrors>
      <proxies/>
      <profiles/>
      <activeProfiles/>
    </settings>

Optional: When using EAP-based devfiles, apply a second settings-xml ConfigMap in the <username>-devspaces namespace, and with the same content, a different name, and the /home/jboss/.m2 mount path.

In the <username>-devspaces namespace, apply the ConfigMap for the TrustStore initialization script:

Java 8

kind: ConfigMap
apiVersion: v1
metadata:
  name: init-truststore
  annotations:
    controller.devfile.io/mount-as: subpath
    controller.devfile.io/mount-path: /home/user/
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-configmap: 'true'
data:
  init-java8-truststore.sh: |
    #!/usr/bin/env bash

    keytool -importcert -noprompt -file /home/user/certs/tls.cer -trustcacerts -keystore ~/.java/current/jre/lib/security/cacerts -storepass changeit

Java 11

kind: ConfigMap
apiVersion: v1
metadata:
  name: init-truststore
  annotations:
    controller.devfile.io/mount-as: subpath
    controller.devfile.io/mount-path: /home/user/
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-configmap: 'true'
data:
  init-java11-truststore.sh: |
    #!/usr/bin/env bash

    keytool -importcert -noprompt -file /home/user/certs/tls.cer -cacerts -storepass changeit

Start a Maven workspace.
Open a new terminal in the tools container.
Run ~/init-truststore.sh.

6.3.2. Gradle

You can enable a Gradle artifact repository in Gradle workspaces that run in a restricted environment.

Prerequisites

You are not running any Gradle workspace.

Procedure

Apply the Secret for the TLS certificate:

kind: Secret
apiVersion: v1
metadata:
  name: tls-cer
  annotations:
    controller.devfile.io/mount-path: /home/user/certs
    controller.devfile.io/mount-as: file
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-secret: 'true'
data:
  tls.cer: >-
    <Base64_encoded_content_of_public_cert> 1

1: Base64 encoding with disabled line wrapping.

Apply the ConfigMap for the TrustStore initialization script:

kind: ConfigMap
apiVersion: v1
metadata:
  name: init-truststore
  annotations:
    controller.devfile.io/mount-as: subpath
    controller.devfile.io/mount-path: /home/user/
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-configmap: 'true'
data:
  init-truststore.sh: |
    #!/usr/bin/env bash

    keytool -importcert -noprompt -file /home/user/certs/tls.cer -cacerts -storepass changeit

Apply the ConfigMap for the Gradle init script:

kind: ConfigMap
apiVersion: v1
metadata:
  name: init-gradle
  annotations:
    controller.devfile.io/mount-as: subpath
    controller.devfile.io/mount-path: /home/user/.gradle
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-configmap: 'true'
data:
  init.gradle: |
    allprojects {
      repositories {
        mavenLocal ()
        maven {
          url "https://<gradle_artifact_repository_route>/repository/maven-public/"
          credentials {
            username "admin"
            password "passwd"
          }
        }
      }
    }

Start a Gradle workspace.
Open a new terminal in the tools container.
Run ~/init-truststore.sh.

6.3.3. npm

You can enable an npm artifact repository in npm workspaces that run in a restricted environment.

Prerequisites

You are not running any npm workspace.

Warning

Applying a ConfigMap that sets environment variables might cause a workspace boot loop.

If you encounter this behavior, remove the ConfigMap and edit the devfile directly.

Procedure

Apply the Secret for the TLS certificate:

kind: Secret
apiVersion: v1
metadata:
  name: tls-cer
  annotations:
    controller.devfile.io/mount-path: /home/user/certs
    controller.devfile.io/mount-as: file
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-secret: 'true'
data:
  tls.cer: >-
    <Base64_encoded_content_of_public_cert> 1

1: Base64 encoding with disabled line wrapping.

Apply the ConfigMap to set the following environment variables in the tools container:

kind: ConfigMap
apiVersion: v1
metadata:
  name: disconnected-env
  annotations:
    controller.devfile.io/mount-as: env
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-configmap: 'true'
data:
  NODE_EXTRA_CA_CERTS: /home/user/certs/tls.cer
  NPM_CONFIG_REGISTRY: >-
    https://<npm_artifact_repository_route>/repository/npm-all/

6.3.4. Python

You can enable a Python artifact repository in Python workspaces that run in a restricted environment.

Prerequisites

You are not running any Python workspace.

Warning

Applying a ConfigMap that sets environment variables might cause a workspace boot loop.

If you encounter this behavior, remove the ConfigMap and edit the devfile directly.

Procedure

Apply the Secret for the TLS certificate:

kind: Secret
apiVersion: v1
metadata:
  name: tls-cer
  annotations:
    controller.devfile.io/mount-path: /home/user/certs
    controller.devfile.io/mount-as: file
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-secret: 'true'
data:
  tls.cer: >-
    <Base64_encoded_content_of_public_cert> 1

1: Base64 encoding with disabled line wrapping.

Apply the ConfigMap to set the following environment variables in the tools container:

kind: ConfigMap
apiVersion: v1
metadata:
  name: disconnected-env
  annotations:
    controller.devfile.io/mount-as: env
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-configmap: 'true'
data:
  PIP_INDEX_URL: >-
    https://<python_artifact_repository_route>/repository/pypi-all/
  PIP_CERT: /home/user/certs/tls.cer

6.3.5. Go

You can enable a Go artifact repository in Go workspaces that run in a restricted environment.

Prerequisites

You are not running any Go workspace.

Warning

Applying a ConfigMap that sets environment variables might cause a workspace boot loop.

If you encounter this behavior, remove the ConfigMap and edit the devfile directly.

Procedure

Apply the Secret for the TLS certificate:

kind: Secret
apiVersion: v1
metadata:
  name: tls-cer
  annotations:
    controller.devfile.io/mount-path: /home/user/certs
    controller.devfile.io/mount-as: file
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-secret: 'true'
data:
  tls.cer: >-
    <Base64_encoded_content_of_public_cert> 1

1: Base64 encoding with disabled line wrapping.

Apply the ConfigMap to set the following environment variables in the tools container:

kind: ConfigMap
apiVersion: v1
metadata:
  name: disconnected-env
  annotations:
    controller.devfile.io/mount-as: env
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-configmap: 'true'
data:
  GOPROXY: >-
    http://<athens_proxy_route>
  SSL_CERT_FILE: /home/user/certs/tls.cer

6.3.6. NuGet

You can enable a NuGet artifact repository in NuGet workspaces that run in a restricted environment.

Prerequisites

You are not running any NuGet workspace.

Warning

Applying a ConfigMap that sets environment variables might cause a workspace boot loop.

If you encounter this behavior, remove the ConfigMap and edit the devfile directly.

Procedure

Apply the Secret for the TLS certificate:

kind: Secret
apiVersion: v1
metadata:
  name: tls-cer
  annotations:
    controller.devfile.io/mount-path: /home/user/certs
    controller.devfile.io/mount-as: file
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-secret: 'true'
data:
  tls.cer: >-
    <Base64_encoded_content_of_public_cert> 1

1: Base64 encoding with disabled line wrapping.

Apply the ConfigMap to set the environment variable for the path of the TLS certificate file in the tools container:

kind: ConfigMap
apiVersion: v1
metadata:
  name: disconnected-env
  annotations:
    controller.devfile.io/mount-as: env
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-configmap: 'true'
data:
  SSL_CERT_FILE: /home/user/certs/tls.cer

Apply the ConfigMap to create the nuget.config file:

kind: ConfigMap
apiVersion: v1
metadata:
  name: init-nuget
  annotations:
    controller.devfile.io/mount-as: subpath
    controller.devfile.io/mount-path: /projects
  labels:
    controller.devfile.io/mount-to-devworkspace: 'true'
    controller.devfile.io/watch-configmap: 'true'
data:
  nuget.config: |
    <?xml version="1.0" encoding="UTF-8"?>
    <configuration>
      <packageSources>
        <add key="nexus2" value="https://<nuget_artifact_repository_route>/repository/nuget-group/"/>
      </packageSources>
      <packageSourceCredentials>
        <nexus2>
            <add key="Username" value="admin" />
            <add key="Password" value="passwd" />
        </nexus2>
      </packageSourceCredentials>
    </configuration>

Chapter 6. Using credentials and configurations in workspaces

6.1. Mounting Secrets

6.1.1. Creating image pull Secrets

6.1.1.1. Creating an image pull Secret with `oc`

6.1.1.2. Creating an image pull Secret from a `.dockercfg` file

6.1.1.3. Creating an image pull Secret from a `config.json` file

6.1.2. Using a Git-provider access token

6.2. Mounting ConfigMaps

6.3. Enabling artifact repositories in a restricted environment

6.3.1. Maven

6.3.2. Gradle

6.3.3. npm

6.3.4. Python

6.3.5. Go

6.3.6. NuGet

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links

Chapter 6. Using credentials and configurations in workspaces

6.1. Mounting Secrets

6.1.1. Creating image pull Secrets

6.1.1.1. Creating an image pull Secret with oc

6.1.1.2. Creating an image pull Secret from a .dockercfg file

6.1.1.3. Creating an image pull Secret from a config.json file

6.1.2. Using a Git-provider access token

6.2. Mounting ConfigMaps

6.3. Enabling artifact repositories in a restricted environment

6.3.1. Maven

6.3.2. Gradle

6.3.3. npm

6.3.4. Python

6.3.5. Go

6.3.6. NuGet

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links

6.1.1.1. Creating an image pull Secret with `oc`

6.1.1.2. Creating an image pull Secret from a `.dockercfg` file

6.1.1.3. Creating an image pull Secret from a `config.json` file