Tuono User Guide


Tuono provides configuration abstraction for cloud providers, making your infrastructure provisioning truly portable. Our portable cloud infrastructure definition language lets you describe what you need using well-known concepts such as networks, subnets, disks, virtual machines, and load balancers. You describe the infrastructure that you need, and Tuono takes care of how those resources are created and managed.

Supported Cloud Providers

​ ​

Details on features supported for each resource type can be found in the Schema Reference.


Understanding these concepts will help you acclimate to the Tuono solution.


We typed in "cloud_provider" so many times, it actually started to hurt! We needed shorter term for cloud provider that not only could describe one, but also any other infrastructure provider - on-premises or cloud. We call it a venue, and you will see venue used throughout the Tuono product and documentation in place of "cloud provider".


A blueprint is a reusable description of infrastructure. You create one or more blueprints containing a description of what resources need to exist. Blueprints can be customized for different situations using variables, making them reusable not only across different use cases, but even across different venues. Examples of blueprints:

  • A blueprint for a corporate network.

  • A blueprint for a mongo database cluster.

  • A blueprint for a custom web application.

  • Our own tutorial has a blueprint.


An environment defines a unique namespace in which you can deploy venue resources described in one or more blueprints. With an environment, you combine:

  • The venue and credentials (account or subscription) to use.

  • The blueprints to deploy.

  • The variables that customize the blueprints, if any.

Once all the information is provided, you can apply the environment to your venue. You can upgrade your blueprints and continue to apply them to modify your environment. When you no longer need the environment, you can destroy it.


When you apply (or destroy) an environment to (in) a venue, a job tracks the progress and results. The job will influence the state of the environment and provide feedback as to what would change (for a preview) or what did change (for an apply or destroy).


Your credentials are sacred, which is why we use a dedicated Vault instance for each subscriber. The vault instance holds provisioning secrets necessary to deploy blueprints safely and securely. Using separate vault instances is part of our overall defensive security strategy, which includes:

  • Protecting secrets in transit.

  • Protecting secrets while stored.

  • Ensuring secrets can never be logged.

  • Ensuring no Tuono employee can access secret content that is not theirs.

  • Using enclave strategies to protect secrets during use, and wipe them after use.


Our web-based portal is your primary interface to the Tuono solution. It also exposes our REST API that can be used to integrate Tuono into a larger workflow.

Theory of Operation

We designed and implemented our provisioning engine from the ground up to solve problems associated with cloud provisioning. We hope you enjoy reading about the "ity"s as much as we have spent time and effort solving them!


One of the most deceptive marketing tactics for infrastructure provisioning systems is to claim that it is a multi-cloud solution. The truth is almost always quite different. Cloud Provisioning systems before Tuono might be considered "multi-cloud capable". The cloud-specific rules and API calls are exposed through those systems without a filter, and the onus falls upon the consumer to spend the time to learn and use them properly. The end result is that the consumer ends up locked into one cloud provider because it becomes too expensive to rewrite scripts and learn new rules, even though they used a system that claimed to be "multi-cloud".

We have developed the first cloud provider provisioning abstraction layer. You can describe the resources you need in a cloud-agnostic, easy-to-use text language and then provision those resources to any supported cloud provider, all without making any changes to your infrastructure definition.

For example, this blueprint can be used to create a virtual network and subnet in either AWS or Azure:

country: USA
area: northwest
region: preferred
folder: overview-example
network: overview-network

Identity (The Source of Truth)

We firmly believe that the only source of truth can be the venue itself. At any point in time if we need to know if something exists or is configured in a particular way, we ask the venue about it. We never make provisioning decisions based on cached or stale state.


Often times, provisioning requires secrets that are incredibly sensitive. Keeping that information safe is of paramount importance to our customers and to us. We allocate a dedicated Vault to each and every one of our paid subscribers. This is a fully independent vault instance running in our infrastructure. We handle your secrets in a way that ensures the window of opportunity where we have access to the sensitive content is extremely narrow.

Integrity (Fail Early)

We avoid late failures that leave infrastructure in an indeterminate state. Our venue simulation layer makes internal changes to venue models as if they had been executed. We code the venue provisioning rules into our venue object layer and then test it in many ways to guarantee it is behaving just like the venue itself. Here are some examples of cases where we will fail early and will not even start provisioning:

  • A subnet is removed from a blueprint but it is still being used by other resources.

  • A subnet has a range that falls outside the network range.

  • A virtual machine has a name that is longer than the venue supports.

In these cases (and many more not shown here), where the venue would eventually reject the provisioning request, we detect it early so that we do not even start making changes.

Reliability (Test Everything)

We know from experience that untested code is broken code. Testing is built into our DNA. We perform isolation unit testing, modular integration testing, component level interface testing, and holistic system testing. How do you know when you are done testing? The truth is, you are never done testing software. By measuring branch coverage, you can gauge how much you purposefully (or accidentally) test, and where you need to focus on adding more tests to make your product more reliable:



had branch coverage of...

AWS Adapter

July 9, 2020


Azure Adapter

July 9, 2020


Provisioning Engine

July 9, 2020


Vault Management

July 9, 2020


Reproducability (Idempotence)

​Idempotence is a fancy word that basically says, β€œperforming the same operation multiple times produces the same result.” In our case, this means applying the same blueprint to the same venue more than once will produce the same result. If something does not need to change then we will not change it.

Idempotence is really important, because unnecessary changes lead to excessive cost or unintended service interruptions. We took one part of Idempotence and cooked it together with one part of "Test Everything" and the end result is a testing pattern that we apply liberally at all layers of our solution.

For every case of a create, update, or delete of an object, we test:

  • Preview (simulate) the action, and verify that changes would occur.

  • Preview (simulate) the action again, and verify no changes would occur.

  • Perform that action live, and verify that changes occur.

  • Perform that action live again, and verify that no changes occur.

  • Preview (simulate) the action again, and verify no changes would occur.

The last entry may appear to be a "cut & paste error", but it is crucial to ensuring that our preview (simulation) layer is accurate with respect to the source of truth.

Fun With Provisioning

You may find silly comments scattered throughout the documentation. This is normal. Don't Panic.

What is a Tuono?

In the Italian language, Tuono means thunder. Can you hear the disruption? Tuono is also a high performance motorcycle, something a couple of our founders apparently dream about at night (and maybe during the day too!)