Configuration Files

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

Files

ensemble.yaml

Example:

apiVersion: unfurl/v1.0.0
kind: Ensemble
metadata:
  uri: https://unfurl.cloud/user1/dashboard.git#:ensemble/ensemble.yaml
spec:
  service_template:
    # tosca service template goes here:
    topology_template:
      node_templates:
        aNodeTemplate:
          type: tosca:Root
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
lock:
  runtime:
    unfurl:
      version: 1.1.0
      digest: 9c2c1b4a
    toolVersions: {}
  package_rules:
    - "unfurl.cloud/onecommons/* #main"
    - "unfurl.cloud/onecommons/std github.com/user1/myfork"
  repositories:
    - url: http://unfurl.cloud/onecommons/std
      package_id: unfurl.cloud/onecommons/std
      commit: 2da68fe0d1014805d15fc9134352626cb136e066
      initial: 2da68fe0d1014805d15fc9134352626cb136e066
      discovered_revision: 1.0.0
      tag: v1.0.0 # current commit is on this tag

JSON Schema:

ensemble.yaml

type	object
properties
apiVersion	type	string
	enum	unfurl/v1alpha1, unfurl/v1.0.0
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 defaults
	environment
spec	type	object
	properties
	service_template	A TOSCA service template
		type	object
	inputs	attributes
	instances	namedObject
	deployment_blueprints	namedObject
	resource_templates	namedObject
	discovered	Discovered Node Templates
		namedObject
status	type	object
	default	{}
	allOf		properties
			inputs	attributes
			outputs	attributes
			instances	instances
			Status
lastJob	Job Record
jobsLog	type	string
changes	Optional list of changes. If missing, changes are saved as separate files
	Changes
lock	Lock

job.yaml

Example:

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

JSON Schema:

job.yaml

Record of an Unfurl job
type	object
properties
apiVersion	const	“unfurl/v1.0.0”
kind	const	“Job”
manifest	type	string
job	Job Record
changes	Changes

unfurl.yaml

Example:

  apiVersion: unfurl/v1.0.0
  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

JSON Schema:

unfurl.yaml

Unfurl configuration file
type	object
properties
apiVersion	type	string
	enum	unfurl/v1alpha1, unfurl/v1.0.0
kind	const	“Project”
ensembles	Ensembles contained in this project or managed by this project (but maybe located in a different project).
	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	The name of the environment to deploy into if none was specified for the ensemble in its configuration or by the command line).
	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
include_paths	If set, only register projects in these directories. (If no match, project is included, use “/” in exclude_paths to exclude all by default) (reserved, unused)
	anyOf		type	array
			items
				type	string
			type	null
exclude_paths	Don’t register projects in these directories (longest path wins if overlaps with an include_paths). (reserved, unused)
	anyOf		type	array
			items
				type	string
			type	null
additionalProperties	False

cloudmap.yaml

