Chapter 3. Developer workspaces

Red Hat CodeReady Workspaces provides developer workspaces with everything needed to a code, build, test, run, and debug applications. To allow that, the developer workspaces provide four main components:

  1. The source code of a project.
  2. A web-based IDE.
  3. Tool dependencies, needed by developers to work on a project
  4. Application runtime: a replica of the environment where the application runs in production

Pods manage each component of a CodeReady Workspaces workspace. Therefore, everything running in a CodeReady Workspaces workspace is running inside containers. This makes a CodeReady Workspaces workspace highly portable.

The embedded browser-based IDE is the point of access for everything running in a CodeReady Workspaces workspace. This makes a CodeReady Workspaces workspace easily shareable.

Important

By default, it is possible to run only one workspace at a time. To change the default value, see: the CodeReady Workspaces 2.3 Installation Guide.

Table 3.1. Features and benefits

FeaturesTraditional IDE workspacesRed Hat CodeReady Workspaces workspaces

Configuration and installation required

Yes.

No.

Embedded tools

Partial. IDE plug-ins need configuration. Dependencies need installation and configuration. Example: JDK, Maven, Node.

Yes. Plug-ins provide their dependencies.

Application runtime provided

No. Developers have to manage that separately.

Yes. Application runtime is replicated in the workspace.

Shareable

No. Or not easily

Yes. Developer workspaces are shareable with a URL.

Versionable

No

Yes. Devfiles exist with project source code.

Accessible from anywhere

No. Installation is needed.

Yes. Only requires a browser.

To start a CodeReady Workspaces workspace, following options are available:

Use the Dashboard to discover CodeReady Workspaces 2.3:

Use a devfile as the preferred way to start a CodeReady Workspaces 2.3 workspace:

Use the browser-based IDE as the preferred way to interact with a CodeReady Workspaces 2.3 workspace. For an alternative way to interact with a CodeReady Workspaces 2.3 workspace, see: Remotely accessing workspaces.

3.1. Configuring a workspace using a devfile

To quickly and easily configure a CodeReady Workspaces workspace, use a devfile. For an introduction to devfiles and instructions for their use, see the instructions in this section.

3.1.1. What is a devfile

A devfile is a file that describes and define a development environment:

  • the source code
  • the development components, such as browser IDE tools and application runtimes
  • a list of pre-defined commands
  • projects to clone

Devfiles are YAML files that CodeReady Workspaces consumes and transforms into a cloud workspace composed of multiple containers. The devfile can be saved in the root folder of a Git repository, a feature branch of a Git repository, a publicly accessible destination, or as a separate, locally stored artifact. Devfiles saved in Git repository can use multiple names, such as devfile.yaml or .devfile.yaml.

When creating a workspace, CodeReady Workspaces uses that definition to initiate everything and run all the containers for the required tools and application runtimes. CodeReady Workspaces also mounts file-system volumes to make source code available to the workspace.

Devfiles can be versioned with the project source code. When there is a need for a workspace to fix an old maintenance branch, the project devfile provides a definition of the workspace with the tools and the exact dependencies to start working on the old branch. Use it to instantiate workspaces on demand.

CodeReady Workspaces maintains the devfile up-to-date with the tools used in the workspace:

  • Projects of the workspace (path, Git location, branch)
  • Commands to perform daily tasks (build, run, test, debug)
  • Runtime environment (container images to run the application)
  • Che-Theia plug-ins with tools, IDE features, and helpers that a developer would use in the workspace (Git, Java support, SonarLint, Pull Request)

3.1.2. Creating a workspace from the default branch of a Git repository

A CodeReady Workspaces workspace can be created by pointing to a devfile that is stored in a Git source repository. The CodeReady Workspaces instance then uses the discovered devfile.yaml file to build a workspace using the /f?url= API.

Prerequisites

Procedure

Run the workspace by opening the following URL: https://codeready-<openshift_deployment_name>.<domain_name>/f?url=https://<GitRepository>

Example

https://che.openshift.io/f?url=https://github.com/eclipse/che

3.1.3. Creating a workspace from a feature branch of a Git repository

A CodeReady Workspaces workspace can be created by pointing to devfile that is stored in a Git source repository on a feature branch of the user’s choice. The CodeReady Workspaces instance then uses the discovered devfile to build a workspace.

Prerequisites

Procedure

Execute the workspace by opening the following URL: https://codeready-<openshift_deployment_name>.<domain_name>/f?url=<GitHubBranch>

Example

Use following URL format to open an experimental quarkus-quickstarts branch hosted on che.openshift.io.

https://che.openshift.io/f?url=https://github.com/maxandersen/quarkus-quickstarts/tree/che

3.1.4. Creating a workspace from a publicly accessible standalone devfile using HTTP

A workspace can be created using a devfile, the URL of which is pointing to the raw content of the devfile. The CodeReady Workspaces instance then uses the discovered devfile to build a workspace.

Prerequisites

Procedure

  1. Execute the workspace by opening the following URL: https://codeready-<openshift_deployment_name>.<domain_name>/f?url=https://<yourhosturl>/devfile.yaml

Example

https://che.openshift.io/f?url=https://gist.githubusercontent.com/themr0c/ef8e59a162748a8be07e900b6401e6a8/raw/8802c20743cde712bbc822521463359a60d1f7a9/devfile.yaml

3.1.5. Overriding devfile values using factory parameters

Values in the following sections of a remote devfile can be overridden using specially constructed additional factory parameters:

  • apiVersion
  • metadata
  • projects
  • attributes

Prerequisites

Procedure

  1. Open the workspace by navigating to the following URL: https://codeready-<openshift_deployment_name>.<domain_name>/f?url=https://<hostURL>/devfile.yaml&override.<parameter.path>=<value>

Example of overriding the generateName property

Consider the following initial devfile:

---
apiVersion: 1.0.0
metadata:
  generateName: golang-
projects:
...

To add or override generateName value, use the following factory URL:

https://che.openshift.io/f?url=https://gist.githubusercontent.com/themr0c/ef8e59a162748a8be07e900b6401e6a8/raw/8802c20743cde712bbc822521463359a60d1f7a9/devfile.yaml&override.metadata.generateName=myprefix

The resulting workspace has the following devfile model:

---
apiVersion: 1.0.0
metadata:
  generateName: myprefix
projects:
...

Example of overriding project source branch property

Consider the following initial devfile:

---
apiVersion: 1.0.0
metadata:
  generateName: java-mysql-
projects:
  - name: web-java-spring-petclinic
    source:
      type: git
      location: "https://github.com/spring-projects/spring-petclinic.git"
...

To add or override source branch value, use the following factory URL:

https://che.openshift.io/f?url=https://gist.githubusercontent.com/themr0c/ef8e59a162748a8be07e900b6401e6a8/raw/8802c20743cde712bbc822521463359a60d1f7a9/devfile.yaml&override.projects.web-java-spring-petclinic.source.branch=1.0.x

The resulting workspace has the following devfile model:

apiVersion: 1.0.0
metadata:
  generateName: java-mysql-
projects:
  - name: web-java-spring-petclinic
    source:
      type: git
      location: "https://github.com/spring-projects/spring-petclinic.git"
      branch: 1.0.x
...

Example of overriding or creating an attribute value

Consider the following initial devfile:

---
apiVersion: 1.0.0
metadata:
  generateName: golang-
attributes:
   persistVolumes: false
projects:
...

To add or override persistVolumes attribute value, use the following factory URL:

https://che.openshift.io/f?url=https://gist.githubusercontent.com/themr0c/ef8e59a162748a8be07e900b6401e6a8/raw/8802c20743cde712bbc822521463359a60d1f7a9/devfile.yaml&override.attributes.persistVolumes=true

The resulting workspace has the following devfile model:

---
apiVersion: 1.0.0
metadata:
  generateName: golang-
attributes:
   persistVolumes: true
projects:
...

When overriding attributes, everything that follows the attributes keyword is interpreted as an attribute name, so you can use dot-separated names:

https://che.openshift.io/f?url=https://gist.githubusercontent.com/themr0c/ef8e59a162748a8be07e900b6401e6a8/raw/8802c20743cde712bbc822521463359a60d1f7a9/devfile.yaml&override.attributes.dot.name.format.attribute=true

The resulting workspace has the following devfile model:

---
apiVersion: 1.0.0
metadata:
  generateName: golang-
attributes:
   dot.name.format.attribute: true
projects:
...

3.1.6. Creating a workspace using crwctl and a local devfile

A CodeReady Workspaces workspace can be created by pointing the crwctl tool to a locally stored devfile. The CodeReady Workspaces instance then uses the discovered devfile to build a workspace.

Prerequisites

Procedure

  1. Run a workspace from a devfile using the workspace:start parameter with the crwctl tool as follows:
$ crwctl workspace:start --devfile=devfile.yaml

3.2. Making a workspace portable using a devfile

To transfer a configured CodeReady Workspaces workspace, create and export the devfile of the workspace and load the devfile on a different host to initialize a new instance of the workspace. For detailed instructions on how to create such a devfile, see below.

3.2.1. What is a devfile

A devfile is a file that describes and define a development environment:

  • the source code
  • the development components, such as browser IDE tools and application runtimes
  • a list of pre-defined commands
  • projects to clone

