Chapter 4. Authoring devfiles Section 4.1, "Authoring devfiles version 1" Section 4.2, "Authoring a devfile 2" 4.1. Authoring devfiles version 1 This section explains the concept of a devfile and how to configure a CodeReady Workspaces workspace by using a devfile of the 1.0 specification. 4.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. A devfiles is a YAML file that CodeReady Workspaces 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 crwctl . In a collection of devfiles, known as a devfile registry . 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: 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. 4.1.2. A minimal devfile The following is the minimum content required in a devfile: apiVersion metadata name 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 . Note A choice of use of the parameter generateName or name is optional, but only one of these parameters has to be chosen by a user and defined. When both attributes are specified, generateName is ignored. See Section 4.1.3, "Generating workspace names" . metadata: generatedName: or metadata: name: 4.1.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. 4.1.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. 4.1.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 4.1.4.2. Specifying multiple projects in a devfile A single devfile can define multiple projects, which are cloned to the desired destination. These projects are created inside a user's workspace after the workspace is started. For each project, specify the following: The type of the source repository - this can be git or zip . For additional information, see the Devfile reference section. The location of the source repository - an URL to a Git repository or zip archive. Optionally, the directory to which the project is cloned. If none is specified, the default directory is used, which is a directory that matches the project name or project Git repository. Example of a devfile with two projects In the following example, the projects frontend and backend act as examples of a user's projects. Each project is located in a separate repository. The backend project has a specific requirement to be cloned into the src/github.com/ <github-organization> / <backend> / directory under the source root, implicitly defined by the CodeReady Workspaces runtime. The frontend project will be cloned into the <frontend/> directory under the source root. apiVersion: 1.0.0 metadata: name: example-devfile projects: - name: <frontend> source: type: git location: https://github.com/ <github-organization> / <frontend> .git - name: <backend> clonePath: src/github.com/ <github-organization> / <backend> source: type: git location: https://github.com/ <github-organization> / <backend> .git Additional resources For a detailed explanation of all devfile component assignments and possible values, see: Specification repository Detailed json-schema documentation These sample devfiles are a good source of inspiration: Sample devfiles for Red Hat CodeReady Workspaces workspaces used by default in the user interface . Sample devfiles for Red Hat CodeReady Workspaces workspaces from Red Hat Developer program . 4.1.5. Devfile reference This section contains devfile reference and instructions on how to use the various elements that devfiles consist of. 4.1.5.1. Adding schema version to a devfile Procedure Define the schemaVersion attribute in the devfile: Example 4.1. Adding schema version to a devfile schemaVersion: 1.0.0 4.1.5.2. Adding a name to a devfile Adding a name to a devfile is mandatory. Both name and generateName are optional attributes, but at least one of them must be defined. Procedure To specify a static name for the workspace, define the name attribute. Adding a static name to a devfile schemaVersion: 1.0.0 metadata: name: devfile-sample To specify a prefix for automatically generated workspace names, define the generateName attribute and do not define the name attribute. The workspace name will be in the <generateName>YYYYY format, for example, devfile-sample-2y7kp , where Y is a random [a-z0-9] character. Adding a generated name to a devfile schemaVersion: 1.0.0 metadata: generateName: devfile-sample- 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. 4.1.5.3. Adding projects to a devfile A devfile is designed to contain 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. 4.1.5.3.1. Project-source type: git source: type: git location: https://github.com/eclipse-che/che-server.git startPoint: main 1 tag: 7.34.0 commitId: 36fe587 branch: 7.34.x sparseCheckoutDir: core 2 1 startPoint : 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 a single directory, is needed. Example 4.2. 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 . 4.1.5.3.2. Project-source type: zip source: type: zip location: http://host.net/path/project-src.zip 4.1.5.3.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 4.1.5.4. Adding components to a devfile Each component in a single devfile must have a unique name. 4.1.5.4.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/ 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. 4.1.5.4.2. Component type: chePlugin Describes plug-ins in a workspace by defining their id . A devfile is allowed to have multiple chePlugin components. components: - alias: exec-plugin type: chePlugin id: eclipse/che-machine-exec-plugin/latest Both types above use an ID, which is slash-separated publisher, name and version of plug-in from the CodeReady Workspaces Plug-in registry. Note that the CodeReady Workspaces Plug-in registry uses the latest version by default for all plug-ins. To reference a custom plug-in by ID, build and deploy a custom plug-in registry. See https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.15/html-single/administration_guide/index#building-custom-registry-images.adoc . 4.1.5.4.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/latest 4.1.5.4.4. Specifying a component by linking to its descriptor Rather than using the editor or plug-in id to specify cheEditor or chePlugin , provide a direct link to the component descriptor, typically named as meta.yaml , using the reference field: components: - alias: exec-plugin type: chePlugin reference: https://raw.githubusercontent.com.../plugin/1.0.1/meta.yaml The URL in the reference field must be publicly accessible and should directly point to a fetchable meta.yaml file. URLs that redirect or do not directly point to a meta.yaml file will cause the workspace startup to fail. To learn more about publishing meta.yaml files, see Section 5.4, "Publishing metadata for a Visual Studio Code extension" . Note It is impossible to mix the id and reference fields in a single component definition; they are mutually exclusive. 4.1.5.4.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/latest type: chePlugin preferences: java.jdt.ls.vmargs: '-noverify -Xmx1G -XX:+UseG1GC -XX:+UseStringDeduplication' Preferences may also be specified as an array: id: redhat/java/latest type: chePlugin preferences: go.lintFlags: ["--enable-all", "--new"] 4.1.5.4.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 OpenShift 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 4.1.5.4.7. Overriding container entrypoints As with the 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 OpenShift List . 4.1.5.4.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. 4.1.5.4.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. 4.1.5.4.10. Component type: dockerimage A component type that allows to define a container image-based configuration of a container in a workspace. 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: quay.io/eclipse/che-java11-maven:nightly 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 memoryRequest: 256M 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. 4.1.5.4.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 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 . 4.1.5.4.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, and so on. 4.1.5.4.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/ env: - name: HOME value: USD(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 4.1.5.4.14. Specifying container memory limit for components To specify a container(s) memory limit for dockerimage , chePlugin or cheEditor , use the memoryLimit parameter: components: - alias: exec-plugin type: chePlugin id: eclipse/che-machine-exec-plugin/latest memoryLimit: 1Gi - alias: maven type: dockerimage image: quay.io/eclipse/che-java11-maven:nightly 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). 4.1.5.4.15. Specifying container memory request for components To specify a container(s) memory request for dockerimage , chePlugin or cheEditor , use the memoryRequest parameter: components: - alias: exec-plugin type: chePlugin id: eclipse/che-machine-exec-plugin/latest memoryLimit: 1Gi memoryRequest: 512M - alias: maven type: dockerimage image: quay.io/eclipse/che-java11-maven:nightly 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). 4.1.5.4.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/latest cpuLimit: 1.5 - alias: maven type: dockerimage image: quay.io/eclipse/che-java11-maven:nightly 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). 4.1.5.4.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/latest cpuLimit: 1.5 cpuRequest: 0.225 - alias: maven type: dockerimage image: quay.io/eclipse/che-java11-maven:nightly 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). 4.1.5.4.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: USD(CHE_PROJECTS_ROOT)/go - type: cheEditor alias: theia-editor id: eclipse/che-theia/ memoryLimit: 2Gi env: - name: HOME value: USD(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 to which the workspace is deployed. CHE_MACHINE_TOKEN : The token used to authenticate the request against the CodeReady Workspaces server. CHE_MACHINE_AUTH_SIGNATURE__PUBLIC__KEY : 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 devfile might 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. The environment variables for securely accessing the CodeReady Workspaces server are out of scope for devfiles. These variables are available only to CodeReady Workspaces plug-ins, which use them for advanced use cases. 4.1.5.4.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 Kubernetes 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 need to be able to directly interact with it yourself or you allow 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: USD(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 hostname within the workspace containers (in the OpenShift terminology, 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 value (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 loop-back interface, such as 127.0.0.1 . Warning Listening on any other interface than the local loop-back poses a security risk because such server is accessible without the JWT authentication within the cluster network on the corresponding IP addresses. path : The path portion of the URL to the endpoint. This defaults to / , meaning that the endpoint is assumed to be accessible at the web root of the server defined by the component. 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 automatically detects this, and the UI offers to expose this port as a public port automatically. This behavior is useful for debugging a web application. It is impossible to do this for servers, such as a database server, which automatically starts at the container start. 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/ 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/ 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 4.1.5.4.20. OpenShift resources To describe complex deployments, include references to OpenShift resource lists in the devfile. The OpenShift resource lists become a part of the workspace. Important CodeReady Workspaces merges all resources from the OpenShift resource lists into a single deployment. Be careful when designing such lists to avoid name conflicts and other problems. Table 4.1. Supported OpenShift resources Platform Supported resources OpenShift deployments , pods , services , persistent volume claims , secrets , ConfigMaps , Routes 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, you can modify the entrypoints (command and arguments) of the containers in the resource list. 4.1.5.5. 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 Visual Studio Code). 4.1.5.5.1. CodeReady Workspaces-specific commands Each CodeReady Workspaces-specific command features: An actions attribute that specifies 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: USD(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: "USD{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. 4.1.5.5.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 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 USD{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 start configurations. 4.1.5.5.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: USD{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 Route. 4.1.5.5.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: Open CodeReady Workspaces preferences in File Settings Open Preferences and find che.task.preview.notifications in the CodeReady Workspaces section. 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) 4.1.5.6. Adding attributes to a devfile Devfile attributes can be used to configure various features. 4.1.5.6.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 4.1.5.6.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 4.1.5.6.3. Attribute: asyncPersist (asynchronous storage) When persistVolumes is set to false (see above), the additional attribute asyncPersist can be set to true to enable asynchronous storage. See https://access.redhat.com/documentation/en-us/red_hat_codeready_workspaces/2.15/html-single/installation_guide/index#configuring-storage-types.adoc for more details. Example of a devfile with asynchronous storage 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 asyncPersist: true 4.1.5.6.4. Attribute: mergePlugins This property can be set to manually control how plug-ins are included in the workspace. When the property mergePlugins is set to true , Che will attempt to avoid running multiple instances of the same container by combining plugins. The default value when this property is not included in a devfile is governed by the Che configuration property che.workspace.plugin_broker.default_merge_plugins ; adding the mergePlugins: false attribute to a devfile will disable plug-in merging for that workspace. Example of a devfile with plug-in merging disabled 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: mergePlugins: false 4.1.6. Objects supported in Red Hat CodeReady Workspaces 2.15 The following table lists the objects that are partially supported in Red Hat CodeReady Workspaces 2.15: Object API Kubernetes Infra OpenShift Infra Notes Pod Kubernetes Yes Yes - Deployment Kubernetes Yes Yes - ConfigMap Kubernetes Yes Yes - PVC Kubernetes Yes Yes - Secret Kubernetes Yes Yes - Service Kubernetes Yes Yes - Ingress Kubernetes 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 Kubernetes Infrastructure: OpenShift routes replaced on Ingresses. Template OpenShift Yes Yes The Kubernetes API does not support templates. A workspace with a template in the recipe starts successfully and the default parameters are resolved. 4.2. Authoring a devfile 2 When you author or edit a devfile for configuring a workspace, the devfile must meet the latest devfile 2 specification. Prerequisites An instance of CodeReady Workspaces with the Dev Workspace Operator enabled. See Installing CodeReady Workspaces . Procedure Follow the instructions in the Devfile User Guide . Additional resources For more information about devfile object schema and object properties, see the Introduction to Devfiles .

