Authentication Required
Skip to content
Lattice Docs System definitions reference

System definitions reference

System definitions

In Lattice, Systems are defined declaratively via JSON in System definition templates.

System definitions are structured as trees. At the root is the top-level System. This top-level System may have subsystems (childen) that are either Systems or Services. At the leaves are the Service definitions, where each Service has a type cooresponding to a valid Service type.

For instance, one might want to model a system with the following logical structure:

<root>                     // System 
  |- front-end             // System 
  |  |- www                // Service: Web server that serves the static content for the UI 
  |  |- public-api         // Service: Node.js REST API 
  |- back-end              // System 
  |  |- private-api        // Service: Python REST API 
  |  |- work-queue         // System 
  |  |  |- queue-api       // Service: Node.js REST API 
  |  |  |- queue-workers   // Service: Node.js 
  |  |  |- queue-db        // Service: MongoDB 3-node Replica Set 
  |  |- app-db             // Service: Postgres database 
  |

One can do this in Lattice by defining a System tree JSON (in one or many files) that represents this hierarchy.

Schema

Nodes of type System have the following form:

{
  type: "System"       // required
  name: <name>,        // required
  subsystems: [        // optional
    <subsystem_0>,
    .
    .
    .
    <subsystem_N>
  ]
}

where subsystem_i is either a System or a Service. With this recursive structure one can form arbitrarily complex System definitions.

Properties

Name Type Required Description
name string true System name
type string true Type. Must be value "System"
subsystems Array false List of subsystems

Example

{
  "type": "System",
  "name": "AirTunes",
  "subsystems": [
    { "$include": { "url": "front-end.json" } },
    { "$include": { "url": "back-end.json" } }
  ]
}

Service definitions

Properties

Name Type Required Description
name string true Service name
type string true Type. Must be a valid service type.

Example

{
  "type": "Service",
  "name": "api",
  "description": "Backend API for Petflix app",

  "components": [
    {
      "name": "api",
      "ports": [
        {
          "name": "http",
          "port": 80,
          "protocol": "HTTP"
        }
      ],
      "build": {
        "git_repository": {
          "url": "https://github.com/mlab-lattice/example-petflix-service",
          "tag": "v1.3.1"
        },
        "language": "node:boron",
        "command": "npm install"
      },
      "exec": {
        "command": [
          "node",
          "index.js"
        ],
        "environment": {
          "MONGODB_URI": "mongodb://mongodb.petflix.local:27017/petflix",
          "PORT": "80"
        }
      }
    }
  ],
  "resources": {
    "num_instances": 1,
    "instance_type": "t2.small"
  }
}

Secrets

Machine Pools

Jobs

Templating

Variables ($variables)

Templates can define variables via a $variables definition block:

{
  "$variables": {
    <name_0>: <value_0>,
    .
    .
    .
    <name_N>: <value_N>
  }
}

Example

{
  "$variables": {
    "systemName": "petflix",
  },

  "type": "System",
  "name": "${systemName}",
  .
  .
  .
}

The variables can later be accessed in expressions. In the above example we define the variable systemName and use it via the expression "${systemName}".

Expressions

Any rval may contain an expression. Expressions are are enclosed in double quotes and evaluate to a value of whatever type the expression evaluates to (e.g. boolean, string, etc...).

Expressions take the following form:

"${<variable>|<parameter>}"

Example

{
  "$variables": {
    "systemName": "petflix",
  },

  "type": "System",
  "name": "${systemName}",
  .
  .
  .
}

Parameters

Any file that defines a System definition template can formally declare parameters via a $parameters definition block:

{
  "$parameters": {
    <name_0>: { 
      "required": <boolean>,
      "default": <value>,
    },
    .
    .
    .
    <name_N>: { 
      "required": <boolean>,
      "default": <value>,
    },
  }

  "type": "System",
  "name": "${systemName}",
  .
  .
  .
}

Parameter values can be confured as required (default is false) or with a default (default is null), but not both.

Example

{
  "$parameters": {
    "systemName": {
      "required": true
    }
  }

  "type": "System",
  "name": "${systemName}",
  .
  .
  .
}

Include

The Systems you define in Lattice can be large and complex. As such, it is best practice to break your System definitions into many files in order to manage the complexity.

Furthermore, because System definition files are templates that can take parameters, it is easy to compose new Systems out of re-usable sub-systems, even sub-systems published by third parties and hosted in other Github repositories.

The templating language allows definition files to include other files via the $include directive.

{
  "$include": {
    "url": <string>,
    "parameters": {
      <name_0>: <value_0>,
      .
      .
      .
      <name_N>: <value_N>
    }
  }
}

Example

{
  "type": "System",
  "name": "petflix",
  "subsystems": [
    { "$include": { "url": "www.json" } },
    { "$include": { "url": "api.json" } },
    { 
      "$include": { 
        "url": "mongodb.json",
        "parameters": {
          replicas: 5
        }
      } 
    }
  ]
}