Devfiles are YAML files that CodeReady Workspaces consumes and transforms into a cloud workspace composed of multiple containers. The devfile can be saved in the root folder of a Git repository, a feature branch of a Git repository, a publicly accessible destination, or as a separate, locally stored artifact. Devfiles saved in Git repository can use multiple names, such as devfile.yaml or .devfile.yaml.

When creating a workspace, CodeReady Workspaces uses that definition to initiate everything and run all the containers for the required tools and application runtimes. CodeReady Workspaces also mounts file-system volumes to make source code available to the workspace.

Devfiles can be versioned with the project source code. When there is a need for a workspace to fix an old maintenance branch, the project devfile provides a definition of the workspace with the tools and the exact dependencies to start working on the old branch. Use it to instantiate workspaces on demand.

CodeReady Workspaces maintains the devfile up-to-date with the tools used in the workspace:

  • Projects of the workspace (path, Git location, branch)
  • Commands to perform daily tasks (build, run, test, debug)
  • Runtime environment (container images to run the application)
  • Che-Theia plug-ins with tools, IDE features, and helpers that a developer would use in the workspace (Git, Java support, SonarLint, Pull Request)

3.2.2. A minimal devfile

The following is the minimum content required in a devfile:

apiVersion: 1.0.0
metadata:
  name: crw-in-crw-out

For a complete devfile example, see Red Hat CodeReady Workspaces in CodeReady Workspaces devfile.yaml.

name or generateName must be defined

Both name and generateName are optional parameters, but at least one of them must be defined. See Section 3.2.3, “Generating workspace names”.

3.2.3. Generating workspace names

To specify a prefix for automatically generated workspace names, set the generateName parameter in the devfile:

apiVersion: 1.0.0
metadata:
  generateName: crw-

The workspace name will be in the <generateName>YYYYY format (for example, che-2y7kp). Y is random [a-z0-9] character.

The following naming rules apply when creating workspaces:

  • When name is defined, it is used as the workspace name: <name>
  • When only generateName is defined, it is used as the base of the generated name: <generateName>YYYYY
Note

For workspaces created using a factory, defining name or generateName has the same effect. The defined value is used as the name prefix: <name>YYYYY or <generateName>YYYYY. When both generateName and name are defined, generateName takes precedence.

3.2.4. Writing a devfile for a project

This section describes how to create a minimal devfile for your project and how to include more than one projects in a devfile.

3.2.4.1. Preparing a minimal devfile

A minimal devfile sufficient to run a workspace consists of the following parts:

  • Specification version
  • Name

Example of a minimal devfile with no project

apiVersion: 1.0.0
metadata:
  name: minimal-workspace

Without any further configuration, a workspace with the default editor is launched along with its default plug-ins, which are configured on the CodeReady Workspaces Server. Che-Theia is configured as the default editor along with the CodeReady Workspaces Machine Exec plug-in. When launching a workspace within a Git repository using a factory, the project from the given repository and branch is be created by default. The project name then matches the repository name.

Add the following parts for a more functional workspace:

  • List of components: Development components and user runtimes
  • List of projects: Source code repositories
  • List of commands: Actions to manage the workspace components, such as running the development tools, starting the runtime environments, and others

Example of a minimal devfile with a project

apiVersion: 1.0.0
metadata:
  name: petclinic-dev-environment
projects:
  - name: petclinic
    source:
      type: git
      location: 'https://github.com/spring-projects/spring-petclinic.git'
components:
  - type: chePlugin
    id: redhat/java/latest

3.2.4.2. Specifying multiple projects in a devfile

A single devfile can specify multiple projects. For each project, specify the type of the source repository, its location, and, optionally, the directory the project is cloned to.

Example of a devfile with two projects

apiVersion: 1.0.0
metadata:
  name: example-devfile
projects:
- name: frontend
  source:
    type: git
    location: https://github.com/acmecorp/frontend.git
- name: backend
  clonePath: src/github.com/acmecorp/backend
  source:
    type: git
    location: https://github.com/acmecorp/backend.git

In the preceding example, there are two projects defined, frontend and backend. Each project is located in its own repository. The backend project has a specific requirement to be cloned into the src/github.com/acmecorp/backend/ directory under the source root (implicitly defined by the CodeReady Workspaces runtime) while the frontend project will be cloned into the frontend/ directory under the source root.

Additional resources

For a detailed explanation of all devfile component assignments and possible values, see:

These sample devfiles are a good source of inspiration:

3.2.5. Devfile reference

This section contains devfile reference and instructions on how to use the various elements that devfiles consist of.

3.2.5.1. Adding projects to a devfile

Usually a devfile contains one or more projects. A workspace is created to develop those projects. Projects are added in the projects section of devfiles.

Each project in a single devfile must have:

  • Unique name
  • Source specified

Project source consists of two mandatory values: type and location.

type
The kind of project-source provider.
location
The URL of project source.

CodeReady Workspaces supports the following project types:

git
Projects with sources in Git. The location points to a clone link.
github
Same as git but for projects hosted on GitHub only. Use git for projects that do not use GitHub-specific features.
zip
Projects with sources in a ZIP archive. Location points to a ZIP file.
3.2.5.1.1. Project-source type: git
source:
    type: git
    location: https://github.com/eclipse/che.git
    startPoint: master           1
    tag: 7.2.0
    commitId: 36fe587
    branch: master
    sparseCheckoutDir: wsmaster  2
1
startPoint is the general value for tag, commitId, and branch. The startPoint, tag, commitId, and branch parameters are mutually exclusive. When more than one is supplied, the following order is used: startPoint, tag, commitId, branch.
2
sparseCheckoutDir the template for the sparse checkout Git feature. This is useful when only a part of a project (typically only a single directory) is needed.

Example 3.1. sparseCheckoutDir parameter settings

  • Set to /my-module/ to create only the root my-module directory (and its content).
  • Omit the leading slash (my-module/) to create all my-module directories that exist in the project. Including, for example, /addons/my-module/.

    The trailing slash indicates that only directories with the given name (including their content) are created.

  • Use wildcards to specify more than one directory name. For example, setting module-* checks out all directories of the given project that start with module-.

For more information, see Sparse checkout in Git documentation.

3.2.5.1.2. Project-source type: zip
source:
    type: zip
    location: http://host.net/path/project-src.zip
3.2.5.1.3. Project clone-path parameter: clonePath

The clonePath parameter specifies the path into which the project is to be cloned. The path must be relative to the /projects/ directory, and it cannot leave the /projects/ directory. The default value is the project name.

Example devfile with projects

apiVersion: 1.0.0
metadata:
  name: my-project-dev
projects:
  - name: my-project-resourse
    clonePath: resources/my-project
    source:
      type: zip
      location: http://host.net/path/project-res.zip
  - name: my-project
    source:
      type: git
      location: https://github.com/my-org/project.git
      branch: develop

3.2.5.2. Adding components to a devfile

Each component in a single devfile must have a unique name.

3.2.5.2.1. Component type: cheEditor

Describes the editor used in the workspace by defining its id. A devfile can only contain one component of the cheEditor type.

components:
  - alias: theia-editor
    type: cheEditor
    id: eclipse/che-theia/next

When cheEditor is missing, a default editor is provided along with its default plug-ins. The default plug-ins are also provided for an explicitly defined editor with the same id as the default one (even if it is a different version). Che-Theia is configured as default editor along with the CodeReady Workspaces Machine Exec plug-in.

To specify that a workspace requires no editor, use the editorFree:true attribute in the devfile attributes.

3.2.5.2.2. Component type: chePlugin

Describes plug-ins in a workspace by defining their id. It is allowed to have several chePlugin components.

  components:
   - alias: exec-plugin
     type: chePlugin
     id: eclipse/che-machine-exec-plugin/0.0.1

Both types above use an ID, which is slash-separated publisher, name and version of plug-in from the CodeReady Workspaces Plug-in registry.

List of available Eclipse Che plug-ins and more information about registry can be found in the Che plug-in registry GitHub repository.

3.2.5.2.3. Specifying an alternative component registry

To specify an alternative registry for the cheEditor and chePlugin component types, use the registryUrl parameter:

  components:
   - alias: exec-plugin
     type: chePlugin
     registryUrl: https://my-customregistry.com
     id: eclipse/che-machine-exec-plugin/0.0.1
3.2.5.2.4. Specifying a component by linking to its descriptor

An alternative way of specifying cheEditor or chePlugin, instead of using the editor or plug-in id (and optionally an alternative registry), is to provide a direct link to the component descriptor (typically named meta.yaml) by using the reference field:

  components:
   - alias: exec-plugin
     type: chePlugin
     reference: https://raw.githubusercontent.com.../plugin/1.0.1/meta.yaml
Note

It is impossible to mix the id and reference fields in a single component definition; they are mutually exclusive.

3.2.5.2.5. Tuning chePlugin component configuration

A chePlugin component may need to be precisely tuned, and in such case, component preferences can be used. The example shows how to configure JVM using plug-in preferences.

  id: redhat/java/0.38.0
  type: chePlugin
  preferences:
     java.jdt.ls.vmargs: '-noverify -Xmx1G -XX:+UseG1GC -XX:+UseStringDeduplication'

Preferences may also be specified as an array:

  id: redhat/java/0.38.0
  type: chePlugin
  preferences:
     go.lintFlags: ["--enable-all", "--new"]
3.2.5.2.6. Component type: kubernetes

A complex component type that allows to apply configuration from a list of OpenShift components.

