Configuration Files

Unfurl’s configuration files are validated according to the JSON schemas described below. (Note: Required properties are in bold.)

Files

ensemble.yaml

apiVersion: unfurl/v1alpha1
kind: Ensemble
# the context will be merged with the corresponding context in the project config:
context:
  # local and secret are special cases that must be defined in the local config
  local:
   schema:
     name1:
       type: string
  secret:
   schema: # expected JSON schema for attributes
     name1:
       type: string
  # environment:
  # runtime:
  external:
    name: # manifest to represent as a resource
      manifest:
        file: .
      instance: "*" # name or "*", default is "root"

spec:
  service_template:
    topology_template:
      node_templates:
        aNodeTemplate:
          type: tosca:Root
    # tosca service template goes here
status:
  # inputs:
  # outputs:
  instances:
    name: # root resource is always named "root"
      template: aNodeTemplate
      attributes:
        .interfaces:
          interfaceName: foo.bar.ClassName
      priority: required
      readyState:
        local: ok
        state: created
      lastConfigChange: A1312XNB0001
      lastStateChange: A1312XNB0001
      created: true
      instances:
        child1:
          template: aNodeTemplate
          # ...
changeLog: changes.yaml
lastJob:
  changeId: A0920aMf0000
  startTime: 2020-09-02-00-36-22-664763
  workflow: deploy
  options:
    force: true
  summary: 1 tasks (1 changed, 1 ok, 0 failed, 0 unknown, 0 skipped)
  startCommit: 628c2a4b633a26c1e8b1c116d3fdeef9bca89716
  specDigest: 037815dc8b56254219a96f359fd996c65e7d0754
  priority: required
  readyState:
    local: ok

ensemble.yaml

type

object

properties

  • apiVersion

type

string

const

“unfurl/v1alpha1”

  • kind

type

string

enum

Manifest, Ensemble

  • metadata

type

object

properties

  • uri

type

string

format

uri

  • aliases

type

array

items

type

string

format

uri

  • context

context

  • spec

type

object

anyOf

properties

  • service_template

a TOSCA service template

type

object

properties

  • instances

namedObject

  • status

type

object

default

{}

allOf

properties

  • inputs

attributes

  • outputs

attributes

  • instances

instances

Status

  • lastJob

Job Record

  • changeLog

type

string

  • jobsFolder

type

string

  • changes

Changes

job.yaml

manifest: ../ensemble.yaml
changes:
- changeId: A0AP4P9C0000
  startTime: 2020-10-25-04-25-09-199310
  previousId: A0AP4OM20000
  workflow: deploy
  options: {}
  summary: 2 tasks (1 changed, 2 ok, 0 failed, 0 unknown, 0 skipped)
  specDigest: 925f61f8c2b3153f2e2e60ffb800f48720095a9a
  priority: required
  readyState:
    effective: error
    local: ok
- changeId: A0AP4P9C0001
  target: ::my_server
  priority: required
  readyState:
    local: ok
  implementation:
    operation: check
    className: unfurl.configurators.terraform.TerraformConfigurator
  inputs: {}
  result:
    args:
    - terraform
    - refresh
    - -state=/Users/adam/_dev/unfurl/tests/examples/my_server/local/terraform.tfstate.json
    - -var-file=/Users/adam/_dev/unfurl/tests/examples/my_server/local/vars.tfvars.json
    returncode: 0
    stdout: >
      Empty or non-existent state file.
    stderr: ''
    cmd: terraform refresh -state=/Users/adam/_dev/unfurl/tests/examples/my_server/local/terraform.tfstate.json
      -var-file=/Users/adam/_dev/unfurl/tests/examples/my_server/local/vars.tfvars.json

job.yaml

List of jobs ran with changes applied

type

object

properties

  • manifest

type

string

  • changes

Changes

