Chapter 3. Developer workspaces

Red Hat CodeReady Workspaces provides developer workspaces with everything you need to code, build, test, run, and debug applications:

  • Project source code
  • Web-based integrated development environment (IDE)
  • Tool dependencies needed by developers to work on a project
  • 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 easy to share.

Important

By default, it is possible to run only one workspace at a time. To increase the number of concurrent workspaces a user can run, update the CheCluster:

$ oc patch checluster/codeready-workspaces -n openshift-workspaces --type=merge \
-p '{ "spec": { "server": { "customCheProperties": { "CHE_LIMITS_USER_WORKSPACES_RUN_COUNT": "-1" } } } }'

For additional information, see: https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.12/html-single/installation_guide/index#users-workspace-limits.

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.

Capable of being versioned

No

Yes. Devfiles exist with project source code.

Accessible from anywhere

No. Installation is needed.

Yes. Only requires a browser.

Start a CodeReady Workspaces workspace:

Use the Dashboard to discover CodeReady Workspaces 2.12:

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

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

3.1. Creating a workspace from a code sample

You can create a new workspace by using one of the code samples included in CodeReady Workspaces.

Prerequisites

Procedure

  1. Go to the Dashboard of CodeReady Workspaces.
  2. In the left navigation panel, click Create Workspace to go to the Quick Add tab that contains code samples.
  3. Select a sample to start a new workspace.
  4. Wait for the initialized workspace to start and for the IDE to open.
Note

CodeReady Workspaces generates a unique name for a new workspace from the devfile’s metadata.generateName property followed by four random characters. You can edit the name of the workspace when it is created.

3.2. Creating a workspace from a template devfile

You can create a new workspace by using one of the devfile templates included in CodeReady Workspaces.

For information about devfiles, see Section 4.2, “Authoring a devfile 2.0.0”.

Prerequisites

Procedure

  1. Go to the Dashboard of CodeReady Workspaces.
  2. In the left navigation panel, click Create Workspace.
  3. Go to the Custom Workspace tab.
  4. Enter a workspace name.

    Note

    If you do not enter a Workspace Name for your workspace, CodeReady Workspaces generates a unique name for a new workspace from the devfile’s metadata.generateName property followed by four random characters.

  5. Select a devfile template from the drop-down list.
  6. Click Create & Open.
  7. Wait for the initialized workspace to start and for the IDE to open.

3.3. Creating a workspace from remote devfile

For quick and easy CodeReady Workspaces workspace creation, use a factory link.

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

This section describes how to start a CodeReady Workspaces workspace using a factory URL. The factory URL is a link pointing CodeReady Workspaces to a Git source repository containing a devfile.

The factory URL exist in two forms:

  • the short form /#$URL
  • long /f?url=$URL form that supports additional configuration parameters used in previous versions of CodeReady Workspaces

Prerequisites

Procedure

3.3.2. 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

  • A running instance of Red Hat CodeReady Workspaces. To install an instance of Red Hat CodeReady Workspaces, see Installing CodeReady Workspaces.
  • The devfile.yaml or .devfile.yaml file is located in the root folder of a Git repository, on a specific branch of the user’s choice that is accessible over HTTPS. See Section 4.2, “Authoring a devfile 2.0.0” for detailed information about creating and using devfiles.

Procedure

Execute the workspace by opening the following URL: \https://codeready-<openshift_deployment_name>.<domain_name>/#<GitHubBranch>

Example

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

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

3.3.3. 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>/#https://<yourhosturl>/devfile.yaml

3.3.4. Overriding devfile values using factory parameters

You can override values in the following sections of a remote devfile:

  • apiVersion
  • metadata
  • projects
  • attributes

You can override the values by using additional factory parameters.

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 3.3. 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://workspaces.openshift.com/f?url=<repository-url>&override.metadata.generateName=myprefix

The resulting workspace has the following devfile model:

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

Example 3.4. 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 the source branch value, use the following factory URL:

https://workspaces.openshift.com/f?url=<repository-url>&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 3.5. 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 the persistVolumes attribute value, use the following factory URL:

https://workspaces.openshift.com/f?url=<repository-url>&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. You can use dot-separated names:

https://workspaces.openshift.com/f?url=<repository-url>&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:
...

Verification steps

  1. In CodeReady Workspaces Dashboard, navigate to the Devfile tab of the newly created workspace and inspect the content.

3.3.5. Allowing users to define workspace deployment labels and annotations

This section describes how to customize workspace deployment labels and annotation using factory parameters.

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&workspaceDeploymentLabels=<url_encoded_comma_separated_key_values>&workspaceDeploymentAnnotations=<url_encoded_comma_separated_key_values override>

Example 3.6. Example of overriding the deployment labels

Consider the following labels to add:

ike.target=preference-v1
ike.session=test

To add or override labels, use the following factory URL:

https://workspaces.openshift.com/f?url=<repository-url>&workspaceDeploymentLabels=ike.target%3Dpreference-v1%2Cike.session%3Dtest

The resulting workspace has the following deployment labels:

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    deployment.kubernetes.io/revision: "1"
  creationTimestamp: "2020-10-27T14:03:26Z"
  generation: 1
  labels:
    che.component.name: che-docs-dev
    che.original_name: che-docs-dev
    che.workspace_id: workspacegln2g1shejjufpkd
    ike.session: test
    ike.target: preference-v1
  name: workspacegln2g1shejjufpkd.che-docs-dev
  namespace: opentlc-mgr-che
  resourceVersion: "107516"
spec:
...

Example 3.7. Example of overriding the deployment annotations

Consider the following annotations to add:

ike.A1=preference-v1
ike.A=test

To add or override annotations, use the following factory URL:

https://workspaces.openshift.com/f?url=<repository-url>&workspaceDeploymentAnnotations=ike.A1%3Dpreference-v1%2Cike.A%3Dtest

The resulting workspace has the following deployment annotations:

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    deployment.kubernetes.io/revision: "1"
    ike.A: test
    ike.A1: preference-v1
  creationTimestamp: "2020-10-28T09:58:52Z"
  generation: 1
  labels:
    che.component.name: che-docs-dev
    che.original_name: che-docs-dev
    che.workspace_id: workspacexrtf710v64rl5ouz
  name: workspacexrtf710v64rl5ouz.che-docs-dev
  namespace: opentlc-mgr-che
  resourceVersion: "213191"
...

Verification steps

To display the deployment labels and annotations:

  1. Get the name of the user’s namespace:

  1. Using CodeReady Workspaces Dashboard, move to the Workspaces tab and read the name of the OpenShift namespace field.

  1. Log in to the cluster:

    1. Retrieve the CodeReady Workspaces cluster URL from the checluster CR (Custom Resource), run:

      $ oc get checluster --output jsonpath='{.items[0].status.cheURL}'
    2. Log in:

      $ oc login -u <username> -p <password> <cluster_URL>

  1. Display the deployment labels and annotations for all deployments in the project using the OpenShift namespace name from the first step:

    $ oc get deployment -n <NAMESPACE> -o=custom-columns="NAMESPACE:.metadata.namespace,NAME:.metadata.name,LABELS:.metadata.labels,ANNOTATIONS:.metadata.annotations"

3.3.6. Allowing users to define workspace creation strategy

As a developer, you can configure CodeReady Workspaces to create a new workspace each time it accepts a factory URL, or to reuse the existing workspace if a user already has one.

CodeReady Workspaces supports the following options:

  • perclick: The default strategy, which creates a new workspace each time a given factory URL is accepted.
  • peruser: Initially, a workspace is created using a factory URL. Other user’s calls then re-use the particular workspace created by the factory URL (1 factory = 1 workspace).

Prerequisites