The content can be provided through the reference attribute, which points to the file with the component content.

  components:
    - alias: mysql
      type: kubernetes
      reference: petclinic.yaml
      selector:
        app.kubernetes.io/name: mysql
        app.kubernetes.io/component: database
        app.kubernetes.io/part-of: petclinic

Alternatively, to post a devfile with such components to REST API, the contents of the Kubernetes List object can be embedded into the devfile using the referenceContent field:

  components:
    - alias: mysql
      type: kubernetes
      reference: petclinic.yaml
      referenceContent: |
           kind: List
           items:
            -
             apiVersion: v1
             kind: Pod
             metadata:
              name: ws
             spec:
              containers:
              ... etc
3.2.5.2.7. Overriding container entrypoints

As with the dockerimage component, it is possible to override the entrypoint of the containers contained in the OpenShift list using the command and args properties (as understood by OpenShift).

There can be more containers in the list (contained in Pods or Pod templates of deployments). To select which containers to apply the entrypoint changes to.

The entrypoints can be defined as follows:

  components:
    - alias: appDeployment
      type: kubernetes
      reference: app-deployment.yaml
      entrypoints:
      - parentName: mysqlServer
        command: ['sleep']
        args: ['infinity']
      - parentSelector:
          app: prometheus
        args: ['-f', '/opt/app/prometheus-config.yaml']

The entrypoints list contains constraints for picking the containers along with the command and args parameters to apply to them. In the example above, the constraint is parentName: mysqlServer, which will cause the command to be applied to all containers defined in any parent object called mysqlServer. The parent object is assumed to be a top level object in the list defined in the referenced file, which is app-deployment.yaml in the example above.

Other types of constraints (and their combinations) are possible:

containerName
the name of the container
parentName
the name of the parent object that (indirectly) contains the containers to override
parentSelector
the set of labels the parent object needs to have

A combination of these constraints can be used to precisely locate the containers inside the referenced Kubernetes List.

3.2.5.2.8. Overriding container environment variables

To provision or override entrypoints in a OpenShift component, configure it in the following way:

  components:
    - alias: appDeployment
      type: kubernetes
      reference: app-deployment.yaml
      env:
        - name: ENV_VAR
          value: value

This is useful for temporary content or without access to editing the referenced content. The specified environment variables are provisioned into each init container and containers inside all Pods and Deployments.

3.2.5.2.9. Specifying mount-source option

To specify a project sources directory mount into container(s), use the mountSources parameter:

   components:
      - alias: appDeployment
        type: kubernetes
        reference: app-deployment.yaml
        mountSources: true

If enabled, project sources mounts will be applied to every container of the given component. This parameter is also applicable for chePlugin type components.

3.2.5.2.10. Component type: dockerimage

A component type that allows to define a container image-based configuration of a container in a workspace. A devfile can only contain one component of the dockerimage type. The dockerimage type of component brings in custom tools into the workspace. The component is identified by its image.

 components:
   - alias: maven
     type: dockerimage
     image: eclipe/maven-jdk8:latest
     volumes:
       - name: mavenrepo
         containerPath: /root/.m2
     env:
       - name: ENV_VAR
         value: value
     endpoints:
       - name: maven-server
         port: 3101
         attributes:
           protocol: http
           secure: 'true'
           public: 'true'
           discoverable: 'false'
     memoryLimit: 1536M
     command: ['tail']
     args: ['-f', '/dev/null']

Example of a minimal dockerimage component

apiVersion: 1.0.0
metadata:
    name: MyDevfile
components:
type: dockerimage
image: golang
memoryLimit: 512Mi
command: ['sleep', 'infinity']

It specifies the type of the component, dockerimage and the image attribute names the image to be used for the component using the usual Docker naming conventions, that is, the above type attribute is equal to docker.io/library/golang:latest.

A dockerimage component has many features that enable augmenting the image with additional resources and information needed for meaningful integration of the tool provided by the image with Red Hat CodeReady Workspaces.

3.2.5.2.11. Mounting project sources

For the dockerimage component to have access to the project sources, you must set the mountSources attribute to true.

apiVersion: 1.0.0
metadata:
    name: MyDevfile
components:
type: dockerimage
image: golang
memoryLimit: 512Mi
mountSources: true
command: ['sleep', 'infinity']

The sources is mounted on a location stored in the CHE_PROJECTS_ROOT environment variable that is made available in the running container of the image. This location defaults to /projects.

3.2.5.2.12. Container Entrypoint

The command attribute of the dockerimage along with other arguments, is used to modify the entrypoint command of the container created from the image. In Red Hat CodeReady Workspaces the container is needed to run indefinitely so that you can connect to it and execute arbitrary commands in it at any time. Because the availability of the sleep command and the support for the infinity argument for it is different and depends on the base image used in the particular images, CodeReady Workspaces cannot insert this behavior automatically on its own. However, you can take advantage of this feature to, for example, start necessary servers with modified configurations, etc.

3.2.5.2.13. Persistent Storage

Components of any type can specify the custom volumes to be mounted on specific locations within the image. Note that the volume names are shared across all components and therefore this mechanism can also be used to share file systems between components.

Example specifying volumes for dockerimage type:

apiVersion: 1.0.0
metadata:
  name: MyDevfile
components:
  - type: dockerimage
    image: golang
    memoryLimit: 512Mi
    mountSources: true
    command: ['sleep', 'infinity']
    volumes:
      - name: cache
        containerPath: /.cache

Example specifying volumes for cheEditor/chePlugin type:

apiVersion: 1.0.0
metadata:
  name: MyDevfile
components:
  - type: cheEditor
    alias: theia-editor
    id: eclipse/che-theia/next
    env:
    - name: HOME
      value: $(CHE_PROJECTS_ROOT)
    volumes:
    - name: cache
      containerPath: /.cache

Example specifying volumes for kubernetes/openshift type:

apiVersion: 1.0.0
metadata:
  name: MyDevfile
components:
  - type: openshift
    alias: mongo
    reference: mongo-db.yaml
    volumes:
    - name: mongo-persistent-storage
      containerPath: /data/db
3.2.5.2.14. Specifying container memory limit for components

To specify a container(s) memory limit for dockerimage, chePlugin, cheEditor, use the memoryLimit parameter:

  components:
   - alias: exec-plugin
     type: chePlugin
     id: eclipse/che-machine-exec-plugin/0.0.1
     memoryLimit: 1Gi
   - type: dockerimage
     image: eclipe/maven-jdk8:latest
     memoryLimit: 512M

This limit will be applied to every container of the given component.

For the cheEditor and chePlugin component types, RAM limits can be described in the plug-in descriptor file, typically named meta.yaml.

If none of them are specified, system-wide defaults will be applied (see description of CHE_WORKSPACE_SIDECAR_DEFAULT__MEMORY__LIMIT__MB system property).

3.2.5.2.15. Specifying container memory request for components

To specify a container(s) memory request for chePlugin or cheEditor, use the memoryRequest parameter:

  components:
   - alias: exec-plugin
     type: chePlugin
     id: eclipse/che-machine-exec-plugin/0.0.1
     memoryLimit: 1Gi
     memoryRequest: 512M
   - type: dockerimage
     image: eclipe/maven-jdk8:latest
     memoryLimit: 512M
     memoryRequest: 256M

This limit will be applied to every container of the given component.

For the cheEditor and chePlugin component types, RAM requests can be described in the plug-in descriptor file, typically named meta.yaml.

If none of them are specified, system-wide defaults are applied (see description of CHE_WORKSPACE_SIDECAR_DEFAULT__MEMORY__REQUEST__MB system property).

3.2.5.2.16. Specifying container CPU limit for components

To specify a container(s) CPU limit for chePlugin, cheEditor or dockerimage use the cpuLimit parameter:

  components:
   - alias: exec-plugin
     type: chePlugin
     id: eclipse/che-machine-exec-plugin/0.0.1
     cpuLimit: 1.5
   - type: dockerimage
     image: eclipe/maven-jdk8:latest
     cpuLimit: 750m

This limit will be applied to every container of the given component.

For the cheEditor and chePlugin component types, CPU limits can be described in the plug-in descriptor file, typically named meta.yaml.

If none of them are specified, system-wide defaults are applied (see description of CHE_WORKSPACE_SIDECAR_DEFAULT__CPU__LIMIT__CORES system property).

3.2.5.2.17. Specifying container CPU request for components

To specify a container(s) CPU request for chePlugin, cheEditor or dockerimage use the cpuRequest parameter:

  components:
   - alias: exec-plugin
     type: chePlugin
     id: eclipse/che-machine-exec-plugin/0.0.1
     cpuLimit: 1.5
     cpuRequest: 0.225
   - type: dockerimage
     image: eclipe/maven-jdk8:latest
     cpuLimit: 750m
     cpuRequest: 450m

This limit will be applied to every container of the given component.

For the cheEditor and chePlugin component types, CPU requests can be described in the plug-in descriptor file, typically named meta.yaml.

If none of them are specified, system-wide defaults are applied (see description of CHE_WORKSPACE_SIDECAR_DEFAULT__CPU__REQUEST__CORES system property).

3.2.5.2.18. Environment variables

Red Hat CodeReady Workspaces allows you to configure Docker containers by modifying the environment variables available in component’s configuration. Environment variables are supported by the following component types: dockerimage, chePlugin, cheEditor, kubernetes, openshift. In case component has multiple containers, environment variables will be provisioned to each container.