unfurl.yaml

  apiVersion: unfurl/v1alpha1
  kind: Project

  contexts:
    defaults: # "defaults" are merged with optional contexts defined below
      local:
       schema:
         name1:
           type: string
      secret:
       schema:
         name1:
           type: string

      # # values are merged with the manifest's context:
      # inputs:
      # locals:
      # secrets:
      # environment:
      # external:
    # user-defined contexts:
    production: {}
    staging: {}

  manifests:
    - file: ""
      repository: ""
      # default instance if there are multiple instances in that project
      # (only applicable when config is local to a project)
      default: True
      context: production # "defaults" context is used if not specified

unfurl.yaml

Unfurl configuration file

type

object

properties

  • apiVersion

const

“unfurl/v1alpha1”

  • kind

const

“Project”

  • manifests

type

array

items

type

object

properties

  • file

type

string

  • default

type

boolean

  • context

type

string

  • contexts

type

object

allOf

namedObject

additionalProperties

context

  • projects

type

object

allOf

namedObject

additionalProperties

type

object

properties

  • url

type

string

format

uri

  • initial

type

string

  • file

type

string

  • localRepositories

Map of file paths located outside of the project

type

object

additionalProperties

./manifest-schema.json#/definitions/repositories

Sections

context

type

object

properties

  • inputs

attributes

  • runtime

type

string

  • environment

type

object

  • locals

External

  • secrets

External

  • connections

namedObject

  • external

type

object

allOf

namedObject

additionalProperties

External

Instance

type

object

allOf

properties

  • template

type

string

  • attributes

default

{}

attributes

  • instances

instances

  • capabilities

instances

  • requirements

instances

  • imported

type

string

Status

External

Declare external instances imported from another manifest.

type

object

properties

  • manifest

type

object

properties

  • file

type

string

  • repository

type

string

  • project

type

string

  • uri

type

string

format

uri

  • instance

type

string

  • schema

attributes

  • attributes

attributes

Status

type

object

properties

  • readyState

type

object

properties

  • effective

readyState

  • local

readyState

  • state

state

  • priority

type

string

enum

ignore, optional, required

  • lastStateChange

changeId

  • lastConfigChange

changeId

additionalProperties

True

Job Record

type

object

allOf

Status

properties

  • changeId

changeId

  • previousId

changeId

  • startCommit

type

string

  • startTime

Timestamp

  • workflow

type

string

  • options

type

object

  • summary

type

string

  • specDigest

type

string

  • endCommit

type

string

Task Record

type

object

allOf

properties

  • changeId

changeId

  • target

type

string

  • implementation

implementation definition

  • inputs

attributes

  • changes

default

{}

allOf

namedObject

additionalProperties

namedObject

  • dependencies

type

array

items

type

object

properties

  • name

type

string

  • ref

type

string

  • expected

  • schema

schema

  • required

type

boolean

  • messages

type

array

  • result

oneOf

enum

skipped

type

object

Status

implementation definition

type

object

properties

  • operation

type

string

  • className

type

string

  • majorVersion

Generic Version Identifier

  • minorVersion

type

string

Changes

change log entry

type

array

items

type

object

anyOf

Job Record

Task Record

Definitions

Enums and Simple Types

readyState

The operational status of the instance

type

string

enum

unknown, ok, degraded, error, pending, absent

state

the operational state of the instance

type

string

enum

initial, creating, created, configuring, configured, starting, started, stopping, stopped, deleting, deleted, error

changeId

type

string

pattern

^A[A-Za-z0-9]{11}$

Timestamp

type

string

format

date-time

Generic Version Identifier

anyOf

type

string

type

number

Reusable helper definitions

instances

type

object

allOf

namedObject

additionalProperties

Instance

attributes

type

object

default

{}

namedObject

atomic

indicates these properties must be set all at once or replaced

type

object

namedObject

constrains how properties are named

type

object

propertyNames

pattern

^[A-Za-z._][A-Za-z0-9._:-]*$

schema

a JSON Schema definition

type

object