Procedure

  • Run the workspace by opening the factory URL and specify the additional strategy parameter:

    \https://codeready-<openshift_deployment_name>.<domain_name>/f?url=<GIT_REPOSITORY_URL>&policies.create=<value>

3.4. 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:create parameter with the crwctl tool as follows:
$ crwctl workspace:create --name=<WORKSPACE_NAME> \ 1
--devfile=devfile.yaml --start \
-n openshift-workspaces
1
The workspace name to create.
Note

If --devfile flag is omitted, the crwctl looks for devfile.yaml or devfile.yml files in the current directory to create a workspace from.

3.5. Importing the source code of a project into a workspace

With CodeReady Workspaces, you can import and work on a project’s current codebase in a workspace.

You can import a project’s codebase into a workspace by using any of the following options:

Prerequisites

3.5.1. Importing a project when creating a workspace

You can import a project’s codebase while creating a new workspace: by using a devfile template and the project’s URL.

Procedure

  1. Go to the Dashboard of CodeReady Workspaces.
  2. In the left navigation panel, click Create Workspace.
  3. Go to the Custom Workspace tab.
  4. Enter a workspace name.

    Note

    If you do not enter a Workspace Name for your workspace, CodeReady Workspaces generates a unique name for a new workspace from the devfile’s metadata.generateName property followed by four random characters.

  5. Select a devfile template from the drop-down list.

    Select a devfile from the list
  6. Edit the projects section of the template devfile displayed in the devfile editor on the page.

    Edit the projects section of the devfile

    Example 3.8. Editing the projects section of a devfile

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

    For more information about devfiles, see Section 4.2, “Authoring a devfile 2.0.0”.

  7. Click Create & Open.
  8. Wait for the initialized workspace to start and for the IDE to open.

3.5.2. Importing a project into a created workspace

You can import a project’s codebase into a created workspace by editing its devfile.

Prerequisites

  • A running workspace

Procedure

  1. Go to the Dashboard of CodeReady Workspaces.
  2. Under RECENT WORKSPACES, hover over the name of the workspace to which you will import the project.
  3. Click the three dots.
  4. Select Edit Workspace.
  5. In the Devfile tab, edit the projects section of the devfile in the editor on the page.

    Example 3.9. Editing the projects section of a devfile

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

    For more information about devfiles, see Section 4.2, “Authoring a devfile 2.0.0”.

  6. Click Save.

3.5.2.1. Adding commands to an imported project

You can add commands to a project that will enable running, debugging, or starting an application in a browser.

Prerequisites

  • A workspace with a project in it

Procedure

  1. Go to the Dashboard of CodeReady Workspaces.
  2. Under RECENT WORKSPACES, hover over the name of the workspace to which you will import the project.
  3. Click the three dots next to the workspace name.
  4. Select Edit Workspace.
  5. In the Devfile tab, edit the commands section of the devfile in the editor on the page.
  6. Click Save.
  7. Open the workspace.
  8. To run a command, select Terminal > Run Task from the main menu.

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

    Configure tasks

3.5.3. Importing a project with Git: Clone in the GUI

You can import a project’s codebase into a running workspace with the Git: Clone command in the graphic user interface of CodeReady Workspaces.

Prerequisites

  • A started workspace

Procedure

  1. Select the Git: Clone command on the Welcome screen or from the command palette:

    • On the Welcome screen, click the Git: Clone link.

      Welcome screen
    • To open the command palette, press F1 or Ctrl+Shift+P (Cmd+Shift+P on macOS).

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

    Configure git clone command

3.5.4. Importing a project with git clone in a terminal

You can use the command line to import a project’s codebase into a running workspace.

Prerequisites

  • A running workspace

Procedure

  1. Open a terminal inside the running workspace.
  2. Type the git clone command 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 IDE does not reflect the changes in the Devfile tab in the dashboard.

Similarly, when you add a project in the Dashboard and then delete the project with the rm -fr myproject command, the project may still appear in the Devfile tab.

3.6. Configuring a CodeReady Workspaces 2.12 workspace

