Syslab

Docs/References/Configuration file format

Configuration file format

Syslab .sl service configuration file format reference

Overview

Syslab configuration files are YAML formatted text files that has the extension .sl. When you connect a code repository, we automatically pick up any configuration files in your repo and create a corresponding service.

Each configuration file represents a single service. It is entirely up to you how you where to put this file. In a monorepo, you can create multiple configuration files for your services, or perhaps just one file per repo for a multi-repos setup.

Learn more about YAML syntax


Fields

The following are all fields valid in a .sl file. A * denotes a required field

syslab*

The syslab is a required number value that specifies the version of the configuration file format that will be used. Valid values: 1

Example:

syslab: 1

handler*

handler is a required string value that specifies a unique reference for a service. A handler must be unique to a service in an organisation. You can think of this as your service's social media handler that you can reference on Syslab. Note that you do not need to use the @ symbol when specifying the handler. This value may include any lowercase alphanumeric characters and the following special characters: -.

Example:

handler: todo-service

name*

name is a required string value that specifies a name for a service. In contrast to handler, name does not have to be unique and can include any alphanumeric, spaces and special characters.

Example:

name: Todo Service

type

type is an optional string value that specify the type of a service. For instance, a service can be of type service for a microservice, website for a website asset or function for a serverless function. type can be of any value and is configurable in the "Service Type" section in your organisation's settings. If type specifies a value that has not been configured in your organisation's "Service Type" settings, a new service type will automatically be created for you.

By default, Syslab includes the following service types: service, website, queue, worker. If no type is specified, the service will be created with the service type.

Example:

type: service

version

version is an optional string value that specifies the current version of a service.

Example:

version: 1.0.1

description

description is an optional string value that includes additional information about a service

Example:

description: A service responsible for managing todo lists for our users

documentationUrl

documentationUrl is an optional string value that specifies a URL where the documentation for a service can be found. It accepts any valid URI schemes.

Example:

documentationUrl: https://internal.acme.co/docs/todo-service

owner*

owner is a required string field specifying the team that owns or is responsible for a service. Similar to handler, this fields accepts any alphanumeric characters and the special character -. This field links the owner to a service and allow updates and subscription to be automatically routed to interested teams. If the value of owner does not correspond to an existing team in your organisation, a new team will automatically be created.

Example:

owner: todo-team

dependencies

dependencies is an optional list of string that specifies the handlers of services that a service depends on. The values inside dependencies follows the same restrictions as the handler field and references other services. If a specified service does not exist, the dependency will still be created but a warning will be displayed.

Example:

dependencies:
  - profile-service
  - notification-service

facts

facts is an optional list of objects that specify a list of key values "facts" about a service. Facts can be used to specify any information about a service, such as its technology stack, SLA, instant message channel, tier, etc...

Each list item must specify 2 properties: name and value, both are required strings that specify the label and value of a fact.

Example:

facts:
  - name: language
    value: go
  - name: channel
    value: #todo-service-engineering

links is an optional list of objects that specify links to resources related to a service. You can use this field to add links to external dashboard, code repositories, build pipelines, etc...

Each list item must specify 2 properties: name and value, both are required strings that specify the label and value of a fact. value must be a valid URL.

Example:

links:
  - name: issue tracker
    value: https://issue-tracker.com/todo-service
  - name: metrics
    value: https://metrics.acme.co/todo-service