A variety of object types may be used within Reflex Engine. This describes the attributes of each.

A higher level overview of some of the objects is available in the Overview.

• pipeline - The “top level” object which relates to sets of services.
• service - A specific service running for a single purpose, lane, region or tenant.
• config - configuration management
• instance - an instance of a service. many instances can relate to a single service
• build - a build of code, relates to a service
• policy - an ABAC Policy (tested on object access)
• policyscope - an ABAC Policy Scope (tested on object change)
• apikey - an API Key
• group - a grouping of API keys for policy management
• state - a general purpose state object

Flexible Schema

Many of the objects support a NoSQL schema-light model, where you can add your own attributes to them above and beyond what is defined herein. This is valuable for you to be able to extend things to meet your own needs. In particular, the state object is designed for general ad-hoc purposes.

Archived Copies

Some of the objects automatically create backups each time they are changed. These are:

• pipeline
• service
• config
• policy
• policyscope

You cannot delete archived copies of objects (by design). If you must delete them, it is only possible via direct db access to MySQL.

Todo: Exposing the archived list and copies via the CLI.

Soft Relationships

In some cases, such as the service and config objects, there are internal “soft” relationships that the Reflex Engine supports. This mechanism works such that if you submit a name of an object as part of an array that it knows about (such as config.extends) then at write time the Reflex Engine tries to map out the relationship to an ID. This is then translated into the format:

name.id

If it cannot find the object, it puts notfound in place of the numeric ID. This is okay, and is just an indicator to you that it cannot find the referenced object.

Whenever the relationship is resolved, Reflex Engine always will try to lookup by the id part of the identifier first (unless it is notfound). If that fails, it will try to lookup by the name part of the identifier.

This facilitates both performance and easy renaming of objects.