3.6.1. 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 Section 1.1, “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.
    • Review project.
  5. From the Devfile tab, edit YAML configuration of the workspace. See Section 4.2, “Authoring a devfile 2.0.0”.

3.6.2. Adding projects to your workspace

Prerequisites

  • A running instance of CodeReady Workspaces. To install an instance of CodeReady Workspaces, see Installing CodeReady Workspaces.
  • An existing workspace defined on this instance of CodeReady Workspaces.

Procedure

To add a project to your workspace:

  1. Navigate to the Workspaces page and click the workspace, which is about to be updated.
  2. Open the Devfile tab.
  3. In the Devfile editor, add a projects section with desired project.

    Edit Devfile Content
  4. Once the project is added, click the Save button to save this workspace configuration.

    For demonstration example, see below:

    Example - Adding a .git project into a workspace using a devfile

    In the following instance, the project crw acts as the example of a user’s project. A user specifies this project using the name attribute of a devfile. The location attribute defines the source repository represented by an URL to a Git repository or ZIP archive.

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

    projects:
      - name: <crw>
        source:
          type: git
          location: 'https://github.com/<github-organization>/<crw>.git'

    For additional information, see the Section 4.1.5, “Devfile reference” section.

3.6.3. Configuring the workspace tools

3.6.3.1. Adding plug-ins

Prerequisites

  • A running instance of CodeReady Workspaces. To install an instance of CodeReady Workspaces, see Installing CodeReady Workspaces.
  • An existing workspace defined on this instance of CodeReady Workspaces.

Procedure

To add plug-ins to your workspace:

  1. Click the Devfile tab.
  2. Add the desired chePlugin component and click the Save button.

    Note

    To see a list of available plugins, activate the completion feature by pressing Ctrl+Space.

    workspace add plugin

3.6.3.2. Defining the workspace editor

Prerequisites

  • A running instance of CodeReady Workspaces. To install an instance of CodeReady Workspaces, see Installing CodeReady Workspaces.
  • An existing workspace defined on this instance of CodeReady Workspaces.

Procedure

To define the editor to use with the workspace:

  1. Click the Devfile tab.
  2. Add the desired cheEditor component and click the Save button.

    Note

    To see a list of available plugins, activate the completion feature by pressing Ctrl+Space. The recommended editor for CodeReady Workspaces 2.12 is Che-Theia.

    workspace add editor

3.7. Running an existing workspace from the user dashboard

This section describes how to run an existing workspace from the user dashboard.

3.7.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

  • A running instance of CodeReady Workspaces. To install an instance of CodeReady Workspaces, see Installing CodeReady Workspaces.
  • An existing workspace defined on this instance of CodeReady Workspaces.

Procedure

  1. Navigate to the CodeReady Workspaces Dashboard. See Section 1.1, “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.

    The workspace is started, and a browser does not navigates to the workspace.

3.7.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

  • A running instance of CodeReady Workspaces. To install an instance of CodeReady Workspaces, see Installing CodeReady Workspaces.
  • An existing workspace defined on this instance of CodeReady Workspaces.

Procedure

  1. Navigate to the CodeReady Workspaces Dashboard. See Section 1.1, “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.

    The workspace is started, and a browser navigates to the workspace.

3.7.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

  • A running instance of CodeReady Workspaces. To install an instance of CodeReady Workspaces, see Installing CodeReady Workspaces.
  • An existing workspace defined on this instance of CodeReady Workspaces.

Procedure

  1. Navigate to the CodeReady Workspaces Dashboard. See Section 1.1, “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.

3.8. Importing OpenShift applications into a workspace

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

3.8.1. Including a OpenShift application in a workspace devfile definition

This procedure describes how to define a CodeReady Workspaces workspace devfile to include a OpenShift application.

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}

Prerequisites