Commands:
apiVersion: 1.0.0 metadata: name: crw-in-crw-out
metadata: generatedName:
metadata: name:
apiVersion: 1.0.0 metadata: generateName: crw-
apiVersion: 1.0.0 metadata: name: minimal-workspace
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
apiVersion: 1.0.0 metadata: name: example-devfile projects: - name: <frontend> source: type: git location: https://github.com/ <github-organization> / <frontend> .git - name: <backend> clonePath: src/github.com/ <github-organization> / <backend> source: type: git location: https://github.com/ <github-organization> / <backend> .git
schemaVersion: 1.0.0
schemaVersion: 1.0.0 metadata: name: devfile-sample
schemaVersion: 1.0.0 metadata: generateName: devfile-sample-
source: type: git location: https://github.com/eclipse-che/che-server.git startPoint: main 1 tag: 7.34.0 commitId: 36fe587 branch: 7.34.x sparseCheckoutDir: core 2
source: type: zip location: http://host.net/path/project-src.zip
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
components: - alias: theia-editor type: cheEditor id: eclipse/che-theia/next
components: - alias: exec-plugin type: chePlugin id: eclipse/che-machine-exec-plugin/latest
components: - alias: exec-plugin type: chePlugin registryUrl: https://my-customregistry.com id: eclipse/che-machine-exec-plugin/latest
components: - alias: exec-plugin type: chePlugin reference: https://raw.githubusercontent.com.../plugin/1.0.1/meta.yaml
id: redhat/java/latest type: chePlugin preferences: java.jdt.ls.vmargs: '-noverify -Xmx1G -XX:+UseG1GC -XX:+UseStringDeduplication'
id: redhat/java/latest type: chePlugin preferences: go.lintFlags: ["--enable-all", "--new"]
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
components: - alias: mysql type: kubernetes reference: petclinic.yaml referenceContent: | kind: List items: - apiVersion: v1 kind: Pod metadata: name: ws spec: containers: ... etc
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']
components: - alias: appDeployment type: kubernetes reference: app-deployment.yaml env: - name: ENV_VAR value: value
components: - alias: appDeployment type: kubernetes reference: app-deployment.yaml mountSources: true
components: - alias: maven type: dockerimage image: quay.io/eclipse/che-java11-maven:nightly 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 memoryRequest: 256M command: ['tail'] args: ['-f', '/dev/null']
apiVersion: 1.0.0 metadata: name: MyDevfile components: - type: dockerimage image: golang memoryLimit: 512Mi command: ['sleep', 'infinity']
apiVersion: 1.0.0 metadata: name: MyDevfile components: - type: dockerimage image: golang memoryLimit: 512Mi command: ['sleep', 'infinity']
apiVersion: 1.0.0 metadata: name: MyDevfile components: - type: dockerimage image: golang memoryLimit: 512Mi mountSources: true command: ['sleep', 'infinity'] volumes: - name: cache containerPath: /.cache
apiVersion: 1.0.0 metadata: name: MyDevfile components: - type: cheEditor alias: theia-editor id: eclipse/che-theia/next env: - name: HOME value: USD(CHE_PROJECTS_ROOT) volumes: - name: cache containerPath: /.cache
apiVersion: 1.0.0 metadata: name: MyDevfile components: - type: openshift alias: mongo reference: mongo-db.yaml volumes: - name: mongo-persistent-storage containerPath: /data/db
components: - alias: exec-plugin type: chePlugin id: eclipse/che-machine-exec-plugin/latest memoryLimit: 1Gi - alias: maven type: dockerimage image: quay.io/eclipse/che-java11-maven:nightly memoryLimit: 512M
components: - alias: exec-plugin type: chePlugin id: eclipse/che-machine-exec-plugin/latest memoryLimit: 1Gi memoryRequest: 512M - alias: maven type: dockerimage image: quay.io/eclipse/che-java11-maven:nightly memoryLimit: 512M memoryRequest: 256M
components: - alias: exec-plugin type: chePlugin id: eclipse/che-machine-exec-plugin/latest cpuLimit: 1.5 - alias: maven type: dockerimage image: quay.io/eclipse/che-java11-maven:nightly cpuLimit: 750m
components: - alias: exec-plugin type: chePlugin id: eclipse/che-machine-exec-plugin/latest cpuLimit: 1.5 cpuRequest: 0.225 - alias: maven type: dockerimage image: quay.io/eclipse/che-java11-maven:nightly cpuLimit: 750m cpuRequest: 450m
apiVersion: 1.0.0 metadata: name: MyDevfile components: - type: dockerimage image: golang memoryLimit: 512Mi mountSources: true command: ['sleep', 'infinity'] env: - name: GOPATH value: USD(CHE_PROJECTS_ROOT)/go - type: cheEditor alias: theia-editor id: eclipse/che-theia/next memoryLimit: 2Gi env: - name: HOME value: USD(CHE_PROJECTS_ROOT)
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: USD(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
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
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
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
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
commands: - name: build actions: - type: exec component: mysql command: mvn clean workdir: /projects/spring-petclinic
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: USD(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: "USD{CHE_PROJECTS_ROOT}/src/github.com/acme/my-go-project"
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 USD{workspaceFolder}/test.file" } ] }
commands: - name: tasks previewUrl: port: 8080 1 path: /myweb 2 actions: - type: exec component: go-cli command: "go run webserver.go" workdir: USD{CHE_PROJECTS_ROOT}/webserver
apiVersion: 1.0.0 metadata: name: petclinic-dev-environment components: - alias: myApp type: kubernetes reference: my-app.yaml attributes: editorFree: true
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
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 asyncPersist: true
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: mergePlugins: false