Booster Catalog Changelog

Mar 9th, 2018 changes

On March 9th 2018 a new catalog format was made active. The changes to the old format are as follows:

• The order of Mission and Runtime folders in the Booster Catalog has been swapped. The order has gone from mission / runtime [ / version ] to runtime / version / mission
• Version folders are not optional anymore. Even if you have just a single version you need to give it a name. Use default if you don't know what to name it.
• The metadata.json file has been converted to metadata.yaml
• Versions are now defined in the toplevel metadata.yaml file.
• The Missions, Runtimes and Versions defined in the metadata.yaml file can now have metadata sections

The rationale for this is that we had the request from some people if it wouldn't be possible to switch the order of Missions and Runtimes around in the Booster Catalog because it seems like a more natural fit. (See https://github.com/fabric8-launcher/launcher-planning/issues/106)

It means that a Runtime team:

1. Manages everything below "their" Runtime folder in the Booster Catalog, and
2. They are free to add other Missions that they feel are a good fit for their specific Runtime

Also the old Booster Catalog layout perhaps gave a little too much flexibility that is very hard to translate into a nice usable UI. Because it theoretically made it possible for each Booster to have a different list of Runtime versions.

Given the fact that right now all Boosters for the same Runtime also have the same list of Versions and thinking that's probably the most common situation it was thought that perhaps it would be best to have that reflected in the Booster Catalog layout itself.

Taking those point together it was decided to change the old Booster Catalog layout from (fictional example):

 - health-check
   - vertx
     - community
     - redhat
  - spring-boot
    - community
    - redhat-v10
    - redhat-v11
- http-rest
   - vertx
     - community
     - redhat
  - spring-boot
    - community
    - redhat-v10
    - redhat-v11

To:

 - vertx
   - community
     - health-check
     - http-rest
  - redhat
     - health-check
     - http-rest
 - spring-boot
   - community
     - health-check
     - http-rest
  - redhat-v10
     - health-check
     - http-rest
  - redhat-v11
     - health-check
     - http-rest

At the same time removing all the:

  - metadata
    - version
      - name: "Community Version"

entries from the booster.yaml files and move that information to the toplevel metadata.yaml file like this:

missions:
- id: configmap
  name: Externalized Configuration
- id: crud
  name: CRUD
- id: health-check
  name: Health Check
runtimes:
- id: wildfly-swarm
  name: WildFly Swarm
  metadata:
    pipelinePlatform: maven
  versions:
  - id: community
    name: Community Version
    metadata:
      suggested: true
  - id: redhat
    name: Redhat Version

Meaning that there is a fixed list of Versions per Runtime defined in a single place.

The example also shows a new feature where the Missions, Runtimes and Versions defined in the metadata.yaml file can have an optional metadata section that can be used for user-defined attributes and values. The runtime teams can put in them whatever they want and those values will be passed on as-id to the frontend UI where they can be used by the UI to be displayed or to affect the UI in some way.

Feb 1st, 2018 changes

Before February 1st, 2018 the booster catalog consisted of a GitHub repository with a directory structure that defined missions, runtimes and possibly versions and in those directories were .yaml files that contained information about where a booster repository could be found.

Then inside each booster repository pointed to by those .yaml files was another .yaml file, the ".openshiftio/booster.yaml" that contained some extra information about the booster such as its name and its description. Eg, things used to look like this:

booster catalog

- crud
   - nodejs
     - crud-nodejs-booster.yaml
   - vert.x
     - community
       - crud-vertx-community-booster.yaml
     - redhat
       - crud-vertx-redhat-booster.yaml

crud-nodejs-booster.yaml

githubRepo: bucharest-gold/nodejs-rest-http-crud
gitRef: master

nodejs-rest-http-crud/.openshiftio/booster.yaml

name: Node.js - CRUD Example
description: Runs a Node.js application ...

That's how things were before. So what has changed?

• The ".openshiftio/booster.yaml" has been merged into the catalog. You can remove these files from your booster repositories
• The .yaml file names in the catalog don't need to be unique anymore and can just be named "booster.yaml"
• You can add "common.yaml" files to hold common values that will be shared by all booster .yaml files in the same catalog directory and in any sub directories
• The format of the booster .yaml files itself has changed (described below)
• Instead of using different branches and tags for our different server environments (master for development, next for staging, vNN for production, openshift-online-free for starter clusters) we now store all that information in the booster descriptor itself

The new catalog will look somewhat like this:

booster catalog

 - crud
   - nodejs
     - booster.yaml
   - vert.x
     - community
       - booster.yaml
     - redhat
       - booster.yaml

crud/nodejs/booster.yaml

name: Node.js - CRUD Example
description: Runs a Node.js application ...
source:
  git:
    url: https://github.com/bucharest-gold/nodejs-rest-http-crud
    ref: master
metadata:
  runsOn: "!starter"
environment:
  staging:
    source:
      git:
        ref: v1.1.0
  production:
    source:
      git:
        ref: v1.0.3

As you can see the directory structure has stayed the same, but the "booster.yaml" file now contains the combined information of the two previous .yaml files along with a whole bunch of new things.

The important differences to note are:

• GitHub repository references are now full URLs (in preparation to supporting other services besides GitHub)
• "supportedDeploymentTypes" is now gone and has been replaced by "metadata / runsOn". Here it specifies that it doesn't run on starter clusters, but if you'd use "none" you basically get the same as specifying "supporedDeploymentTypes: zip" before (ie it runs nowhere, you can only download it)
• There is a new "environments" section that holds the information specific for running in each environment. The environment name is a property freely definable by the server running the Launcher but we'd normally expect values like "development", "staging" and "production". If the name defined by the Launcher matches one in the "environments" section then the values in that section will be applied "on top" of the values found in the root of the .yaml file

More detailed information about the new Booster Catalog format etc, can be found here: HOWTO Create a Booster Catalog (Generic) and HOWTO Create a Booster Catalog (RHOAR)