Procedure

  1. Create the simplest devfile:

    apiVersion: 1.0.0
    metadata:
     name: minimal-workspace 1
    1
    Specify the name minimal-workspace. 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, including, for example, the terminal.
  2. To add OpenShift applications to a workspace, modify the devfile and add the Kubernetes component type.

    For example, to embed the NodeJS-Mongo application in the minimal-workspace:

    apiVersion: 1.0.0
    metadata:
     name: minimal-workspace
    components:
     - type: openshift
       reference: https://raw.githubusercontent.com/.../mongo-db.yaml
     - alias: nodejs-app
       type: openshift
       reference: https://raw.githubusercontent.com/.../nodejs-app.yaml
       entrypoints:
         - command: ['sleep']  1
           args: ['infinity']
    1
    The sleep infinity command is added as the entrypoint of the Node.js application. The command prevents the application from starting at the workspace start phase. This configuration allows the user to start the application when needed for testing or debugging purposes.
  3. Add the commands in the devfile to make it easier for a developer to test the application:

    apiVersion: 1.0.0
    metadata:
      name: nodejs-with-db
    projects:
      - name: nodejs-mongo-app
        source:
          type: git
          location: 'https://github.com/ijason/NodeJS-Sample-App.git'
          commitId: 187d468 # refers to the last commitId the project compiles (with express3)
    components:
      - type: openshift
        reference: https://raw.githubusercontent.com/redhat-developer/devfile/master/samples/web-nodejs-with-db-sample/mongo-db.yaml
      - alias: nodejs-app
        type: openshift
        reference: https://raw.githubusercontent.com/redhat-developer/devfile/master/samples/web-nodejs-with-db-sample/nodejs-app.yaml
    commands:
      - name: run 1
        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
    1
    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.
  4. Use the devfile to create and start a workspace:

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

Additional resources

3.8.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

  • A running instance of CodeReady Workspaces. To install an instance of CodeReady Workspaces, see Installing CodeReady Workspaces.
  • An existing workspace defined on this instance of CodeReady Workspaces.

Procedure

  1. After the creation of a workspace, use the Workspace menu and then click on the desired workspace.
  2. Modify the workspace devfile, use the Devfile tab.
  3. Add a OpenShift component.
  4. For the changes to take effect, save the devfile and restart the CodeReady Workspaces workspace.

3.8.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. To generate a devfile, use:

    $ crwctl devfile:generate
    • It is also possible to generate a devfile from, for example, the NodeJS-MongoDB application that includes the NodeJS component, using the crwctl devfile:generate command:

      Example:

      $ 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.

    $ crwctl workspace:start --devfile=devfile​.yaml

3.9. 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, oc.
  • Uploading and downloading files using the oc tool.

3.9.1. Remotely accessing workspaces using oc

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

Prerequisites

  • The oc, version 1.5.0 or higher, is available. For information about installed version, use:

    $ oc version
    Client Version: version.Info{Major:"1", Minor:"15", GitVersion:"v1.15.0"
    
    ...

Procedure

In the example below:

  • workspace7b2wemdf3hx7s3ln.maven-74885cf4d5-kf2q4 is the name of the Pod.
  • crw is the project.

    1. 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
      crw         workspace7b2wemdf3hx7s3ln.maven-74885cf4d5-kf2q4   4/4     Running   0          6m4s
    2. To find the name of the container:

      $ NAMESPACE=crw
      $ 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
    3. When you have the project, Pod name, and the name of the container, use the `oc ` command to open a remote shell:

      $ NAMESPACE=crw
      $ POD=workspace7b2wemdf3hx7s3ln.maven-74885cf4d5-kf2q4
      $ CONTAINER=maven
      $ oc exec -ti -n ${NAMESPACE} ${POD} -c ${CONTAINER} bash
      user@workspace7b2wemdf3hx7s3ln $
    4. 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.9.2. Downloading and uploading a file to a workspace using the command-line interface

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

Prerequisites

  • A running instance of CodeReady Workspaces. To install an instance of CodeReady Workspaces, see Installing CodeReady Workspaces.
  • Remote access to the CodeReady Workspaces workspace you intend to modify. See Remotely accessing workspaces.
  • The oc, version 1.5.0 or higher, is available. For information about installed version, use:

    $ oc version
    Client Version: version.Info{Major:"1", Minor:"15", GitVersion:"v1.15.0"
    
    ...

Procedure

The following procedure uses crw as an example of a user project.

  • 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=crw
    $ 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=crw
$ 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.

Additional resources

3.10. 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.10.1. Mounting a secret as a file into a workspace container

Warning

On OpenShift 3.11, secrets mounted as file overrides volume mounts defined in the devfile.

This section describes how to mount a secret from the user’s 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 OpenShift 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.10.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. In the OpenShift project where a CodeReady Workspaces workspace will be created, generate a new OpenShift secret.

    • The labels of the secret that is about to be generated must match the set of labels configured in che.workspace.provision.secret.labels property of 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 OpenShift 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.10.3. Mounting a git credentials store into a workspace container

This section describes how to mount git credentials 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 the 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.10.4. The use of annotations in the process of mounting a secret into a workspace container

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

3.11. Authenticating users on private repositories of SCM servers

The following section describes how to configure user authentications for SCM servers.

3.11.1. Authenticating on Bitbucket servers

The following section describes the configuration needed to enables CodeReady Workspaces to use Bitbucket (BB) repositories with Git cloning operations.

BB authentication is based on using personal access tokens. Each BB user is able to request several personal access tokens with different attributes, such as names, permissions, or expiration times. Those tokens can also be used to sign BB REST API calls and perform Git repository operations.

  • CodeReady Workspaces users may use public or private repositories on the BB Source Code Management (SCM) system as a source of their projects.
Note

Before configuring the OAuth 1 authentication that is required for reading from private repositories and writing to both private and public repositories, configure the BB server with CodeReady Workspaces first. To do so, see the Prerequisites section below.

Additional resources

For a remote Git repository that uses a self-signed certificate, add an additional server configuration. See Deploying CodeReady Workspaces with support for Git repositories with self-signed certificates.

Prerequisites

  • A BB endpoint has been registered with CodeReady Workspaces. Follow the Configuring Bitbucket servers procedure and register a BB server using the CHE_INTEGRATION_BITBUCKET_SERVER__ENDPOINTS YAML secret property.

Procedure

  1. Configure the OAuth 1 authentication by following the Configuring Bitbucket Server OAuth 1 procedure.

3.11.2. Authenticating on GitLab servers

Configuring authentication on the GitLab system is similar to Bitbucket.

GitLab authentication is based on using personal access tokens. Each GitLab user is able to request several personal access tokens with different names, permissions, expiration times, and so on. Those tokens can be used to sign GitLab REST API calls and perform Git repository operations.

See the GitLab documentation for more details about personal access tokens.

To allow GitLab authentication on CodeReady Workspaces side, personal tokens must be stored in the user’s project in the form of a secret. The secret must look as follows:

Example 3.10. GitLab personal access token secret

apiVersion: v1
kind: Secret
metadata:
  name: gitlab-personal-access-token-secret
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: scm-personal-access-token
  annotations:
    che.eclipse.org/expired-after: '-1'
    che.eclipse.org/che-userid: '355d1ce5-990e-401e-9a8c-094bca10b5b3'
    che.eclipse.org/scm-userid: '2'
    che.eclipse.org/scm-username: 'user-foo'
    che.eclipse.org/scm-url: 'https://gitlab.apps.cluster-example.com'
data:
  token: Yzh5cEt6cURxUWVCa3FKazhtaHg=

The main parts of the secret are:

Label

app.kubernetes.io/component

Indicates it is a SCM personal token secret.

Annotation

che.eclipse.org/che-userid

Red Hat CodeReady Workspaces id of the user token belongs to

Annotation

che.eclipse.org/scm-userid

GitLab user id to which token belongs

Annotation

che.eclipse.org/scm-username

GitlLab user name to which token belongs

Annotation

che.eclipse.org/scm-url

GitLab server URL to which this token belong

Annotation

che.eclipse.org/expired-after

Personal access token expiration time

Data entry

token

Base-64 encoded value of the personal access token

Note

Encoding a string into the base64 format using the base64 tool on Linux machines leads to adding the newline character to the end of the source string and causing a value to be unusable as the authentication header value after decoding. Avoid this by using base64 -w0, which removes newly added lines, or strip newlines explicitly using`tr -d \\n`.

  1. To obtain a user ID from a secret, take a look into user profile page on GitLab web UI or make a call to a REST API URL:

    • For GitLab:

      https://<gitlab-hostname>/api/v4/users?username=<username>
    • For CodeReady Workspaces

      \https://codeready-<openshift_deployment_name>.<domain_name>/api/user
    • With the token credentials obtained from a secret, another secret is automatically created, allowing authorization to Git operations. This secret is mounted into a workspace container as a Git credentials file, and any additional configurations are not required to work with private Git repositories.
    • When a remote Git repository uses a self-signed certificate, add an additional server configuration. See: Deploying CodeReady Workspaces with support for Git repositories with self-signed certificates.

3.11.3. Authenticating on GitHub servers

Configuring authentication on the GitHub system is similar to GitLab.

GitHub authentication can be based on using personal access tokens. Each GitHub user is able to request several personal access tokens with different names, permissions, expiration times, and so on. Those tokens can be used to sign GitHub REST API calls and perform Git repository operations.

To allow GitHub authentication on CodeReady Workspaces side, personal tokens must be stored in the user’s project in the form of a secret. The secret must look as follows:

Example 3.11. GitHub personal access token secret

apiVersion: v1
kind: Secret
metadata:
  name: github-personal-access-token-secret
  labels:
    app.kubernetes.io/part-of: che.eclipse.org
    app.kubernetes.io/component: scm-personal-access-token
  annotations:
    che.eclipse.org/expired-after: '-1'
    che.eclipse.org/che-userid: '355d1ce5-990e-401e-9a8c-094bca10b5b3'
    che.eclipse.org/scm-userid: '1651062'
    che.eclipse.org/scm-username: 'user-foo'
    che.eclipse.org/scm-url: 'https://github.com'
data:
  token: Yzh5cEt6cURxUWVCa3FKazhtaHg=

The main parts of the secret are:

Label

app.kubernetes.io/component

Indicates it is an SCM personal token secret.

Annotation

che.eclipse.org/che-userid

Red Hat CodeReady Workspaces id of the user token belongs to

Annotation

che.eclipse.org/scm-userid

GitHub user id to which token belongs

Annotation

che.eclipse.org/scm-username

GitHub username to which token belongs

Annotation

che.eclipse.org/scm-url

GitHub server URL to which this token belongs. Typically, it is https://github.com

Annotation

che.eclipse.org/expired-after

Personal access token expiration time

Data entry

token

Base-64 encoded value of the personal access token

Note

Encoding a string into the base64 format using the base64 tool on Linux machines leads to adding the newline character to the end of the source string and causing a value to be unusable as the authentication header value after decoding. Avoid this by using base64 -w0, which removes newly added lines, or strip newlines explicitly using`tr -d \\n`.

  1. To obtain a user ID from a secret, make a call to a REST API URL:

    https://api.github.com/user
    • For CodeReady Workspaces

      \https://codeready-<openshift_deployment_name>.<domain_name>/api/user
    • With the token credentials obtained from a secret, another secret is automatically created, allowing authorization to Git operations. This secret is mounted into a workspace container as a Git credentials file, and any additional configurations are not required to work with private Git repositories.
    • When a remote Git repository uses a self-signed certificate, add an additional server configuration. See: Deploying CodeReady Workspaces with support for Git repositories with self-signed certificates.