Devfile describes the structure of a cloud-native devworkspace and development environment.

Map of implementation-dependant free-form YAML attributes.

Predefined, ready-to-use, devworkspace-related commands

Command that consists in applying a given component definition, typically bound to a devworkspace event.

For example, when an `apply` command is bound to a `preStart` event, and references a `container` component, it will start the container as a K8S initContainer in the devworkspace POD, unless the component has its `dedicatedPod` field set to `true`.

When no `apply` command exist for a given component, it is assumed the component will be applied at devworkspace start by default, unless `deployByDefault` for that component is set to false.

Defines the group this command is part of

Optional label that provides a label for this command to be used in Editor UI menus for example

Composite command that allows executing several sub-commands either sequentially or concurrently

The commands that comprise this composite command

Indicates if the sub-commands should be executed concurrently

CLI Command executed in an existing component container

The actual command-line string

Special variables that can be used:

 - `$PROJECTS_ROOT`: A path where projects sources are mounted as defined by container component's sourceMapping.

 - `$PROJECT_SOURCE`: A path to a project source ($PROJECTS_ROOT/<project-name>). If there are multiple projects, this will point to the directory of the first one.

Describes component to which given action relates

Optional list of environment variables that have to be set before running the command

Specify whether the command is restarted or not when the source code changes. If set to `true` the command won't be restarted. A *hotReloadCapable* `run` or `debug` command is expected to handle file changes on its own and won't be restarted. A *hotReloadCapable* `build` command is expected to be executed only once and won't be executed again. This field is taken into account only for commands `build`, `run` and `debug` with `isDefault` set to `true`.

Default value is `false`

Working directory where the command should be executed

Special variables that can be used:

 - `$PROJECTS_ROOT`: A path where projects sources are mounted as defined by container component's sourceMapping.

 - `$PROJECT_SOURCE`: A path to a project source ($PROJECTS_ROOT/<project-name>). If there are multiple projects, this will point to the directory of the first one.

Mandatory identifier that allows referencing this command in composite commands, from a parent, or in events.

List of the devworkspace components, such as editor and plugins, user-provided containers, or other types of components

Allows adding and configuring devworkspace-related containers

Annotations that should be added to specific resources for this container

The arguments to supply to the command running the dockerimage component. The arguments are supplied either to the default command provided in the image or to the overridden command.

Defaults to an empty array, meaning use whatever is defined in the image.

The command to run in the dockerimage component instead of the default one provided in the image.

Defaults to an empty array, meaning use whatever is defined in the image.

Specify if a container should run in its own separated pod, instead of running as part of the main development environment pod.

Default value is `false`

Environment variables used in this container.

The following variables are reserved and cannot be overridden via env:

 - `$PROJECTS_ROOT`

 - `$PROJECT_SOURCE`

Toggles whether or not the project source code should be mounted in the component.

Defaults to true for all component types except plugins and components that set `dedicatedPod` to true.

Optional specification of the path in the container where project sources should be transferred/mounted when `mountSources` is `true`. When omitted, the default value of /projects is used.

List of volumes mounts that should be mounted is this container.

Allows specifying the definition of an image for outer loop builds

Defines if the image should be built during startup.

Default value is `false`

Name of the image for the resulting outerloop build

Allows importing into the devworkspace the Kubernetes resources defined in a given manifest. For example this allows reusing the Kubernetes definitions used to deploy some runtime components in production.

Defines if the component should be deployed during startup.

Default value is `false`

Mandatory name that allows referencing the component from other elements (such as commands) or from an external devfile that may reference this component through a parent or a plugin.

Allows importing into the devworkspace the OpenShift resources defined in a given manifest. For example this allows reusing the OpenShift definitions used to deploy some runtime components in production.

Allows specifying the definition of a volume shared by several other components

Ephemeral volumes are not stored persistently across restarts. Defaults to false

Additional projects related to the main project in the devfile, contianing names and sources locations

Path relative to the root of the projects to which this project should be cloned into. This is a unix-style relative path (i.e. uses forward slashes). The path is invalid if it is absolute or tries to escape the project root through the usage of '..'. If not specified, defaults to the project name.

Defines from what the project should be checked out. Required if there are more than one remote configured

The remotes map which should be initialized in the git project. Projects must have at least one remote configured while StarterProjects & Image Component's Git source can only have at most one remote configured.

Zip project's source location address. Should be file path of the archive, e.g. file://$FILE_PATH

Bindings of commands to events. Each command is referred-to by its name.

IDs of commands that should be executed after the devworkspace is completely started. In the case of Che-Theia, these commands should be executed after all plugins and extensions have started, including project cloning. This means that those commands are not triggered until the user opens the IDE in his browser.

IDs of commands that should be executed after stopping the devworkspace.

IDs of commands that should be executed before the devworkspace start. Kubernetes-wise, these commands would typically be executed in init containers of the devworkspace POD.

IDs of commands that should be executed before stopping the devworkspace.

Overrides of attributes encapsulated in a parent devfile. Overriding is done according to K8S strategic merge patch standard rules.

Overrides of commands encapsulated in a parent devfile or a plugin. Overriding is done according to K8S strategic merge patch standard rules.

Overrides of components encapsulated in a parent devfile or a plugin. Overriding is done according to K8S strategic merge patch standard rules.

Overrides of dependentProjects encapsulated in a parent devfile. Overriding is done according to K8S strategic merge patch standard rules.

Id in a registry that contains a Devfile yaml file

Reference to a Kubernetes CRD of type DevWorkspaceTemplate

Overrides of projects encapsulated in a parent devfile. Overriding is done according to K8S strategic merge patch standard rules.

Registry URL to pull the parent devfile from when using id in the parent reference. To ensure the parent devfile gets resolved consistently in different environments, it is recommended to always specify the `registryUrl` when `id` is used.

Overrides of starterProjects encapsulated in a parent devfile. Overriding is done according to K8S strategic merge patch standard rules.

Sub-directory from a starter project to be used as root for starter project.

URI Reference of a parent devfile YAML file. It can be a full URL or a relative URI with the current devfile as the base URI.

Overrides of variables encapsulated in a parent devfile. Overriding is done according to K8S strategic merge patch standard rules.

Specific stack/sample version to pull the parent devfile from, when using id in the parent reference. To specify `version`, `id` must be defined and used as the import reference source. `version` can be either a specific stack version, or `latest`. If no `version` specified, default version will be used.

Projects worked on in the devworkspace, containing names and sources locations

StarterProjects is a project that can be used as a starting point when bootstrapping new projects

Map of key-value variables used for string replacement in the devfile. Values can be referenced via {{variable-key}} to replace the corresponding value in string fields in the devfile. Replacement cannot be used for

 - schemaVersion, metadata, parent source

 - element identifiers, e.g. command id, component name, endpoint name, project name

 - references to identifiers, e.g. in events, a command's component, container's volume mount name

 - string enums, e.g. command group kind, endpoint exposure

Devfile.io

Devfile schema - Version 2.3.0

Additional resources