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
          # ...
lastJob:
  changeId: A0920aMf0000
  startTime: 2020-09-02-00-36-22-664763
  changelog: jobs/job2020-09-02-00-36-22-664763.yaml
  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
jobLog: jobs.tsv

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

  • environment

environment

  • spec

type

object

properties

  • service_template

a TOSCA service template

type

object

  • inputs

attributes

  • instances

namedObject

  • deployment_blueprints

namedObject

  • resource_templates

namedObject

  • status

type

object

default

{}

allOf

properties

  • inputs

attributes

  • outputs

attributes

  • instances

instances

Status

  • lastJob

Job Record

  • jobsLog

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

  environments:
    defaults: # "defaults" are merged with optional contexts defined below
      locals:
       schema:
         name1:
           type: string
      secrets:
       schema:
         name1:
           type: string
      # # values are merged with the manifest's context:
      # inputs:
      # locals:
      # secrets:
      # variables:
      # external:
    # user-defined contexts:
    production: {}
    staging: {}

  ensembles:
    - file: "ensemble/ensemble.yaml"
      alias: "named_ensemble"
      project: "in_another_project"
      default: true
      environment: production # "defaults" context is used if not specified

unfurl.yaml

Unfurl configuration file

type

object

properties

  • apiVersion

const

“unfurl/v1alpha1”

  • kind

const

“Project”

  • ensembles

type

array

items

type

object

properties

  • file

Path to ensemble manifest, relative to the the project it is located in.

type

string

  • project

The project the ensemble is located in if different from the current project.

type

string

  • managedBy

The project that is managing the ensemble if different from the current project.

type

string

  • default

Use this ensemble if not is specified.

type

boolean

  • alias

Alternative name to specify this ensemble on the command line instead of its file path

type

string

  • environment

The name of the environment to use for this ensemble.

type

string

  • environments

anyOf

type

object

propertyNames

pattern

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

additionalProperties

anyOf

environment

type

null

type

null

  • default_environment

type

string

  • 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

repositories

additionalProperties

False

Sections

environment

type

object

properties

  • inputs

attributes

  • defaultProject

type

string

  • name

type

string

  • deployment_blueprint

type

string

  • variables

anyOf

type

object

type

null

  • locals

attributes

  • secrets

attributes

  • connections

anyOf

namedObject

type

null

  • instances

namedObject

  • repositories

type

object

  • cloudmaps

type

object

  • imports

type

array

  • external

type

object

allOf

namedObject

additionalProperties

External

additionalProperties

True

Instance

type

object

allOf

properties

  • template

anyOf

type

object

type

string

  • attributes

default

{}

attributes

  • properties

attributes

  • instances

instances

  • capabilities

instances

  • requirements

type

array

items

instances

  • imported

type

string

  • protected

type

boolean

  • created

anyOf

type

boolean

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

additionalProperties

False

repositories

type

object

properties

  • name

type

string

  • url

type

string

format

uri

  • revision

intended revision (branch or tag) declared by user

type

string

  • commit

current commit

type

string

  • branch

current commit is on this branch

type

string

  • tag

current commit is on this tag

type

string

  • initial

initial commit

type

string

  • origin

origin url

type

string

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

  • endTime

Timestamp

  • workflow

type

string

  • options

type

object

  • summary

type

string

  • specDigest

type

string

  • endCommit

type

string

  • changelog

path to the full job record

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

default

{}

propertyNames

pattern

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

schema

a JSON Schema definition

type

object