Templates

Templates Directory

On startup, Cluster Broccoli tries to read job templates from the templates directory. The default location is templates, but it can be configured by setting broccoli.templates.storage.fs.url.

The directory must contain one sub-directory for each template. These template directories contain a template for a Nomad job (template.json) and an optional file with meta information (meta.json).

Example Directory Layout

templates
├── http-server
│   ├── meta.json
│   └── template.json
├── jupyter
│   └── template.json
└── zeppelin
    ├── meta.json
    └── template.json

Template Definition

Nomad JSON Template File

The template file is basically a Nomad job file in JSON format. In order to allow for customization (e.g. launching multiple instances of the same job with different names or settings), you can add parameters. A parameter is enclosed in two curly brackets ({{...}}).

Each template has to have at least a parameterized job ID:

{
    "Job": {
        "Region": "global",
        "ID": "{{id}}",
        "Name": "{{id}}",
        ...
    }
}

For your convenience you can write the job in HCL syntax and convert it using nomad run -output template.hcl > template.json.

Meta Information File

Currently you can provide three types of meta information about a template: A description, parameter information and a parameter type.

{
  "description": "A simple Python HTTP request handler. This class serves files from the current directory and below, directly mapping the directory structure to HTTP requests.",
  "parameters": {
    "cpu": {
      "default": "100",
      "type": "raw"
    },
    "password": {
      "secret": true,
      "type": "string"
    }
  }
}

Description

The description can be used to briefly describe your template. It will be shown in the user interface to explain what to expect when creating a new instance based on this template.

{
  "description": "This is my great Broccoli template. Apply gently for extreme awesomeness!"
}

Parameter Information

The template file usually contains different parameters. These parameters can have additional properties.

Default Values

In order to avoid having to fill all parameter values on instance creation you can provide default values.

{
  "parameters": {
    "cpu": {
      "default": "100"
    }
  }
}

Secret Parameters

Sometimes you want parameters to be not visible to non-administrators. In this case you can mark a parameter as 'secret'.

{
  "parameters": {
    "password": {
      "secret": true
    }
  }
}

Parameter types

Every parameter has a type. The parameter value will be rendered according to the type.

{
  "parameters": {
    "password": {
      "type": "string"
    }
  }
}

The following parameter types are supported:

Type	Description	Input	Output
string	Convert the value to a valid JSON String.	"{{statement}}"	"Frank likes \"fish\""
raw	Insert the value without any conversion. Use with caution!	"{{statement}}"	"Frank likes "fish""

When the parameter type is not explicitly specified broccoli.instances.parameters.defaultType is used.