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
- Git configuration
- 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
, orenv
.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 allDev 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, Bitbucket, or Microsoft Azure Repos 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 use a personal access token. You can configure personal access tokens on the User Preferences page of your OpenShift Dev Spaces dashboard: https://<openshift_dev_spaces_fqdn>/dashboard/#/user-preferences?tab=personal-access-tokens
, or apply it manually as a Kubernetes Secret in the namespace.
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 workspaces with clones of private Git repositories that are hosted on GitHub, GitLab, Bitbucket Server, or Microsoft Azure Repos.
You can create and apply multiple access-token Secrets per Git provider. You must apply each of those Secrets in your user project.
Prerequisites
You have logged in to the cluster.
TipOn OpenShift, you can use the
oc
command-line tool to log in to the cluster:$ oc login https://<openshift_dev_spaces_fqdn> --username=<my_user>
Procedure
Generate your access token on your Git provider’s website.
ImportantPersonal access tokens are sensitive information and should be kept confidential. Treat them like passwords. If you are having trouble with authentication, ensure you are using the correct token and have the appropriate permissions for cloning repositories:
- Open a terminal locally on your computer
-
Use the
git
command to clone the repository using your personal access token. The format of thegit
command vary based on the Git Provider. As an example, GitHub personal access token verification can be done using the following command:
git clone https://<PAT>@github.com/username/repo.git
Replace
<PAT>
with your personal access token, andusername/repo
with the appropriate repository path. If the token is valid and has the necessary permissions, the cloning process should be successful. Otherwise, this is an indicator of incorrect personal access token, insufficient permissions, or other issues.ImportantFor GitHub Enterprise Cloud, verify that the token is authorized for use within the organization.
Encode your access token to Base64.
TipIf 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
-
Go to
https://<openshift_dev_spaces_fqdn>/api/user/id
in the web browser to get your OpenShift Dev Spaces user ID. 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-organization: <git_provider_organization>4 data: token: <Base64_encoded_access_token> type: Opaque
-
Visit
https://<openshift_dev_spaces_fqdn>/api/kubernetes/namespace
to get your OpenShift Dev Spaces user namespace asname
. Switch to your OpenShift Dev Spaces user namespace in the cluster.
TipOn 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.
TipOn 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
, orenv
.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 allDev 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.2.1. Mounting Git configuration
Follow the instructions below to mount a Git config file in a workspace.
Prerequisites
- You have logged in to the cluster.
Procedure
Prepare a new OpenShift ConfigMap.
kind: ConfigMap apiVersion: v1 metadata: name: workspace-userdata-gitconfig-configmap namespace: <user_namespace> 1 labels: controller.devfile.io/mount-to-devworkspace: 'true' controller.devfile.io/watch-configmap: 'true' annotations: controller.devfile.io/mount-as: subpath controller.devfile.io/mount-path: /etc/ data: gitconfig: "[user] \n name = <git_user_name> \n email = <git_user_email>" 2
Apply the ConfigMap.
$ oc apply -f - <<EOF <ConfigMap_prepared_in_step_1> EOF
Verification
- Start a new workspace by using the URL of a remote Git repository that the Git provider hosts.
-
Once the workspace is started, open a new terminal in the
tools
container and rungit config --get-regexp user.*
. Your Git user name and email should appear in the output.
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 thesettings.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 JBoss 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.
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: /public-certs controller.devfile.io/mount-as: file labels: controller.devfile.io/mount-to-devworkspace: 'true' controller.devfile.io/watch-secret: 'true' data: nexus.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: NPM_CONFIG_REGISTRY: >- https://<npm_artifact_repository_route>/repository/npm-all/
6.3.3.1. Disabling self-signed certificate validation
Run the command below to disable SSL/TLS, bypassing the validation of your self-signed certificates. Note that this is a potential security risk. For a better solution, configure a self-signed certificate you trust with NODE_EXTRA_CA_CERTS
.
Procedure
Run the following command in the terminal:
npm config set strict-ssl false
6.3.3.2. Configuring NODE_EXTRA_CA_CERTS to use a certificate
Use the command below to set NODE_EXTRA_CA_CERTS to point to where you have your SSL/TLS certificate.
Procedure
Run the following command in the terminal:
`export NODE_EXTRA_CA_CERTS=/public-certs/nexus.cer` 1 `npm install`
- 1
/public-certs/nexus.cer
is the path to self-signed SSL/TLS certificate of Nexus artifactory.
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.
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.
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.
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>