@toa.io/extensions.configuration

Toa Configuration

TL;DR

Define

# manifest.toa.yaml
name: dummy
namespace: dummies

configuration:
  schema:
    foo: string
    bar: number
  defaults:
    foo: bar
    bar: 1

Use

function transition (input, entity, context) {
  const { foo, bar } = context.configuration

  // ...
}

Override

# context.toa.yaml
configuration:
  dummies.dummy:
    foo: qux          # override default value
    foo@staging: quux # deployment environment discriminator
    bar: $BAZ_VALUE   # secret

Deploy secrets

$ toa conceal configuration BAZ_VALUE=$ecr3t

---

Problem Definition

• Components should be runnable in different deployment environments.
• Some algorithm's parameters should be deployed secretly.
• Components should be reusable in different contexts.

Manifest

Component's configuration is declared using configuration manifest, containing schema and optionnaly defaults properties.

Schema

Configuration schema is declared with COS.

# manifest.toa.yaml
name: dummy
namespace: dummies

configuration:
  schema:
    foo: string
    bar: number

Introducing non-backward compatible changes to a configuration schema will result in a loss of compatibility with existing contexts and deployment environments. Therefore, configuration schema changes are subject to component versioning.

If configuration object doesn't contain property schema, then it is considered to be schema.

# manifest.toa.yaml
name: dummy
namespace: dummies

configuration:
  foo: string
  bar: number

Defaults

The default configuration value can be provided using the defaults property, which should conform to the configuration schema.

# manifest.toa.yaml
name: dummy
namespace: dummies

configuration:
  schema:
    foo: string
    bar: number
  defaults:
    foo: hello
    bar: 0

Schema defaults hint

The configuration schema itself can contain default primitive values using the COS syntax.

# manifest.toa.yaml
name: dummy
namespace: dummies

configuration:
  schema:
    foo: hello
    bar: 0

Annotation

A component's configuration can be overridden using the configuration context annotation.

# context.toa.yaml
configuration:
  dummies.dummy:
    foo: bye
    bar: 1
    bar@staging: 2

Secrets

Configuration annotation top-level values which are uppercase strings prefixed with $ considered as secrets.

# context.toa.yaml
configuration:
  payments.gateway:
    api-key: $STRIPE_API_KEY

Secrets are not being deployed with context deployment (toa deploy), thus must be deployed separately at least once for each deployment environment manually (toa conceal).

Deployed kubernetes secret's name is predefined as configuration.

$ toa conceal configuration STRIPE_API_KEY=xxxxxxxx

Aspect

Component's configuration values are available as a well-known Aspect configuration.

function transition (input, entity, context) {
  const foo = context.configiuration.foo

  // ...
}