How it works

Unfurl is a command line tool that works with Git to record and deploy changes to your DevOps infrastructure. It tracks configuration changes, keeping a history of exactly how you did it and what the results are, so you can easily repair or recreate what you did later.

Unfurl integrates with the deployment tools you are already using, like Ansible, Terraform and Helm, organizing their usage into Ensembles, shareable abstractions that ease migrations to new environments as well as share and reuse your work.

Key Concepts

Ensemble manifest

At the core of Unfurl is an Ensemble manifest, a YAML file that includes:

Unfurl projects

An unfurl project is directory that consists of:


Unfurl creates a “home” project (by default in ~/.unfurl_home) representing the local machine. It is used to bootstrap the local deployment environment and its configuration settings are inherited by each Unfurl project on that machine.

Unfurl repositories

unfurl can automatically commit any changes to the project to one or more git repositories. Unfurl provides flexibility on how to map this layout to git repositories, supporting both “monorepo” and “polyrepo” arrangements. An ensemble can keep instance data and specifications in separate git repositories (useful for testing or ephemeral instances) and a project can live in a dedicated repository or be part of a source repository.

Steps to build your ensemble

  1. Organize and isolate
  2. Model
  3. Implement
  4. Activate
  5. Publish and Remix

1. Organize your deployment environment


Unfurl allows you to collect your configuration information and organize them into contexts.

Contexts are used to create isolated environments that the Unfurl deployment process runs in. For example, you might create different context for different projects or different deployment environments such as “production” or “staging”.

Some of supported configuration include:

Contexts can include secrets which can be in managed in a variety of ways including support for secret managers such as Hashicorp Vault or Amazon Secret Manager or transparently encrypting them using Ansible Vault.

Bootstrap and manage your local environment

Unfurl stores these local contexts in an “.unfurl_home” Ensemble that represents its local environment. So you can use all its functionality to manage the local machine it is running on, for example, it can:

2. Model your cloud infrastructure


Specify your servers, applications, network, etc. with a declarative model that describes resources and their properties, dependencies, and relationships using the OASIS’s TOSCA (“Topology and Orchestration Specification for Cloud Applications”) standard). Leverage the TOSCA ecosystem of existing model libraries and tools.

TOSCA supports abstract type hierarchies and reusable templates for resources and relationships so your models can be truly cloud-agnostic.

Topology also can describe its surrounding cloud environment such as required external resources so the deployment process can validate and adapt to its environment.

Models can be vague with ad-hoc properties or they can be detailed and precise with strongly typed nodes and relationships, depending on need, and they can be incrementally refined over time.

Models can be dynamically generated and updated as part of the deployment process, for example from Helm charts or Terraform modules.

3. Implement your model


Once you’ve specified the model, you associate it with operations and workflows in YAML using plugins called “configurators”, which integrate configuration tools, including:

Domain-specific configurators:

The YAML configuration language has several facilities for processing an operation’s inputs and outputs, including:

4. Activate and Manage


Now you are ready to deploy your model – run “unfurl deploy” from the command line and it will execute a plan. As it is running it tracks changes resource attributes and status and when it is complete it commits that to a Git repository. mirror not just the configuration but the state and status of live running services.

If you are already have live resources Unfurl supports “discover” and “check” workflows for detecting and syncing resources and operational state.

Unfurl supports incremental deployment and has a repair mode which can greatly accelerate development and testing development.

Unfurl excels at “day two” operations such as backups, repairs and upgrades:

5. Share, Clone and Remix


You can share and clone Unfurl projects and ensembles just like you share and clone git repositories. Because Unfurl cleanly separates secrets and local settings Unfurl repositories are self-contained and location independent.

Like a git repository your Unfurl repository can be private or public, but either way, when you publish your ensemble the real power of Unfurl kicks in. Now other Unfurl projects can import and reference it, much like you import a module or package in a software program.

Once imported, other ensembles can reference the ensemble’s exported api endpoints, network resources or artifacts in their models, selecting them based on their type and other declared constraints.

Cloud agnostic and location independent

And because Ensembles maintain a persistent identity you can maintain these relationships as their internal implementations change – even if their locations change, even if they migrate to different cloud providers using a very different implementations. Or not: these references can also detect changes that violate the declared contracts between ensembles.

Cloud as code

Because Ensembles not just contain configuration but also reflects the state of live instances you can use the same development processes you for coding to also manage your IT infrastructure, for example: