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
		changelog	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
anyOf		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