Creating a workspace from remote devfile

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

Creating a workspace from the default branch of a Git repository

This section describes how to start a Che workspace using a factory URL. The factory URL is a link pointing Che 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 Che

Prerequisites
  • A running instance of Eclipse Che. See Installing Che.

  • The Git repository <GIT_REPOSITORY_URL> is available over HTTPS and contains a devfile.yaml or .devfile.yaml in the root folder. See Authoring devfiles version 2.

Procedure

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 Authoring devfiles version 2 for detailed information about creating and using devfiles.

Procedure

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

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
  • A running instance of Eclipse Che. To install an instance of Eclipse Che, see Installing Che.

  • The publicly-accessible standalone devfile.yaml file. See Authoring devfiles version 2 for detailed information about creating and using devfiles.

Procedure
  1. Execute the workspace by opening the following URL: https://che-host:che-port/#https://<yourhosturl>/devfile.yaml

Example
https://workspaces.openshift.com/f?url=https://github.com/eclipse/che-docs

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
  • A running instance of Eclipse Che. To install an instance of Eclipse Che, see Installing Che.

  • A publicly accessible standalone devfile.yaml file. See Authoring devfiles version 2 for detailed information about creating and using devfiles.

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 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 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 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 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 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, so a user 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. Using Che Dashboard, move to the Devfile tab of the newly created workspace and check its content.

Allowing users to define workspace deployment labels and annotations

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

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

  • A publicly accessible standalone devfile.yaml file. See Authoring devfiles version 2 for detailed information about creating and using devfiles.

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 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 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 Che Dashboard, move to the Workspaces tab and read the name of the Kubernetes namespace field.

  1. Log in to the cluster:

    1. Retrieve the Che 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 namespace using the Kubernetes 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"

Allowing users to define workspace creation strategy

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

Che 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
  • A running instance of Che. See Installing Che.

  • The Git repository <GIT_REPOSITORY_URL> is available over HTTPS.

Procedure

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

    https://che-host:che-port/f?url=<GIT_REPOSITORY_URL>&policies.create=<value>

Additional resources