This document is a work in progress.

Seiso supports a variety of methods for managing your service data, such as sourcing data from existing data sources. But sometimes there isn't an existing source for the data you want to see in Seiso.

One approach to solving this problem is to create version controlled files, and then use the Seiso Master Importer to sync the files to Seiso. We call these files _Seiso data masters_ since they're intended to be authoritative for the data they contain. (For an overview, see the guide Manage Your Service Data with GitHub, Jenkins & Seiso.)

This guide explains in a hands-on way how to work with data masters. I'll assume that you already know JSON since the examples require that. If you don't actually know it, though, it's pretty easy to decipher.

1 General notes

This section covers some general considerations before we get into the specifics surrounding given data types.

1.1 Repository organization and layout

It's up to you or your organization to decide how you want to organize your services into repositories, and how you want to lay out individual repos.

Regarding organizing services into repos, if you don't have that many services, you might opt to go with a single repo that contains all of your service data. If you have a lot of services then you might prefer to group related services together in a repo. Totally up to you.

Within a given repo you can organize the files however you like. You can create directories, a hierarchy of directories, a single flat directory, whatever. Basically you'll have some script that invokes the importer against those files, and the script will need to know the scheme you're using.

Finally, we're assuming here that you're using version control, and we're even assuming for the sake of discussion that you're using Git, but neither of those is required. You could have a bunch of files on your desktop and just import them manually if you wanted to. Not necessary recommending that approach, but Seiso doesn't know or care.

1.2 Seiso data master schemas

Each data type has its own schema. This guide describes those and gives examples. For reference materials please see the appendix entitled Seiso Data Master Schemas in the Seiso User Manual.

In general, a top-level data type will have a type field and an items field. The type field, as you might guess, indicates the data type so you don't have to keep specifying it every time you run the importer. The items field is an array containing the data items themselves.

Some fields are identified as references. References have to be identifiers, not free-form text. The field used for identifying a given item depends on its type; key is pretty common, but in some cases it's something else (name, username, etc.).

1.3 Supported file formats

The Seiso Master Importer supports two file formats: JSON and YAML. In this guide I'll use the JSON format just because more people seem to know it, but if you prefer to use YAML, it's a straightforward translation. For reference, here's an example of the YAML format:

%YAML 1.1
---
type: services

items:

- key: seisodb
  name: Seiso Database
  description: MySQL database for devops data.
  group: devops
  type: database
  platform: "MySQL 5.6.22 (AWS RDS)"
  owner: willie
  scmRepository: https://github.com/ExpediaDotCom/seiso

- key: seiso
  name: Seiso
  description: Open source devops data integration service. Includes a REST API and a web UI.
  group: devops
  type: app-web-service
  platform: Java
  owner: willie
  scmRepository: https://github.com/ExpediaDotCom/seiso
  docLinks:
  - title: Seiso Project Site
    href: http://seiso.io
    description: Seiso service project site.
  - title: Seiso Ops Guide
    href: https://github.example.com/pages/ops-guides/seiso/
    description: Seiso service operations manual.
  - title: Adding New Services to Seiso
    href: https://github.example.com/seiso-data/common
    description: Explains how to use the Seiso data repositories to add new services to Seiso.
---

2 Services (type: services)

Services are a central concept in Seiso. The Seiso User Manual contains a reasonably detailed discussion.

2.1 Example

{
  "type" : "services",
  "items" : [
    {
      "key": "eos",
      "name": "Eos",
      "description": "Automated operational decisioning and response",
      "group": "devops",
      "type": "agent",
      "platform": ".NET",
      "owner": "mike",
      "scmRepository": "https://github.example.com/EWE/eos",
      "docLinks": [
        {
          "title": "Eos Overview",
          "href": "https://confluence/display/eweoa/EOS",
          "description": "Describes features, architecture, operations and support."
        },
        {
          "title": "Eos Self-Service: Remediation",
          "href": "https://confluence/display/eweoa/Eos+Self-Service%3A+Remediation",
          "description": "Guide to setting up self-service remediation in Eos."
        }
      ]
    },
    {
      "key": "eosworker",
      "name": "EosWorker",
      "description": "Farm of workers Eos uses to perform actions",
      "group": "devops",
      "type": "web-service",
      "platform": null,
      "owner": "mike",
      "scmRepository": null
    },
    {
      "key": "eosrouter",
      "name": "EosRouter",
      "description": "Router for abstracting which brain is hosting which service instances",
      "group": "devops",
      "type": "web-service",
      "platform": null,
      "owner": "mike",
      "scmRepository": null
    }
  ]
}

2.2 Description

indicates a required field.

Field Description Reference via Max length (chars)
key Globally unique identifier for the service. 40
name Globally unique display name. 200
description Short service description. 250
group Service group containing this service. key
type Service type. key
platform Software platform. E.g., Java, .NET, NodeJS, etc. This is just descriptive, free-form text. 80
owner Service owner (a person). username
scmRepository Link to SCM repository. 250
docLinks List of links to external documentation.
docLinks.title Link title. 250
docLinks.href Link URL. 250
docLinks.description Short link description. 250

3 Service instances (type: service-instances)

Service instances are essentially services bound to a given environment. See the Seiso User Manual for a detailed explanation.

3.1 Example

{
  "type" : "services",
  "items" : [
    {
      "key": "air-shopping-prod",
      "service": "air-shopping",
      "environment": "prod",
      "description": "Primary Air Shopping instance in production.",
      "dataCenter": "amazon-us-west-1a",
      "loadBalanced": true,
      "loadBalancer": "PROD-10-1-1-1",
      "minCapacityDeploy": 50,
      "minCapacityOps": 75,
      "ipAddressRoles": [
        {
          "name": "default",
          "description": "Default IP address role"
        }
      ],
      "ports": [
        {
          "number": 443,
          "protocol": "https",
          "description": null
        }
      ],
      "dependencies": [
        {
          "key": "air-gds-prod"
        },
        {
          "key": "air-search-prod"
        }
      ]
    },

    ... other service instances ...
  ]
}

3.2 Description

indicates a required field.

Field Description Reference via Max length (chars)
key Globally unique identifier for the service instance. 40
service Reference to the service instance's service. key
environment Reference to the service instance's environment. key
description Service instance description. Useful if the service instance has a special purpose that you want to advertise. 250
dataCenter Reference to the service instance's data center. key
loadBalanced Boolean (true|false) indicating whether the service instance is load balanced.
loadBalancer Reference to the service instance's load balancer, if any. name
minCapacityDeploy Hint to deployment services indicating the minimum node capacity to maintain at any given time during the deployment, expressed as a percentage in the range 0-100.
minCapacityOps Hint to automated remediation services indicating the minimum node capacity to maintain at any given time during normal operations, expressed as a percentage in the range 0-100.
ipAddressRoles List of IP address roles for the service instance. The idea is that some service instances have multiple IP addresses, and so each role allows you to define the name and description/purpose of your IP addresses.
ipAddressRoles.name IP address role name. If you have only one, prefer "default" as a name. 80
ipAddressRoles.description IP address role description. 250
ports Service instance port list, as appearing on individual nodes (as opposed to on the load balancer public interface).
ports.number Port number. Must be in the range 0-65535.
ports.protocol Free-form text stating the protocol (e.g., http, https, ldap, etc.). 40
ports.description Port description (e.g., how the service instance uses it). 250
dependencies List of (downward) dependencies for this service instance. Dependencies are service instances. We use a list of objects here instead of a list of strings because we anticipate adding other fields to individual dependencies.
dependencies.key The dependency's key. Again the dependency is a service instance. key