Specification for platforms file

Generic format

This is the general description of the platform format. This will be used when selecting the right supported languages and toolchains based on platform. In this way, we have the flexibility of having a separate lifecycles file and toolchains file on a per platform basis.

defaults:
  platform: somePlatform
  os: someOS
  stability: stable
  sudo: nosudo
supported_platforms:
  somePlatform:
    someOS:
      language:
        - groovy
        - java
        - python
        - ruby
      toolchain:
        - env
        - gemset
        - rvm
        - python
        - jdk
restrictions:
  somePlatform:
    only_organizations:
      - samrocketman
      - someorg
    only_projects:
      - org/project

Generic format Legend

1. defaults - Is a key to specify configuration defaults for what platform/OS jobs will use if they don't specify any. Validation: this key is required. The name of the key can't change. The value of the key is a Map.
2. platform - Specifies the default platform jobs will use if they don't specify any. Validation: this key is required. The name of the key can't change. The value of the key is a String. The value must exist as a key in supported_platforms.
3. os - Specifies the default OS jobs will use if they don't specify any. Validation: this key is required. The name of the key can't change. The value of the key is a String. The value must exist as a key inside of the default platform in supported_platforms.
4. stability - Specifies the default stability label jobs will use if they don't specify any. Validation: this key is required. The name of the key can't change. The value of the key is a String. The value must be either stable or unstable.
5. sudo - Specifies the default sudo label jobs will use if they don't specify any. Validation: this key is required. The name of the key can't change. The value of the key is a String. The value must be either sudo or nosudo.
6. supported_platforms - Is a full index of all platforms supported by a build system. A platform consists of a name, the operating system, languages supported on that OS, and software build toolchains supported on that OS. Validation: this key is required. The name of the key can't change. The value of the key is a Map.
7. somePlatform - Is the name of a platform. This can be called anything. It is recommended to be named in a way that makes sense for the infrastructure. For instance, a platform might be called docker because it is all docker containers (with multiple operating systems). Validation: key is optional unless there are no platforms. The name of the key is variable (e.g. docker). The value of the key is a Map. 1. someOS - Is the name of an operating system. This can be called anything. It is recommended to be named in a way that makes sense for the infrastructure. For instance, an operating system might be Ubuntu 14.04 so a recommended name might be ubuntu1404. Validation: key is optional unless there are no other OS keys for this platform. The name of the key is variable (e.g. ubuntu1404). The value of the key is a Map.
   1. language - What languages can be built on this platform and OS? This key specifies what languages are supported. Validation: key is required if someOS is present. The name of the key can't change. The value of the key is an ArrayList of Strings.
   2. toolchain - What toolchains are available on this platform and OS? This key specifies what toolchains are supported. Validation: key is required if someOS is present. The name of the key can't change. The value of the key is an ArrayList of Strings.
8. restrictions - sometimes you don't want just anybody to be able to build on a platform. Restrictions restrict who is allowed to build on this platform. Validation: this key is required. The name of the key can't change. The value of the key is a Map.
9. somePlatform - is the name of the restricted platform. Restrict who can use this platform. Validation: key is optional. A key of the same name must exist in supported_platforms key. The name of the key is variable (e.g. docker). The value of the key is a Map. 1. only_organizations - All projects within this white list of organizations or usernames can make use of this platform. Validation: This key is optional. The value of this key is an ArrayList. 1. only_projects - Only specific projects in this white list can make use of this platform. Validation: This key is optional. The value of this key is an ArrayList.

A more specific platform example

defaults:
  platform: docker
  os: ubuntu1404
  stability: stable
  sudo: nosudo
supported_platforms:
  docker:
    centos6x:
      language:
        - groovy
        - java
        - python
        - ruby
      toolchain:
        - env
        - gemset
        - rvm
        - python
        - jdk
    ubuntu1404:
      language:
        - groovy
        - java
        - python
        - ruby
      toolchain:
        - env
        - gemset
        - rvm
        - python
        - jdk
  metal:
    centos6x:
      language:
        - groovy
        - java
        - python
        - ruby
      toolchain:
        - env
        - gemset
        - rvm
        - python
        - jdk
restrictions:
  metal:
    only_organizations:
      - samrocketman
      - someorg
    only_projects:
      - org/project

When someone loads a platform for the first time in the Job DSL code. They could override the default platform, operating system, and agent stability. The agent stability is a simple concept that just allows stable agents to be for the majority of the build system and unstable agents for toolchain and language experimentation.

import net.gleske.jervis.lang.LifecycleGenerator
def x = new lifecycleGenerator()
x.loadPlatforms('/path/to/platform.yaml')
x.label_platform = 'docker'
x.label_os = 'ubuntu1404'
x.label_stability = 'stable'
x.label_sudo = 'nosudo'

Example yaml files and outputs

A simple ruby YAML file.

language: ruby

If a platform is not specified in the YAML then the default platform will be used. The following Jenkins labels will be output.

stable&&nosudo&&docker&&ubuntu1404&&language:ruby&&gemfile&&env&&rvm&&jdk

If a user wishes to override the default platform then they will need to do so via the jenkins YAML key.

language: "ruby"
jenkins:
  unstable: true
  sudo: true
  platform: "docker"
  os: "centos6x"

The label expression in Jenkins of the YAML overriding settings will look like the following.

unstable&&sudo&&docker&&centos6x&&language:ruby&&gemfile&&env&&rvm&&jdk