CodeReady Workspaces devfile, demystified

With the exciting advent of CodeReady Workspaces (CRW) 2.0 comes some important changes. Based on the upstream project Eclipse Che 7, CRW brings even more of the "Infrastructure as Code" idea to fruition. Workspaces mimic the environment of a PC, an operating system, programming language support, the tools needed, and an editor. The real power comes by defining a workspace using a YAML file—a text file that can be stored and versioned in a source control system such as Git. This file, called devfile.yaml, is powerful and complex. This article will attempt to demystify the devfile.

A Java Maven example

The following devfile defines a workspace that has Java language support, includes the Maven build tool, and has two custom commands.

Let's break this down.

Section 1: metadata

This section is required, and in this case name is specified as the name of this workspace (wksp-javamaven). You also have the option of a name prefix, in which case the system will generate the rest of the name (e.g., generateName: javamaven-). Using generateName means a user can have multiple instances of this workspace at the same time. This is an important distinction and one which must be addressed by management.

Section 2: projects

This section is optional (but probably a very good idea) and tells the workspace where to find the project that will be included. In this case, we're pointing to the master branch of a Git repository located on GitHub. You can specify multiple projects for a workspace, and the type can be a zip file as well. While the name of the project does not need to match the name of the repo it's, again, probably a very good idea. If you make them different, well ... then that's a create opportunity to add confusion and really mess things up.

Section 3: attributes

This part is optional and can pretty much define anything you wish. In this example, it's specifying that any values stored in any specified volumes are not stored. This will likely be the value you'll always want. The idea is that, unless you commit your changes to the Git repo, any work done will be lost. Think of it this way: Whereas on your local PC you perform a File --> Save command to keep your work, you'll instead do git commit. In "devfile-speak," persistVolumes: false makes the data ephemeral. This setting, false, also makes the workspace perform better.

Section 4: components

This is the heaviest part of this example, where we specify what bits and pieces make up our workspace.

The first component is a Che Plugin, identified at redhat/java/latest. You can see the description of this plug on this GitHub page.

The next component is a type dockerimage that is the maven support for this workspace. Of special note is the setting mountSources: true, which makes the source code available to the container that is running this image. In this particular case, we want our Maven build to have access to the source code—which makes sense.

The volumes: setting defines a directory within the container that is available to this workspace. This is used, for example, to give the workspace access to a needed directory that would otherwise be outside the container and blocked by lack of permissions. In other words, if you run a command in a workspace and get an error message because you are denied access to a directory, you can get around that by defining that directory here, in your devfile, that will be created inside your container.

The remaining settings associated with this component are related to memory limits, security, etc.

Section 5: apiVersion

This section is required and is how you specify which API version you are using. This is pretty much boilerplate text.

Section 6: commands

This is the fun part. In this section, you can define custom commands that are available to the user. Typically, this is where you'll specify command-line commands that can be run from within the IDE rather than dropping to the command line and typing what may be a lengthy command. The properties here will look pretty much self-explanatory. Note that a macro can be used instead of hard-coded value for the project root directory (e.g., ${CHE_PROJECTS_ROOT}).

Start exploring

There are many settings and variations of devfiles. If you have the ability, I suggest going into your CRW 2.0 instance and exploring any existing workspaces' devfiles. Take an existing devfile, clone it, then change it and implement it to see what happens. Like any good developer, make changes until you break things, then gain understanding.