apiVersion: 1.0.0
metadata:
  name: MyDevfile
components:
  - type: dockerimage
    image: golang
    memoryLimit: 512Mi
    mountSources: true
    command: ['sleep', 'infinity']
    env:
      - name: GOPATH
        value: $(CHE_PROJECTS_ROOT)/go
  - type: cheEditor
    alias: theia-editor
    id: eclipse/che-theia/next
    memoryLimit: 2Gi
    env:
    - name: HOME
      value: $(CHE_PROJECTS_ROOT)
Note
  • The variable expansion works between the environment variables, and it uses the Kubernetes convention for the variable references.
  • The predefined variables are available for use in custom definitions.

The following environment variables are pre-set by the CodeReady Workspaces server:

  • CHE_PROJECTS_ROOT: The location of the projects directory (note that if the component does not mount the sources, the projects will not be accessible).
  • CHE_WORKSPACE_LOGS_ROOT__DIR: The location of the logs common to all the components. If the component chooses to put logs into this directory, the log files are accessible from all other components.
  • CHE_API_INTERNAL: The URL to the CodeReady Workspaces server API endpoint used for communication with the CodeReady Workspaces server.
  • CHE_WORKSPACE_ID: The ID of the current workspace.
  • CHE_WORKSPACE_NAME: The name of the current workspace.
  • CHE_WORKSPACE_NAMESPACE: The CodeReady Workspaces project of the current workspace. This environment variable is the name of the user or organization that the workspace belongs to. Note that this is different from the OpenShift project or OpenShift project to which the workspace is deployed.
  • CHE_MACHINE_TOKEN: The token used to authenticate the request against the CodeReady Workspaces server.
  • CHE_MACHINE_AUTH_SIGNATUREPUBLICKEY: The public key used to secure the communication with the CodeReady Workspaces server.
  • CHE_MACHINE_AUTH_SIGNATURE__ALGORITHM: The encryption algorithm used in the secured communication with the CodeReady Workspaces server.

A devfiles may only need the CHE_PROJECTS_ROOT environment variable to locate the cloned projects in the component’s container. More advanced devfiles might use the CHE_WORKSPACE_LOGS_ROOT__DIR environment variable to read the logs (for example as part of a devfile command). The environment variables used to securely access the CodeReady Workspaces server are mostly out of scope for devfiles and are present only for advanced use cases that are usually handled by the CodeReady Workspaces plug-ins.

3.2.5.2.19. Endpoints

Components of any type can specify the endpoints that the Docker image exposes. These endpoints can be made accessible to the users if the CodeReady Workspaces cluster is running using a OpenShift ingress or an OpenShift route and to the other components within the workspace. You can create an endpoint for your application or database, if your application or database server is listening on a port and you want to be able to directly interact with it yourself or you want other components to interact with it.

Endpoints have several properties as shown in the following example:

apiVersion: 1.0.0
metadata:
  name: MyDevfile
projects:
  - name: my-go-project
    clonePath: go/src/github.com/acme/my-go-project
    source:
      type: git
      location: https://github.com/acme/my-go-project.git
components:
  - type: dockerimage
    image: golang
    memoryLimit: 512Mi
    mountSources: true
    command: ['sleep', 'infinity']
    env:
      - name: GOPATH
        value: $(CHE_PROJECTS_ROOT)/go
      - name: GOCACHE
        value: /tmp/go-cache
    endpoints:
     - name: web
       port: 8080
       attributes:
         discoverable: false
         public: true
         protocol: http
  - type: dockerimage
    image: postgres
    memoryLimit: 512Mi
    env:
      - name: POSTGRES_USER
        value: user
      - name: POSTGRES_PASSWORD
        value: password
      - name: POSTGRES_DB
        value: database
    endpoints:
      - name: postgres
        port: 5432
        attributes:
          discoverable: true
          public: false

Here, there are two Docker images, each defining a single endpoint. Endpoint is an accessible port that can be made accessible inside the workspace or also publicly (example, from the UI). Each endpoint has a name and port, which is the port on which certain server running inside the container is listening. The following are a few attributes that you can set on the endpoint:

  • discoverable: If an endpoint is discoverable, it means that it can be accessed using its name as the host name within the workspace containers (in the OpenShift parlance, a service is created for it with the provided name). 55
  • public: The endpoint will be accessible outside of the workspace, too (such endpoint can be accessed from the CodeReady Workspaces user interface). Such endpoints are publicized always on port 80 or 443 (depending on whether tls is enabled in CodeReady Workspaces).
  • protocol: For public endpoints the protocol is a hint to the UI on how to construct the URL for the endpoint access. Typical values are http, https, ws, wss.
  • secure: A boolean (defaulting to false) specifying whether the endpoint is put behind a JWT proxy requiring a JWT workspace token to grant access. The JWT proxy is deployed in the same Pod as the server and assumes the server listens solely on the local loopback interface, such as 127.0.0.1.

    Warning

    Listening on any other interface than the local loopback poses a security risk because such server is accessible without the JWT authentication within the cluster network on the corresponding IP addresses.

  • path: The URL of the endpoint.
  • unsecuredPaths: A comma-separated list of endpoint paths that are to stay unsecured even if the secure attribute is set to true.
  • cookiesAuthEnabled: When set to true (the default is false), the JWT workspace token is automatically fetched and included in a workspace-specific cookie to allow requests to pass through the JWT proxy.

    Warning

    This setting potentially allows a CSRF attack when used in conjunction with a server using POST requests.

When starting a new server within a component, CodeReady Workspaces autodetects this, and the UI offers to automatically expose this port as a public port. This is useful for debugging a web application, for example. It is impossible to do this for servers that autostart with the container (for example, a database server). For such components, specify the endpoints explicitly.

Example specifying endpoints for kubernetes/openshift and chePlugin/cheEditor types:

apiVersion: 1.0.0
metadata:
  name: MyDevfile
components:
  - type: cheEditor
    alias: theia-editor
    id: eclipse/che-theia/next
    endpoints:
    - name: 'theia-extra-endpoint'
      port: 8880
      attributes:
        discoverable: true
        public: true

  - type: chePlugin
    id: redhat/php/latest
    memoryLimit: 1Gi
    endpoints:
    - name: 'php-endpoint'
      port: 7777

  - type: chePlugin
    alias: theia-editor
    id: eclipse/che-theia/next
    endpoints:
    - name: 'theia-extra-endpoint'
      port: 8880
      attributes:
        discoverable: true
        public: true

  - type: openshift
    alias: webapp
    reference: webapp.yaml
    endpoints:
    - name: 'web'
      port: 8080
      attributes:
        discoverable: false
        public: true
        protocol: http

  - type: openshift
    alias: mongo
    reference: mongo-db.yaml
    endpoints:
    - name: 'mongo-db'
      port: 27017
      attributes:
        discoverable: true
        public: false
3.2.5.2.20. OpenShift resources

Complex deployments can be described using OpenShift resource lists that can be referenced in the devfile. This makes them a part of the workspace.

Important
  • Because a CodeReady Workspaces workspace is internally represented as a single deployment, all resources from the OpenShift list are merged into that single deployment.
  • Be careful when designing such lists because this can result in name conflicts and other problems.
  • Only the following subset of the OpenShift objects are supported: deployments, pods, services, persistent volume claims, secrets, and ConfigMaps. Kubernetes Ingresses are ignored, but OpenShift routes are supported. A workspace created from a devfile using any other object types fails to start.
  • When running CodeReady Workspaces on a Kubernetes cluster, only Kubernetes lists are supported. When running CodeReady Workspaces on an OpenShift cluster, both OpenShift lists are supported.
apiVersion: 1.0.0
metadata:
  name: MyDevfile
projects:
  - name: my-go-project
    clonePath: go/src/github.com/acme/my-go-project
    source:
      type: git
      location: https://github.com/acme/my-go-project.git
components:
  -  type: kubernetes
     reference: ../relative/path/postgres.yaml

The preceding component references a file that is relative to the location of the devfile itself. Meaning, this devfile is only loadable by a CodeReady Workspaces factory to which you supply the location of the devfile and therefore it is able to figure out the location of the referenced OpenShift resource list.

The following is an example of the postgres.yaml file.

apiVersion: v1
kind: List
items:
-
    apiVersion: v1
    kind: Deployment
    metadata:
        name: postgres
        labels:
            app: postgres
    spec:
        template:
        metadata:
            name: postgres
            app:
                name: postgres
        spec:
            containers:
            - image: postgres
              name: postgres
              ports:
              - name: postgres
                containerPort: 5432
                volumeMounts:
                - name: pg-storage
                  mountPath: /var/lib/postgresql/data
            volumes:
            - name: pg-storage
              persistentVolumeClaim:
                  claimName: pg-storage
-
    apiVersion: v1
    kind: Service
    metadata:
        name: postgres
        labels:
            app: postgres
            name: postgres
    spec:
        ports:
            - port: 5432
              targetPort: 5432
        selector:
            app: postgres
-
    apiVersion: v1
    kind: PersistentVolumeClaim
    metadata:
        name: pg-storage
      labels:
        app: postgres
    spec:
        accessModes:
         - ReadWriteOnce
        resources:
            requests:
                storage: 1Gi

For a basic example of a devfile with an associated OpenShift list, see web-nodejs-with-db-sample on redhat-developer GitHub.