Example (from https://github.com/onecommons/cloudmap/blob/main/cloudmap.yaml):

apiVersion: unfurl/v1.0.0
kind: CloudMap
repositories:
  unfurl.cloud/onecommons/blueprints/mediawiki:
    git: unfurl.cloud/onecommons/blueprints/mediawiki.git
    path: onecommons/blueprints/mediawiki
    name: MediaWiki
    protocols:
    - https
    - ssh
    internal_id: '35'
    project_url: https://unfurl.cloud/onecommons/blueprints/mediawiki
    metadata:
      description: MediaWiki is free and open-source wiki software used in Wikipedia,
        Wiktionary, and many other online encyclopedias.
      issues_url: https://unfurl.cloud/onecommons/blueprints/mediawiki/-/issues
      homepage_url: https://unfurl.cloud/onecommons/blueprints/mediawiki
    default_branch: main
    branches:
      main: 0fc60cb3afd06ae2c4abe038007e9ff4db398662
    tags:
      v1.0.0: 0fc60cb3afd06ae2c4abe038007e9ff4db398662
      v0.1.0: 225932bc2a45473d682e48f272bc48fcd83909bb
    notable:
      ensemble-template.yaml#spec/service_template:
        artifact_type: artifact.tosca.ServiceTemplate
        name: Mediawiki
        version: 0.1
        description: MediaWiki is free and open-source wiki software used in Wikipedia,
          Wiktionary, and many other online encyclopedias.
        type:
          name: Mediawiki@unfurl.cloud/onecommons/blueprints/mediawiki
          title: Mediawiki
          extends:
          - Mediawiki@unfurl.cloud/onecommons/blueprints/mediawiki
          - SQLWebApp@unfurl.cloud/onecommons/std:generic_types
          - WebApp@unfurl.cloud/onecommons/std:generic_types
          - App@unfurl.cloud/onecommons/std:generic_types
        dependencies:
        - MySQLDB@unfurl.cloud/onecommons/std:generic_types
        artifacts:
        - docker.io/bitnami/mediawiki
...
artifacts:
  docker.io/bitnami/mediawiki:
    type: artifacts.OCIImage

JSON Schema:

CloudMap Schema

CloudMap Schema
type	object
properties
apiVersion	type	string
	enum	unfurl/v1alpha1, unfurl/v1.0.0
kind	const	“CloudMap”
repositories	type	object
	propertyNames	pattern	^[^s]*$
	additionalProperties	type	object
		properties
		git	type	string
		path	type	string
		initial_revision	type	string
		name	type	string
		protocols	type	array
			items
				type	string
		internal_id	type	string
		project_url	type	string
		mirror_of	type	string
		fork_of	type	string
		private	type	boolean
		default_branch	type	string
		metadata	type	object
			properties
			description	type	string
			topics	type	array
				items
					type	string
			spdx_license_id	type	string
			license_url	type	string
			issues_url	type	string
			homepage_url	type	string
			avatar_url	type	string
			lastupdate_time	type	string
			lastupdate_digest	type	string
		branches	type	object
			additionalProperties	type	string
		tags	type	object
			additionalProperties	type	string
		notable	type	object
			additionalProperties	type	object
				properties
				artifact_type	type	string
				name	type	string
				version	anyOf		type	string
							type	number
				description	type	string
				schema	type	string
				artifacts	type	array
					items
						type	string
artifacts	type	object
	propertyNames	pattern	^[^s]*$
	additionalProperties	type	object
		properties
		type	type	string

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	TOSCA repositories
	type	object
cloudmaps	type	object
	properties
	repositories	type	object
	hosts	type	object
imports	type	array
external	type	object
	allOf		namedObject
			additionalProperties	External
lfs_lock	Configure the global git lfs lock for jobs. See Job Locking
	type	object
	properties
	lock	Whether to use git lfs when locking an ensemble. ‘try’ use locking if lfs is available; ‘require’ means error if unable to lock
		type	string
		enum	no, try, require
		default	no
	name	Name of the lock file
		type	string
	url	Git LFS server url; if missing, use the ensemble’s git repository
		type	string
		format	uri

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
		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
version	Imported template requires compatible version.
	Generic Version Identifier
connections	List of connection names to import.
	type	array
	items
		type	string
additionalProperties	False

repositories

type	object
properties
url	repository URL
	type	string
	format	uri
package_id	set if repository is a package
	type	string
name	name repository (set if package_id is missing)
	type	string
revision	intended revision (branch or tag) declared by user
	type	string
discovered_revision	discovered version tag or (MISSING) if not found
	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, critical
lastStateChange	changeId
lastConfigChange	changeId
protected	type	boolean
created	anyOf		changeId
			type	string
			type	boolean
customized	anyOf		changeId
			type	boolean

Job Record

type	object
allOf		Status
		properties
		changeId	changeId
		previousId	changeId
		startCommit	type	string
		startTime	Timestamp
		endTime	Timestamp
		workflow	type	string
		options	job options set by the user
			type	object
		summary	type	string
		changed	number of tasks that made changes to the target
			type	integer
		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
		startTime	Timestamp
		endTime	Timestamp
		implementation	implementation definition
		reason	type	string
		inputs	attributes
		changes	default	{}
			allOf		additionalProperties	namedObject
		changed	true if the task made changes to the target
			type	boolean
		dependencies	type	array
			items
				type	object
				properties
				name	type	string
				ref	type	string
				expected
				schema	schema
				required	type	boolean
				writeOnly	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

Lock

Lock Section
type	object
properties
runtime	type	object
	properties
	unfurl	type	object
		properties
		version	Generic Version Identifier
		digest	type	string
	toolVersions	asdf tools versions used
		type	object
package_rules	package rules used
	type	array
	items
		type	string
repositories	type	array
	items
		repositories
ensembles	the state of referenced external ensembles
	type	object
	allOf		namedObject
			additionalProperties	type	object
				properties
				uri	type	string
					format	uri
				changeId	anyOf		changeId
							type	null
				digest	type	string
				manifest	type	object
					properties
					file	type	string
					repository	type	string
					project	type	string

Definitions

Enums and Simple Types

readyState

The operational status of the instance
type	string
enum	unknown, ok, degraded, error, pending, absent

state

the Node 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