In some cases there are also hard relationships which are mapped by Reflex Engine under the hood. These will appear in your objects as something_id (such as pipeline_id on the service object, linking to its pipeline. You will not be able to change these attributes–they are always remapped at each store of the object, based on the something attribute.

Pipeline

The Pipeline is the top level object. Services refer to the Pipeline for their launch information.

Example:

{
    "name": "bct",
    "title": "Bat'leth Combat Training",
    "launch": {  },
    "monitor": [  ]
}

Launch Sub-object

Example:

{
    "launch": {
        "cfgdir": "/app/bct/config",
        "rundir": "/app/bct",
        "exec": [ "/usr/bin/node", "index.js" ]
    }
}

Monitor Sub-object

Used with the Monitor module.

|Type| value| Description |—-|-|- |name|string|base path to where configurations are stored |type|string|”http” is the only supported type |expect|object|Sub-object including:

• response-code (with int value) |query|object|see example |retry|int|how long to wait before trying on a failure |timeout|int|how long to wait before giving up on a response

Example:

    {
        "name": "bct-heartbeat",
        "expect": {
            "response-code": 204,
            "json": {"status": {"version": "17"}},
            "content": "version: 17",
            "regex": "version: [0-9]+",
            "headers": {"this-header": "that-result"}
        },
        "query": {
            "headers": {
                "Host": "the-hostname.cold.org"
            },
            "method": "GET",
            "path": "/api/v1/health"
        },
        "retry": 30,
        "timeout": 2,
        "type": "http"
    }

Service

The central pivot point referencing other objects.

Example:

{
  "name": "bct-tst",
  "active-instances":[
    "bct-p1ap1-blue"
  ],
  "static-instances":[ ],
  "dynamic-instances":[
    "bct-p1ap1-blue"
  ],
  "lane":"prd",
  "pipeline":"bct",
  "region":"saas1",
  "target":"bct-1610-0017",
  "tenant":"blue",
  "version-url":"https://{service}/api/v1/health"
}

Config

The higher level concepts behind Secrets and Configuratins are described separately.

There are two types of Configuration objects: Parameter, and File. If the type is File, then it should include a content section which describes how to store data as a file. Conventionally a parameter object exports to a File object.

You have three types of relationships between Config objects: Extends, Imports, and Exports. These relationships act differently to serve different purposes:

Extends

• Goes up a hierarchy, recursively
• Preference given to values lower in tree (child overrides parent)
• Ignored on exported target

Imports

• Merges a single object into current
• Preference given to values on imported object, not current
• Imports does not merge ‘extends’ nor ‘imports’ values
• Can be used on exported targets

Exports

• Exported objects are started as a clone of source object
• Attribute preference is given to target object values (they will override source object values).
• Extends is not processed on target objects (no hierarchy processed)
• Imports is processed on target objects
• Exported objects should be type=file, otherwise nothing happens

Exporting Configurations

There are a few ways to export configurations:

• A branch of the final configuration object can be inserted to STDIN (ideal)
• A branch of the final configuration object is saved as a JSON file
• Local files are processed for variable substitution: %{VARIABLE}
• An embedded file on a File object is decoded and saved to disk
• Parameters are set as process environment variables (dangerous when using secrets)

Variable Substitution

• Variables are substituted using the syntax: %{VARIABLE}

• The name of the variable is looked up on the configuration object (after it is flattened) by referencing sensitive.parameters as well as any other object references defined in the procvars array.

• All referenced object values must be strings or numbers. Arrays or sub-objects are ignored.
• Variables may reference values that in turn have variables. All variables are fully resolved. If the following process variables were used:

{
    "sensitive": {
      "parameters": {
        "ENV": "tst",
        "NAME": "manage",
        "ENV-SUFFIX": "-%{ENV}",
        "FULL-NAME": "%{NAME}%{ENV-SUFFIX}"
      }
    }
}

And the contents of a file to process were:

hostname="%{FULL-NAME}"

The result would be:

hostname="manage-tst"

Config Type=parameter

Config Type=file

Config Content sub-object

Example Config

In the following examples, we reference a set of objects: bct-tst (target config from the Service), bct (parent config) and bct-config1, bct-config2 and bct-keystore (exported objects). There should be a pre-existing file named local.xml.in, which is processed for variables including %{DB_URL}. Can you determine what the result of processing this would be?

{
    "name": "bct",
    "type": "parameter",
    "extends": ["common"],
    "exports": ["bct-config1", "bct-config2"],
    "sensitive": {
        "parameters": {
            "MONGO-URI":"mongodb://%{MONGO-HOSTS}/%{MONGO-DBID}"
        }
    },
    "setenv": {
        "MONGO-URI": "%{MONGO-URI}"
    }
}

{
    "name": "bct-tst",
    "type": "parameter",
    "extends": ["bct"],
    "exports": ["bct-keystore"],
    "procvars": ["sensitive.config.db"],
    "sensitive": {
        "parameters": {
            "MONGO-USER":"test_user",
            "MONGO-PASS":"not a good password",
            "MONGO-HOSTS":"test-db",
            "MONGO-DBID":"test_db"
        },
        "config": {
            "db": {
                "server": "%{MONGO-HOSTS}",
                "db": "%{MONGO-DBID}",
                "user": "%{MONGO-USER}",
                "pass": "%{MONGO-PASS}",
                "replset": {
                    "rs_name": "myReplicaSetName"
                }
            }
        }
    }
}

{
    "name": "common",
    "type": "parameter",
    "sensitive": {
        "parameters": {
            "SHARED-SECRET":"moar"
        }
    }
}

{
    "name": "bct-config1",
    "type": "file",
    "content": {
        "source": "local.xml.in",
        "dest": "local.xml",
        "varsub": true
    }
}

{
    "name": "bct-config2",
    "type": "file",
    "content": {
        "dest":"local-production.json",
        "ref":"sensitive.config",
        "type":"application/json"
    }
}

{
    "name": "bct-keystore",
    "type": "file",
    "content": {
        "dest":"local.keystore",
        "ref":"sensitive.data",
        "encoding": "base64"
    },
    "sensitive": {
        "data": "bm90IHJlYWxseSBhIGtleXN0b3JlIG9iamVjdAo="
    }
}

The output from evaluating these configurations with Launch Assist would be:

1. The environment variable MONGO_URI is set to: mongodb://test-db/test_db
2. The file local.xml is created (in the path specified in the Service Object’s cfgdir), by reading from the pre-existing local.xml.in file, performing variable substitution using values from sensitive.parameters.
3. The file local.keystore is written, using the embedded contents from sensitive.data
4. The file local-production.json is created, containing the JSON data:

{
    "db": {
        "server": "test-db",
        "db": "test_db",
        "user": "test_user",
        "pass": "not a good password",
        "replset": {
            "rs_name": "myReplicaSetName"
        }
    }
}

Instance

Instance Address sub-object

Build

Builds are useful in tracking software through a continuous delivery cycle.

Todo: Insert documentation and links to using builds and the release / promote command

Policy

Policies must also be matched to objects with a Policyscope entry.

Policyscope

Apikey

To generate a new APIkey, just create a new object with a name only, and it will generate the secrets for you.

The APIkey object is the name plus . and any one of the base64 elements of secrets.

Group

Groupings of Apikeys or Pipelines for easier policy management. When creating and updating a group, add the apikey names only (not secrets) to the group array.

State

The State object is a general purpose object. There are no required fields other than name

-

» Next: API Keys