Parent Devfiles

[l0rd]

We want to experiment how the Devfile format could be used to define a stack.

Requirements

1. Parent devfile

A parent devfile is a devfile published somewhere where odo or Che can read
it. Like a gist, a registry or a kubernetes resource (see referencing parents below).

A parent devfile is a regular devfile and includes components (for build and runtime), one or more code sample projects, events and commands to build and run the sample applications.

Any devfile that references a parent devfile will inherit its components, events and commands but won't inherit the code sample.

2. Referencing parents: uri, id or kubernetes

A parent devfile can be referenced in 3 different ways. Using its id if it has been published in a registry:

parent:
    id: redhat/nodejs/11.6  # <-- the id format is <publisher>/<stack-name>/<version>
    registry: https://devfile-registry.io/

Using the URI if it has been published on a static http server (like gist or pastebin):

parent:
    uri: https://raw.githubusercontent.com/eclipse/che-devfile-

Using a Kubernetes resource name, namespace if it has been deployed on a Kubernete cluster as a DevWorkspaceTemplate:

parent:
    kubernetes:
        name: mydevworkspacetemplate
        namespace: mynamespace

3. Customizing parent configuration

When referencing a parent, a devfile should be able to customize its configuration. The syntax to customize a parent configuration is similar to kustomize:

parent:
  id: redhat/theia-vsx-stack/latest     # <--- Parent referenced by id 
  components:                                  # <--- Parent configuration can be customized
    - name: vsx-installer                    # <--- Should match the name of an existing parent component
      container:
         env:
            - name: VSX_LIST
               value: java-dbg.vsix,java.vsix
  commands:
    (...)
components:                          # The main Devfile body provides new elements, not inherited from the parent
  - name: tooling                     # <--- Should *not* match the name of a parent component 
    container:                           # <--- Components are added to parent's components
      image: busybox
events:                                   # <--- Events are only allowed in the main Devfile body,
  (...)                                       #        and the resulting events is the merged of the these events with the events of the parent.  

The place where an customizable element (component, command or project) should be defined is clearly driven by the following rule. It is either:

• inside the scope of the parent element itself if it is an override of an existing parent element,
• at the toplevel of the current devfile if it is a new element not present in the parent.

As a consequence;

• If a command / project / component element is added inside the parent scope, but there is no element with the same key (name or id) in the parent, this will trigger an error.
• If a command / project / component element is added in the main Devfle body, at the top-level, and an element with the same key (name or id) exists in the parent or in any plugin, then this will trigger an error.

As for the events element it is not really customizable: Due to the structure of the Events object, we can only add command bindings to some event. Overriding an existing command binding doesn't really makes sense. That's why we only allow events in the main devfile body, and not in the overrides. And the resulting events are the merge of the event objects coming from the parent, the plugins, and the main devfile body.

An Example

The parent devfile is published on github repo: https://raw.githubusercontent.com/eclipse/che-devfile-registry/master/devfiles/nodejs/devfile.yaml

The following devfile references it:

schemaVersion: 2.0.0
metadata:
  name: nodejs-app
parent:
    uri: https://(...)/nodejs/devfile.yaml # <--- Parent referenced by `uri`, registry `id`
                                           #      or `kubernetes` devworkspace
  components:                              # <--- Parent configuration can be customized
    - name: vsx-installer
      container:
         env:
            - name: VSX_LIST
               value: java-dbg.vsix,java.vsix
components:                               # <--- components are added to parent's components
  - name: tooling                       # <--- should not match the name of a parent component
    container:
      image: busybox
commands:                                 # <--- commands are added to parent's commands
   (...)

[johnmcollier]

@l0rd Could the project devfile also include additional components not referenced in the stack devfile (e.g. new containers, plugins, etc)?

[l0rd]

@l0rd Could the project devfile also include additional components not referenced in the stack devfile (e.g. new containers, plugins, etc)?

That's a good question. I think that we need to discuss that. There are 2 possible behaviors. Eventual components or commands in the project devfile:

• replace the stack components or commands
  or
• are added to the stack components or commands

The replace behavior is consistent with what we are doing with the project. But "augmenting" a stack with extra components looks like an interesting use case.

[elsony]

The goal is to allow user to refer to an existing devfile to reuse and modify/customerize it. Therefore, ideally, we should have a way to cover both adding definition and modifying existing one.

[l0rd]

Makes sense @elsony. We need to decide how we specify if a component/command is supposed to replace or extend a stack components/commands. Using IDs/aliases is an option.

[davidfestal]

I implemented the related changes, API-wise and spec-wise, in the proposal-25-variant-1-define-stacks.

I also added related examples of both:

• a devfile 2.0.0 with devfile 2.0.0 parent
• devWorkspace K8S CR with either DevWorkspaceTemplate CR parent or devfile 2.0.0 parent.

[sbose78]

How do I try out the PoC ? :)

[davidfestal]

The only thing to try out on the Che side for now is playing with the syntax / API by running Openshift.io on this branch:

https://che.openshift.io/f/?url=https://github.com/che-incubator/devworkspace-api/tree/proposal-25-variant-1-define-stacks

As soon as the workspace is opened, you should be able to:

• open the yaml files in the following folders:
  • samples/
  • devfile-support/samples
• have yaml language support (completion and documentation) based on the current Json schemas.

I'm still working on the implementation side of this POC to include this parent mechanism into the existing Workspace CRD controller POC.

[davidfestal]

Here is a link to the demo of the POC implementation of this proposal on the Che side:
https://youtu.be/SZppcZLQ03E

[l0rd]

The new details provided in the issue description have been reviewed and approved today