Resource Placement

Regions and Folders

Regions

A region defines a physical location (i.e. a datacenter) for your resources. Every resource that is provisioned must be within a region. The region schema abstracts the venue-specific location to physical properties such as country, area, state, and city. Tuono then maps these properties to actual venue locations:

location:
  region:
    preferred:
      country: USA
      area: northwest

When we resolve this region definition for the destination venue, we attempt to find the best match for the properties provided. For this example, that would be:

Venue	Datacenter	Location
AWS	us-west-2	OR, USA
Azure	westus2	WA, USA

Ambiguity

Ambiguity means your original intentions were not expressed well enough for Tuono to provision what you want. For example, if a region definition resolves to multiple potential datacenters, we do not know which region you meant:

location:
  region:
    preferred:
      country: USA
      area: east

To avoid ambiguity the current recommended method for region selection is using region specific definitions for AWS and Azure outlined in each cloud providers regions specifications.

If you apply this blueprint to an environment targeting AWS, it is ambiguous. Did you mean the Virginia datacenter or the Ohio datacenter? To resolve this ambiguity, you can add the state of the region, or you can be very specific about the region of your resources and avoid the configuration abstraction, while maintaining portability:

location:
  region:
    preferred:
      aws: us-east-1
      azure: eastus

By specifying the venue’s region identifier, it will ensure that the resources are provisioned within the specified region without ambiguity.

Venue-specific identifiers can be very useful if the user is familiar with the venue’s regions and has specific datacenter targets. It also allows datacenters to be chosen based on something other than just geography (e.g. cost, accessibility).Each venue provides a plethora of physical datacenters to choose from.

The region schema documentation contains links to venue documentation on available regions.

Folders

All provisioned resources are placed into a folder. A folder is a unique namespace within an AWS Account or Azure Subscription that holds resources. Within a folder, for each resource type, resources must be uniquely named. You can have identically named resources for the same resource type as long as they are in different folders. The folder is specified as a required property of most schema resources.

Folders become Resource Groups in both AWS and Azure. Resources are placed into folders, which are each associated with one region. In the following example, a virtual network is created in a specific folder, which is in a specific region:

location:
  region:
    preferred:
      country: USA
      area: northwest
  folder:
    example:
      region: preferred

networking:
  network:
    test:
      folder: example        # this is optional, see below
      range: 10.0.0.0/16

Inferred Folder

Most of the resources in the schema have a folder property that is a reference to a location.folder which is required. To eliminate the repetitive step of declaring the same folder in all of the resources in a blueprint, we will infer the folder if there is only one in the blueprint. This only happens on folder references, but may be expanded to other reference types in the future.

If you declare more than one folder in a blueprint, you must explicitly declare which folder each resource belongs to.

Multiple Regions or Resource Groups

The Tuono schema allows a user to define multiple resource groups for their objects using multiple folder stanzas. This might look like this:

location:
  region:
    my_region:
      country: USA
      area: northwest
  folder:
    resource_group_a:
      region: my_region
    resource_group_b:
      region: my_region

If you declare more than one folder in a blueprint, you must explicitly declare the folder - generally an optional property of most objects - for each objects. This is because we only have a concept of the 'default' folder when there is only one folder object.

We are planning to improve this by introducing the concept of an explicit "default folder".

To leverage this, it might look like this:

networking:
  network:
    my_network:
      folder: resource_group_a
      ...
  subnet:
    my_subnet:
      folder: resource_group_a
      network: my_network
      ...
...
compute:
  image:
    my_image:
      folder: resource_group_b
      ...
  ...
  vm:
    my_vm:
      folder: resource_group_b
...

Significantly, it is also possible to reference multiple resource groups, in multiple regions using a similar syntax:

location:
  region:
    west_region:
      country: USA
      area: northwest
    east_region:
      country: USA
      area: northeast
  folder:
    resource_group_a:
      region: west_region
    resource_group_b:
      region: east_region