If you use generic or large resource lists from which you will only need a subset of resources, you can select particular resources from the list using a selector (which, as the usual OpenShift selectors, works on the labels of the resources in the list).

apiVersion: 1.0.0
metadata:
  name: MyDevfile
projects:
  - name: my-go-project
    clonePath: go/src/github.com/acme/my-go-project
    source:
      type: git
      location: https://github.com/acme/my-go-project.git
components:
  - type: kubernetes
    reference: ../relative/path/postgres.yaml
    selector:
      app: postgres

Additionally, it is also possible to modify the entrypoints (command and arguments) of the containers present in the resource list. For details of the advanced use case, see the reference (TODO: link).

3.2.5.3. Adding commands to a devfile

A devfile allows to specify commands to be available for execution in a workspace. Every command can contain a subset of actions, which are related to a specific component in whose container it will be executed.

 commands:
   - name: build
     actions:
       - type: exec
         component: mysql
         command: mvn clean
         workdir: /projects/spring-petclinic

You can use commands to automate the workspace. You can define commands for building and testing your code, or cleaning the database.

The following are two kinds of commands:

  • CodeReady Workspaces specific commands: You have full control over what component executes the command.
  • Editor specific commands: You can use the editor-specific command definitions (example: tasks.json and launch.json in Che-Theia, which is equivalent to how these files work in VS Code).
3.2.5.3.1. CodeReady Workspaces-specific commands

Each CodeReady Workspaces-specific command features:

  • An action attribute that is a command to execute.
  • A component attribute that specifies the container in which to execute the command.

The commands are run using the default shell in the container.

apiVersion: 1.0.0
metadata:
  name: MyDevfile
projects:
  - name: my-go-project
    clonePath: go/src/github.com/acme/my-go-project
    source:
      type: git
      location: https://github.com/acme/my-go-project.git
components:
  - type: dockerimage
    image: golang
    alias: go-cli
    memoryLimit: 512Mi
    mountSources: true
    command: ['sleep', 'infinity']
    env:
      - name: GOPATH
        value: $(CHE_PROJECTS_ROOT)/go
      - name: GOCACHE
        value: /tmp/go-cache
commands:
  - name: compile and run
    actions:
     - type: exec
       component: go-cli
       command: “go get -d && go run main.go”
       workdir: “${CHE_PROJECTS_ROOT}/src/github.com/acme/my-go-project”

+

Note
  • If a component to be used in a command must have an alias. This alias is used to reference the component in the command definition. Example: alias: go-cli in the component definition and component: go-cli in the command definition. This ensures that Red Hat CodeReady Workspaces can find the correct container to run the command in.
  • A command can have only one action.
3.2.5.3.2. Editor-specific commands

If the editor in the workspace supports it, the devfile can specify additional configuration in the editor-specific format. This is dependent on the integration code present in the workspace editor itself and so is not a generic mechanism. However, the default Che-Theia editor within Red Hat CodeReady Workspaces is equipped to understand the tasks.json and launch.json files provided in the devfile.

apiVersion: 1.0.0
metadata:
  name: MyDevfile
projects:
  - name: my-go-project
    clonePath: go/src/github.com/acme/my-go-project
    source:
      type: git
      location: https://github.com/acme/my-go-project.git
commands:
  - name: tasks
    actions:
      - type: vscode-task
        referenceContent: >
            {
                "version": "2.0.0",
                "tasks": [
                    {
                        "label": "create test file",
                        "type": "shell",
                        "command": "touch ${workspaceFolder}/test.file"
                    }
                ]
            }

This example shows association of a tasks.json file with a devfile. Notice the vscode-task type that instructs the Che-Theia editor to interpret this command as a tasks definition and referenceContent attribute that contains the contents of the file itself. You can also save this file separately from the devfile and use reference attribute to specify a relative or absolute URL to it.

In addition to the vscode-task commands, the Che-Theia editor understands vscode-launch type using which you can specify the launch configurations.

3.2.5.3.3. Command preview URL

It is possible to specify a preview URL for commands that expose web UI. This URL is offered for opening when the command is executed.

commands:
    - name: tasks
      previewUrl:
        port: 8080     1
        path: /myweb   2
      actions:
      - type: exec
        component: go-cli
        command: "go run webserver.go"
        workdir: ${CHE_PROJECTS_ROOT}/webserver
1
TCP port where the application listens. Mandatory parameter.
2
The path part of the URL to the UI. Optional parameter. The default is root (/).

The example above opens http://__<server-domain>__/myweb, where <server-domain> is the URL to the dynamically created OpenShift Ingress or OpenShift Route.

3.2.5.3.3.1. Setting the default way of opening preview URLs

By default, a notification that asks the user about the URL opening preference is displayed.

To specify the preferred way of previewing a service URL:

  1. Open CodeReady Workspaces preferences in File → Settings → Open Preferences and find che.task.preview.notifications in the CodeReady Workspaces section.
  2. Choose from the list of possible values:

    • on — enables a notification for asking the user about the URL opening preferences
    • alwaysPreview — the preview URL opens automatically in the Preview panel as soon as a task is running
    • alwaysGoTo — the preview URL opens automatically in a separate browser tab as soon as a task is running
    • off — disables opening the preview URL (automatically and with a notification)

3.2.5.4. Devfile attributes

Devfile attributes can be used to configure various features.

3.2.5.4.1. Attribute: editorFree

When an editor is not specified in a devfile, a default is provided. When no editor is needed, use the editorFree attribute. The default value of false means that the devfile requests the provisioning of the default editor.

Example of a devfile without an editor

apiVersion: 1.0.0
metadata:
  name: petclinic-dev-environment
components:
  - alias: myApp
    type: kubernetes
    reference: my-app.yaml
attributes:
  editorFree: true

3.2.5.4.2. Attribute: persistVolumes (ephemeral mode)

By default, volumes and PVCs specified in a devfile are bound to a host folder to persist data even after a container restart. To disable data persistence to make the workspace faster, such as when the volume back end is slow, modify the persistVolumes attribute in the devfile. The default value is true. Set to false to use emptyDir for configured volumes and PVC.

Example of a devfile with ephemeral mode enabled

apiVersion: 1.0.0
metadata:
  name: petclinic-dev-environment
projects:
  - name: petclinic
    source:
      type: git
      location: 'https://github.com/che-samples/web-java-spring-petclinic.git'
attributes:
  persistVolumes: false

3.2.6. Objects supported in Red Hat CodeReady Workspaces 2.3

The following table lists the objects that are partially supported in Red Hat CodeReady Workspaces 2.3:

ObjectAPIOpenShift InfraOpenShift InfraNotes

Pod

OpenShift

Yes

Yes

-

Deployment

OpenShift

Yes

Yes

-

ConfigMap

OpenShift

Yes

Yes

-

PVC

OpenShift

Yes

Yes

-

Secret

OpenShift

Yes

Yes

-

Service

OpenShift

Yes

Yes

-

Ingress

OpenShift

Yes

No

Minishift allows you to create Ingress and it works when the host is specified (OpenShift creates a route for it). But, the loadBalancer IP is not provisioned. To add Ingress support for the OpenShift infrastructure node, generate routes based on the provided Ingress.

Route

OpenShift

No

Yes

The OpenShift recipe must be made compatible with the OpenShift Infrastructure and, instead of the provided route, generate Ingress.

Template

OpenShift

Yes

Yes

The OpenShift API does not support templates. A workspace with a template in the recipe starts successfully and the default parameters are resolved.

Additional resources

3.3. Creating and configuring a new CodeReady Workspaces 2.3 workspace

3.3.1. Creating a new workspace from the dashboard

This procedure describes how to create and edit a new CodeReady Workspaces devfile using the Dashboard.

Prerequisites

Procedure

To edit the devfile:

  1. In the Workspaces window, click the Add Workspace button. The Custom Workspace page should be opened.
  2. Scroll down to the Devfile section. In the Devfile editor, add necessary changes.

    Devfile editor with the minimal devfile
    Example: add a project

    To add a project into the workspace, add or edit the following section:

    projects:
      - name: che
        source:
          type: git
          location: 'https://github.com/eclipse/che.git'

    See the Devfile reference.

3.3.2. Adding projects to your workspace

Prerequisites

Procedure

To add a project to your workspace:

  1. Navigate to Workspaces page and click the workspace you want to update.

    Here you have two ways to add a project to your workspace:

  2. From the Projects tab.

    1. Open the Projects tab, and then click the Add Project button.
    2. Choose if you want to import the project by Git URL or from your GitHub account.

      Add Git Project
  3. From the Devfile tab.

    1. Open the Devfile tab.
    2. In the Devfile editor, add projects section with desired project.

      Edit Devfile Content
      Example: add a project

      To add a project into the workspace, add or edit the following section:

      projects:
        - name: che
          source:
            type: git
            location: 'https://github.com/eclipse/che.git'

      See the Devfile reference.

  4. Once the project is added, click Save button to save this workspace configuration, or click Apply button to apply changes to the running workspace.

    Save Workspace Configuration

3.3.3. Configuring the workspace and adding tools

3.3.3.1. Adding plug-ins

Prerequisites

Procedure

To add plug-ins to your workspace:

  1. Click the Plugins tab.
  2. Enable the plug-in that you want to add and click the Save button.

3.3.3.2. Defining the workspace editor

Prerequisites

