Configuring a workspace using a devfile

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

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.

A devfiles is a YAML file that Che consumes and transforms into a cloud workspace composed of multiple containers. It is possible to store a devfile remotely or locally, in any number of ways, such as:

  • In a git repository, in the root folder, or on a feature branch.

  • On a publicly accessible web server, accessible through HTTP.

  • Locally as a file, and deployed using chectl.

  • In a collection of devfiles, known as a devfile registry.

When creating a workspace, Che uses that definition to initiate everything and run all the containers for the required tools and application runtimes. Che 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.

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

  • Elements of the project, such as the path, git location, or branch.

  • Commands to perform daily tasks such as build, run, test, and debug.

  • The runtime environment with its container images needed for the application to run.

  • Che-Theia plug-ins with tools, IDE features, and helpers that a developer would use in the workspace, for example, Git, Java support, SonarLint, and Pull Request.

Creating a workspace from the default branch of a Git repository

It is possible to create a Che workspace by pointing to a devfile that is stored in a Git source repository. The Che instance then uses the discovered devfile.yaml file to build a workspace using the factory URL (/f?url=) API.

Prerequisites
  • A running instance of Eclipse Che. To install an instance of Eclipse Che, see Installing Che.

  • The devfile.yaml or .devfile.yaml file is located in the root folder of a Git repository that is available over HTTPS. See Making a workspace portable using a devfile for detailed information about creating and using devfiles.

Procedure

Run the workspace by opening the following URL: \https://che-host:che-port/f?url=https://<GitRepository>

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

Creating a workspace from a feature branch of a Git repository

A Che 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 Che instance then uses the discovered devfile to build a workspace.

Prerequisites
  • A running instance of Eclipse Che. To install an instance of Eclipse Che, see Installing Che.

  • 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 Making a workspace portable using a devfile for detailed information about creating and using devfiles.

Procedure

Execute the workspace by opening the following URL: \https://che-host:che-port/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

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 Che instance then uses the discovered devfile to build a workspace.

Prerequisites
Procedure
  1. Execute the workspace by opening the following URL: \https://che-host:che-port/f?url=https://<yourhosturl>/devfile.yaml

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

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://che-host:che-port/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 a user 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:
...

Creating a workspace using chectl and a local devfile

A Che workspace can be created by pointing the chectl tool to a locally stored devfile. The Che 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 chectl tool as follows:

$ chectl workspace:create --name=<WORKSPACE_NAME> \ (1)
--devfile=devfile.yaml --start \
-n che
1 The workspace name to create
If --devfile flag is omitted then chectl looks for devfile.yaml or devfile.yml files in the current directory to create a workspace from.

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://che-host:che-port/f?url=https://<hostURL>/devfile.yaml&workspaceDeploymentLabels=<url_encoded_comma_separated_key_values>&workspaceDeploymentAnnotations=<url_encoded_comma_separated_key_values override>

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://che.openshift.io/f?url=https://gist.githubusercontent.com/themr0c/ef8e59a162748a8be07e900b6401e6a8/raw/8802c20743cde712bbc822521463359a60d1f7a9/devfile.yaml&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 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://che.openshift.io/f?url=https://gist.githubusercontent.com/themr0c/ef8e59a162748a8be07e900b6401e6a8/raw/8802c20743cde712bbc822521463359a60d1f7a9/devfile.yaml&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"
...