Procedure

To define the editor to use with the workspace:

  1. Click the Editors tab.

    Note

    The recommended editor for CodeReady Workspaces 2.3 is Che-Theia.

  2. Enable the editor to add and click the Save button.
  3. Click the Devfile tab to view the changes.

    workspace devfile

3.3.3.3. Defining specific container images

Procedure

To add a new container image:

  1. In the Devfile tab, add the following section under the components property:

    components:
      - mountSources: true
         command:
           - sleep
         args:
           - infinity
         memoryLimit: 1Gi
         alias: maven3-jdk11
         type: dockerimage
         endpoints:
           - name: 8080/tcp
             port: 8080
         volumes:
           - name: projects
             containerPath: /projects
         image: 'maven:3.6.0-jdk-11'
  2. Add a CodeReady Workspaces 2.2 recipe content to the CodeReady Workspaces 2.3 devfile as referenceContent:

    component as a referenceContent
    1. Set the type from the original CodeReady Workspaces 2.2 configuration. The following is an example of the resulting file:

        type: kubernetes
        referenceContent: |
          apiVersion: v1
          kind: Pod
          metadata:
           name: ws
          spec:
           containers:
            -
             image: 'rhche/centos_jdk8:latest'
             name: dev
             resources:
             limits:
               memory: 512Mi
  3. Copy the required fields from the old workspace (image, volumes, endpoints). For example:

    workspace devfile che 7
  4. Change the memoryLimit and alias variables, if needed. Here, the field alias is used to set a name for the component. It is generated automatically from the image field, if not set.

      image: 'maven:3.6.0-jdk-11'
      alias: maven3-jdk11
  5. Change the memoryLimit, memoryRequest, or both fields to specify the RAM required for the component.

      alias: maven3-jdk11
      memoryLimit: 256M
      memoryRequest: 128M
  6. Repeat the steps to add additional container images.

3.3.3.4. Adding commands to your workspace

The following is a comparison between workspace configuration commands in CodeReady Workspaces 2.2 (Figure 1) and CodeReady Workspaces 2.3 (Figure 2):

Figure 3.1. An example of the Workspace configuration commands in CodeReady Workspaces 2.3

workspace devfile

Procedure

To define commands to your workspace, edit the workspace devfile:

  1. Add (or replace) the commands section with the first command. Change the name and the command fields from the original workspace configuration (see the preceding equivalence table).

    commands:
      - name: build
        actions:
          - type: exec
            command: mvn clean install
  2. Copy the following YAML code into the commands section to add a new command. Change the name and the command fields from the original workspace configuration (see the preceding equivalence table).

      - name: build and run
        actions:
          - type: exec
            command: mvn clean install && java -jar
  3. Optionally, add the component field into actions. This indicates the component alias where the command will be performed.
  4. Repeat step 2 to add more commands to the devfile.
  5. Click the Devfile tab to view the changes.

    workspace devfile changes
  6. Save changes and start the new CodeReady Workspaces 2.3 workspace.

    save and start the new che workspace

3.4. Importing a OpenShift application into a workspace

This section describes how to import a OpenShift application into a CodeReady Workspaces workspace.

For demonstration purposes, the section uses a sample OpenShift application having the following two Pods:

To run the application on a OpenShift cluster:

$ node=https://raw.githubusercontent.com/redhat-developer/devfile/master/samples/web-nodejs-with-db-sample/nodejs-app.yaml && \
mongo=https://raw.githubusercontent.com/redhat-developer/devfile/master/samples/web-nodejs-with-db-sample/mongo-db.yaml && \
oc apply -f ${mongo} && \
oc apply -f ${node}

To deploy a new instance of this application in a CodeReady Workspaces workspace, use one of the following three scenarios:

3.4.1. Including a OpenShift application in a workspace devfile definition

This procedure demonstrates how to define the CodeReady Workspaces 2.3 workspace devfile by OpenShift application.

Prerequisites

The devfile format is used to define a CodeReady Workspaces workspace, and its format is described in the Making a workspace portable using a devfile section. The following is an example of the simplest devfile:

apiVersion: 1.0.0
metadata:
 name: minimal-workspace

Only the name (minimal-workspace) is specified. After the CodeReady Workspaces server processes this devfile, the devfile is converted to a minimal CodeReady Workspaces workspace that only has the default editor (Che-Theia) and the default editor plug-ins (example: the terminal).

Use the OpenShift type of components in the devfile to add OpenShift applications to a workspace.

For example, the user can embed the NodeJS-Mongo application in the minimal-workspace defined in this paragraph by adding a components section.

apiVersion: 1.0.0
metadata:
 name: minimal-workspace
components:
 - type: kubernetes
   reference: https://raw.githubusercontent.com/.../mongo-db.yaml
 - alias: nodejs-app
   type: kubernetes
   reference: https://raw.githubusercontent.com/.../nodejs-app.yaml
   entrypoints:
     - command: ['sleep']
       args: ['infinity']

Note that the sleep infinity command is added as the entrypoint of the Node.js application. This prevents the application from starting at the workspace start phase. It allows the user to start it when needed for testing or debugging purposes.

To make it easier for a developer to test the application, add the commands in the devfile:

apiVersion: 1.0.0
metadata:
 name: minimal-workspace
components:
 - type: kubernetes
   reference: https://raw.githubusercontent.com/.../mongo-db.yaml
 - alias: nodejs-app
   type: kubernetes
   reference: https://raw.githubusercontent.com/.../nodejs-app.yaml
   entrypoints:
     - command: ['sleep']
       args: ['infinity']
commands:
 - name: run
   actions:
     - type: exec
       component: nodejs-app
       command: cd ${CHE_PROJECTS_ROOT}/nodejs-mongo-app/EmployeeDB/ && npm install && sed -i -- ''s/localhost/mongo/g'' app.js && node app.js

Use this devfile to create and start a workspace with the crwctl command:

$ crwctl worspace:start --devfile <devfile-path>

The run command added to the devfile is available as a task in Che-Theia from the command palette. When executed, the command starts the Node.JS application.

3.4.2. Adding a OpenShift application to an existing workspace using the dashboard

This procedure demonstrates how to modify an existing workspace and import the OpenShift application using the newly created devfile.

Prerequisites

Procedure

  1. After the creation of a workspace, use the Workspace menu and then the Configure workspace icon to manage the workspace.

    configure workspace
  2. To modify the workspace details, use the Devfile tab. The workspace details are displayed in this tab in the devfile format.

    configure workspace devfile
  3. To add a OpenShift component, use the Devfile editor on the dashboard.
  4. For the changes to take effect, save the devfile and restart the CodeReady Workspaces workspace.

3.4.3. Generating a devfile from an existing OpenShift application

This procedure demonstrates how to generate a devfile from an existing OpenShift application using the crwctl tool.

Prerequisites

Procedure

  1. Use the crwctl devfile:generate command to generate a devfile:

    $ crwctl devfile:generate
    • The user can also use the crwctl devfile:generate command to generate a devfile from, for example, the NodeJS-MongoDB application.

      The following example generates a devfile that includes the NodeJS component:

      $ crwctl devfile:generate --selector="app=nodejs"
      apiVersion: 1.0.0
      metadata:
        name: crwctl-generated
      components:
        - type: kubernetes
          alias: app=nodejs
          referenceContent: |
            kind: List
            apiVersion: v1
            metadata:
              name: app=nodejs
            items:
              - apiVersion: apps/v1
                kind: Deployment
                metadata:
                  labels:
                    app: nodejs
                  name: web
      (...)

      The Node.js application YAML definition is available in the devfile, inline, using the referenceContent attribute.

    • To include support for a language, use the --language parameter:

      $ crwctl devfile:generate --selector="app=nodejs" --language="typescript"
      apiVersion: 1.0.0
      metadata:
        name: crwctl-generated
      components:
        - type: kubernetes
          alias: app=nodejs
          referenceContent: |
            kind: List
            apiVersion: v1
      (...)
        - type: chePlugin
          alias: typescript-ls
          id: che-incubator/typescript/latest
  2. Use the generated devfile to start a CodeReady Workspaces workspace with crwctl.

3.5. Remotely accessing workspaces

This section describes how to remotely access CodeReady Workspaces workspaces outside of the browser.

CodeReady Workspaces workspaces exist as containers and are, by default, modified from a browser window. In addition to this, there are the following methods of interacting with a CodeReady Workspaces workspace:

  • Opening a command line in the workspace container using the OpenShift command-line tool, kubectl
  • Uploading and downloading files using the kubectl tool

3.5.1. Remotely accessing workspaces using the OpenShift command-line tool

To access CodeReady Workspaces workspaces remotely using OpenShift command-line tool (kubectl), follow the instructions in this section.

Note

The kubectl tool is used in this section to open a shell and manage files in a CodeReady Workspaces workspace. Alternatively, it is possible to use the oc OpenShift command-line tool.

Prerequisites

  • The kubectl tool is available. See OpenShift website.
  • Verify the installation of kubectl using the oc version command:

    $ oc version
    Client Version: version.Info{Major:"1", Minor:"15", GitVersion:"v1.15.0", GitCommit:"e8462b5b5dc2584fdcd18e6bcfe9f1e4d970a529", GitTreeState:"clean", BuildDate:"2019-06-19T16:40:16Z", GoVersion:"go1.12.5", Compiler:"gc", Platform:"darwin/amd64"}
    Server Version: version.Info{Major:"1", Minor:"15", GitVersion:"v1.15.0", GitCommit:"e8462b5b5dc2584fdcd18e6bcfe9f1e4d970a529", GitTreeState:"clean", BuildDate:"2019-06-19T16:32:14Z", GoVersion:"go1.12.5", Compiler:"gc", Platform:"linux/amd64"}

    For versions 1.5.0 or higher, proceed with the steps in this section.

Procedure

  1. Use the exec command to open a remote shell.
  2. To find the name of the OpenShift project and the Pod that runs the CodeReady Workspaces workspace:

    $ oc get pod -l che.workspace_id --all-namespaces
    NAMESPACE   NAME                                               READY   STATUS    RESTARTS   AGE
    che         workspace7b2wemdf3hx7s3ln.maven-74885cf4d5-kf2q4   4/4     Running   0          6m4s

In the example above, the Pod name is workspace7b2wemdf3hx7s3ln.maven-74885cf4d5-kf2q4, and the project is codeready.

  1. To find the name of the container:

    $ NAMESPACE=che
    $ POD=workspace7b2wemdf3hx7s3ln.maven-74885cf4d5-kf2q4
    $ oc get pod ${POD} -o custom-columns=CONTAINERS:.spec.containers[*].name
    CONTAINERS
    maven,che-machine-execpau,theia-ide6dj,vscode-javaw92
  2. When you have the project, pod name, and the name of the container, use the kubectl command to open a remote shell:

    $ NAMESPACE=che
    $ POD=workspace7b2wemdf3hx7s3ln.maven-74885cf4d5-kf2q4
    $ CONTAINER=maven
    $ oc exec -ti -n ${NAMESPACE} ${POD} -c ${CONTAINER} bash
    user@workspace7b2wemdf3hx7s3ln $
  3. From the container, execute the build and run commands (as if from the CodeReady Workspaces workspace terminal):

    user@workspace7b2wemdf3hx7s3ln $ mvn clean install
    [INFO] Scanning for projects...
    (...)

Additional resources

3.5.2. Downloading and uploading a file to a workspace using the command-line interface

This procedure describes how to use the kubectl tool to download or upload files remotely from or to an Red Hat CodeReady Workspaces workspace.

Prerequisites

Procedure

  • To download a local file named downloadme.txt from a workspace container to the current home directory of the user, use the following in the CodeReady Workspaces remote shell.

    $ REMOTE_FILE_PATH=/projects/downloadme.txt
    $ NAMESPACE=che
    $ POD=workspace7b2wemdf3hx7s3ln.maven-74885cf4d5-kf2q4
    $ CONTAINER=maven
    $ oc cp ${NAMESPACE}/${POD}:${REMOTE_FILE_PATH} ~/downloadme.txt -c ${CONTAINER}
  • To upload a local file named uploadme.txt to a workspace container in the /projects directory:
$ LOCAL_FILE_PATH=./uploadme.txt
$ NAMESPACE=che
$ POD=workspace7b2wemdf3hx7s3ln.maven-74885cf4d5-kf2q4
$ CONTAINER=maven
$ oc cp ${LOCAL_FILE_PATH} ${NAMESPACE}/${POD}:/projects -c ${CONTAINER}

Using the preceding steps, the user can also download and upload directories.

3.6. Creating a workspace from code sample

Every stack includes a sample codebase, which is defined by the devfile of the stack. This section explains how to create a workspace from this code sample in a sequence of three procedures.

  1. Creating a workspace from the user dashboard:

    1. Using the Get Started view.
    2. Using the Custom Workspace view.
  2. Changing the configuration of the workspace to add code sample.
  3. Running an existing workspace from the user dashboard.

For more information about devfiles, see Configuring a CodeReady Workspaces workspace using a devfile.

3.6.1. Creating a workspace from Get Started view of User Dashboard

This section describes how to create a workspace from the User Dashboard.

Prerequisites

Procedure

  1. Navigate to the CodeReady Workspaces Dashboard. See Navigating CodeReady Workspaces using the Dashboard.
  2. In the left navigation panel, go to Get Started.
  3. Click the Get Started tab.
  4. In the gallery, there is list of samples that may be used to build and run projects.

    Select a stack from the gallery
    Changing resource limits

    Changing the memory requirements is only possible from the devfile.

  5. Start the workspace: click the chosen stack card.

    Create and Open
New workspace name

Workspace name can be auto-generated based on the underlying devfile of the stack. Generated names always consist of the devfile metadata.generateName property as the prefix and four random characters.

3.6.2. Creating a workspace from Custom Workspace view of User Dashboard

This section describes how to create a workspace from the User Dashboard.

Prerequisites

Procedure

  1. Navigate to the CodeReady Workspaces Dashboard. See Navigating CodeReady Workspaces using the Dashboard.
  2. In the left navigation panel, go to Get Started.
  3. Click the Custom Workspace tab.
  4. Define a Name for the workspace.

    New workspace name

    Workspace name can be auto-generated based on the underlying devfile of the stack. Generated names always consist of the devfile metadata.generateName property as the prefix and four random characters.

  5. In the Devfile section, select the devfile template that will be used to build and run projects.

    Select a devfile from the list
    Changing resource limits

    Changing the memory requirements is only possible from the devfile.

  6. Start the workspace: click the Create & Open button at the bottom of the form:

    Create and Open

3.6.3. Changing the configuration of an existing workspace

This section describes how to change the configuration of an existing workspace from the User Dashboard.

Prerequisites

Procedure

  1. Navigate to the CodeReady Workspaces Dashboard. See Navigating CodeReady Workspaces using the dashboard.
  2. In the left navigation panel, go to Workspaces.
  3. Click the name of a workspace to navigate to the configuration overview page.
  4. Click the Overview tab and execute following actions:

    • Change the Workspace name.
    • Select Storage Type.
    • Export the workspace configuration to a file or private cloud.
    • Delete the workspace.

      Workspace configuration overview
  5. In the Projects section, choose the projects to integrate in the workspace.

    1. Click the Add Project button and do one of the following:

      1. Enter the project Git repository URL to integrate in the workspace:

        Add project by URL to workspace
      2. Connect your GitHub account and select projects to integrate:

        Add project from GitHub to workspace
    2. Click the Add button.
  6. In the Plugins section, choose the plug-ins to integrate in the workspace.

    Example

    Start with a generic Java-based stack, then add support for Node.js or Python.

  7. In the Editors section, choose the editors to integrate in the workspace. The CodeReady Workspaces 2.3 editor is based on Che-Theia.
  8. From the Devfile tab, edit YAML configuration of the workspace. See the Devfile reference.

    Example: add commands
    YAML configuration
    Example: add a project

    To add a project into the workspace, add or edit the following section:

    projects:
      - name: che
        source:
          type: git
          location: 'https://github.com/eclipse/che.git'

3.6.4. Running an existing workspace from the User Dashboard

This section describes how to run an existing workspace from the User Dashboard.

3.6.4.1. Running an existing workspace from the User Dashboard with the Run button

This section describes how to run an existing workspace from the User Dashboard using the Run button.

Prerequisites

Procedure

  1. Navigate to the CodeReady Workspaces Dashboard. See Navigating CodeReady Workspaces using the dashboard.
  2. In the left navigation panel, navigate to Workspaces.
  3. Click on the name of a non-running workspace to navigate to the overview page.
  4. Click on the Run button in the top right corner of the page.
  5. The workspace is started.
  6. The browser does not navigates to the workspace.

3.6.4.2. Running an existing workspace from the User Dashboard using the Open button

This section describes how to run an existing workspace from the User Dashboard using the Open button.

Prerequisites

Procedure

  1. Navigate to the CodeReady Workspaces Dashboard. See Navigating CodeReady Workspaces using the dashboard.
  2. In the left navigation panel, navigate to Workspaces.
  3. Click on the name of a non-running workspace to navigate to the overview page.
  4. Click on the Open button in the top right corner of the page.
  5. The workspace is started.
  6. The browser navigates to the workspace.

3.6.4.3. Running an existing workspace from the User Dashboard using the Recent Workspaces

This section describes how to run an existing workspace from the User Dashboard using the Recent Workspaces.

Prerequisites

Procedure

  1. Navigate to the CodeReady Workspaces Dashboard. See Navigating CodeReady Workspaces using the dashboard.
  2. In the left navigation panel, in the Recent Workspaces section, right-click the name of a non-running workspace and click Run in the contextual menu to start it.

    Run from Recent Workspaces

3.7. Creating a workspace by importing the source code of a project

This section describes how to create a new workspace to edit an existing codebase.

Prerequisites

You can do it in two ways before starting a workspace:

To create a new workspace to edit an existing codebase, use one of the following three methods after you have started the workspace:

3.7.1. Select a sample from the Dashboard, then change the devfile to include your project

  • In the left navigation panel, go to Get Started.
  • Click the Custom Workspace tab if it’s not already selected.
  • In the Devfile section, select the devfile template that will be used to build and run projects.

    Select a devfile from the list
  • In the Devfile editor, update projects section:

    Update projects section of the devfile
    Example: add a project

    To add a project into the workspace, add or edit the following section:

    projects:
      - name: che
        source:
          type: git
          location: 'https://github.com/eclipse/che.git'

    See the Devfile reference.

  • To open the workspace, click the Create & Open button.

3.7.2. Importing from the Dashboard into an existing workspace

  1. Import the project. There are at least two ways to import a project using the Dashboard.

    • From the Dashboard, select Workspaces, then select your workspace by clicking on its name. This will link you to the workspace’s Overview tab.
    • Or, use the gear icon. This will link to the Devfile tab where you can enter your own YAML configuration.
  2. Click the Projects tab.
  3. Click Add Project. You can then import project by a repository Git URL or from GitHub.
Add projects to workspace
Note

You can add a project to a non-running workspace, but you must start the workspace to delete it.

3.7.2.1. Editing the commands after importing a project

After you have a project in your workspace, you can add commands to it. Adding commands to your projects allows you to run, debug, or launch your application in a browser.

To add commands to the project:

  1. Open the workspace configuration in the Dashboard, then select the Devfile tab.

    Add commands to workspace
  2. Open the workspace.
  3. To run a command, select Terminal > Run Task from the main menu.

    Run task
  4. To configure commands, select Terminal > Configure Tasks from the main menu.

    Configure tasks

3.7.3. Importing to a running workspace using the Git: Clone command

To import to a running workspace using the Git: Clone command:

  1. Start a workspace, then use the Git: Clone command from the command palette or the Welcome screen to import a project to a running workspace.

    Welcome screen
  2. Open the command palette using F1 or CTRL-SHIFT-P, or from the link in the Welcome screen.

    Invoke git clone command
  3. Enter the path to the project you want to clone.

    Configure git clone command

3.7.4. Importing to a running workspace with git clone in a terminal

In addition to the approaches above, you can also start a workspace, open a Terminal, and type git clone to pull code.

Run git clone in a terminal
Note

Importing or deleting workspace projects in the terminal does not update the workspace configuration, and the change is not reflected in the Project and Devfile tabs in the dashboard.

Similarly, if you add a project using the Dashboard, then delete it with rm -fr myproject, it may still appear in the Projects or Devfile tab.

3.8. Configuring workspace exposure strategies

The following section describes how to configure workspace exposure strategies of a CodeReady Workspaces server and ensure that applications running inside are not vulnerable to outside attacks.

The workspace exposure strategy is configured per CodeReady Workspaces server, using the che.infra.kubernetes.server_strategy configuration property or the CHE_INFRA_KUBERNETES_SERVER__STRATEGY environment variable.

The supported values for che.infra.kubernetes.server_strategy are:

  • multi-host

For the multi-host strategy, set the che.infra.kubernetes.ingress.domain (or the CHE_INFRA_KUBERNETES_INGRESS_DOMAIN environment variable) configuration property to the domain name that will host workspace component subdomains.

3.8.1. Workspace exposure strategies

Specific components of workspaces need to be made accessible outside of the OpenShift cluster. This is typically the user interface of the workspace’s IDE, but it can also be the web UI of the application being developed. This enables developers to interact with the application during the development process.

CodeReady Workspaces supports three ways to make workspace components available to the users, also referred to as strategies:

  • multi-host strategy

The strategies define whether new subdomains are created for components of the workspace, and what hosts these components are available on.

3.8.1.1. Multi-host strategy

With this strategy, each workspace component is assigned a new subdomain of the main domain configured for the CodeReady Workspaces server. On OpenShift, this is the only possible strategy, and manual configuration of the workspace exposure strategy is therefore always ignored.

This strategy is the easiest to understand from the perspective of component deployment because any paths present in the URL to the component are received as they are by the component.

On a CodeReady Workspaces server secured using the Transport Layer Security (TLS) protocol, creating new subdomains for each component of each workspace requires a wildcard certificate to be available for all such subdomains for the CodeReady Workspaces deployment to be practical.

3.8.2. Security considerations

This section explains the security impact of using different CodeReady Workspaces workspace exposure strategies.

All the security-related considerations in this section are only applicable to CodeReady Workspaces in multiuser mode. The single user mode does not impose any security restrictions.

3.8.2.1. JSON web token (JWT) proxy

All CodeReady Workspaces plug-ins, editors, and components can require authentication of the user accessing them. This authentication is performed using a JSON web token (JWT) proxy that functions as a reverse proxy of the corresponding component, based on its configuration, and performs the authentication on behalf of the component.

The authentication uses a redirect to a special page on the CodeReady Workspaces server that propagates the workspace and user-specific authentication token (workspace access token) back to the originally requested page.

The JWT proxy accepts the workspace access token from the following places in the incoming requests, in the following order:

  1. The token query parameter
  2. The Authorization header in the bearer-token format
  3. The access_token cookie

3.8.2.2. Secured plug-ins and editors

CodeReady Workspaces users do not need to secure workspace plug-ins and workspace editors (such as Che-Theia). This is because the JWT proxy authentication is transparent to the user and is governed by the plug-in or editor definition in their meta.yaml descriptors.

3.8.2.3. Secured container-image components

Container-image components can define custom endpoints for which the devfile author can require CodeReady Workspaces-provided authentication, if needed. This authentication is configured using two optional attributes of the endpoint:

  • secure - A boolean attribute that instructs the CodeReady Workspaces server to put the JWT proxy in front of the endpoint. Such endpoints have to be provided with the workspace access token in one of the several ways explained in Section 3.8.2.1, “JSON web token (JWT) proxy”. The default value of the attribute is false.
  • cookiesAuthEnabled - A boolean attribute that instructs the CodeReady Workspaces server to automatically redirect the unauthenticated requests for current user authentication as described in Section 3.8.2.1, “JSON web token (JWT) proxy”. Setting this attribute to true has security consequences because it makes Cross-site request forgery (CSRF) attacks possible. The default value of the attribute is false.

3.8.2.4. Cross-site request forgery attacks

Cookie-based authentication can make an application secured by a JWT proxy prone to Cross-site request forgery (CSRF) attacks. See the Cross-site request forgery Wikipedia page and other resources to ensure your application is not vulnerable.

3.8.2.5. Phishing attacks

An attacker who is able to create an Ingress or route inside the cluster with the workspace that shares the host with some services behind a JWT proxy, the attacker may be able to create a service and a specially forged Ingress object. When such a service or Ingress is accessed by a legitimate user that was previously authenticated with a workspace, it can lead to the attacker stealing the workspace access token from the cookies sent by the legitimate user’s browser to the forged URL. To eliminate this attack vector, configure OpenShift to disallow setting the host of an Ingress.

3.9. Mounting a secret as a file or an environment variable into a workspace container

Secrets are 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 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 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.

    Note

    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 OpenShift mounting mechanism, but it requires additional annotations and labeling for a proper bound of a secret with the required CodeReady Workspaces workspace container.

3.9.1. Mounting a secret as a file into a workspace container

Warning

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

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

Prerequisites

Procedure

  1. Create a new OpenShift secret in the OpenShift project where a CodeReady Workspaces 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 CodeReady Workspaces. The default labels are:
    • app.kubernetes.io/part-of: che.eclipse.org
    • app.kubernetes.io/component: workspace-secret:

      Note

      Note that the following example describes variations in the usage of the target-container annotation in versions 2.1 and 2.2 of Red Hat CodeReady Workspaces.

      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 CodeReady Workspaces workspace, but this is applicable only for the CodeReady Workspaces version 2.1.

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

      Since the CodeReady Workspaces version 2.2, 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: {prod-home}/.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: {prod-home}/.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/jboss/.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.

3.9.2. Mounting a secret as an environment variable into a workspace container

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

Prerequisites

Procedure

  1. Create a new OpenShift secret in the k8s project where a CodeReady Workspaces 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 CodeReady Workspaces. By default, it is a set of two labels:
    • app.kubernetes.io/part-of: che.eclipse.org
    • app.kubernetes.io/component: workspace-secret:

      Note

      Note that the following example describes variations in the usage of the target-container annotation in versions 2.1 and 2.2 of Red Hat CodeReady Workspaces.

      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 CodeReady Workspaces workspace, but this is applicable only for the CodeReady Workspaces version 2.1.

      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 container named maven.

      Since the CodeReady Workspaces version 2.2, 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/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 data item, 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 workpsace containers.

      Note

      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.

3.9.3. Mounting a git credetials store into a workspace container

This section describes how to mount git credetials store as secret from the user’s project into the file in single-workspace or multiple-workspace containers of CodeReady Workspaces.

Prerequisites

Procedure

  1. Prepare git credential file in format https://git-scm.com/docs/git-credential-store#_storage_format.
  2. Encode content of the file to the base64 format.
  3. Create a new OpenShift secret in the OpenShift project where a CodeReady Workspaces 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 CodeReady Workspaces. The default labels are:
    • app.kubernetes.io/part-of: che.eclipse.org
    • app.kubernetes.io/component: workspace-secret:

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

OpenShift annotations and labels are tools used by libraries, tools, and other clients, to attach arbitrary non-identifying metadata to 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 OpenShift objects internally.

This section describes OpenShift annotation values used in the process of OpenShift secret mounting in a CodeReady Workspaces workspace.

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

  • che.eclipse.org/target-container: Valid till the version 2.1. The name of the mounting container. If the name is not defined, the secret mounts into all user’s containers of the CodeReady Workspaces workspace.
  • che.eclipse.org/automount-workspace-secret: Introduced in the version 2.2.. The main mount selector. When set to true, the secret mounts into all user’s containers of the CodeReady Workspaces 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: This item 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.