References

Also Known As "Refs", not to be confused with anything related to Football.

Introduction

References (or refs) define dependency relationships between resources. These dependencies allow Tuono to convert the blueprints in an environment into a dependency graph, which allows for parallel provisioning of resources. We will use an example containing a region and a folder to explore how references work. Regions and folders are more thoroughly explored in the next section.

If we define a region and a folder, we use a ref to declare a dependency:

location:
  region:
    preferred:
      country: USA
      area: northwest
  folder:
    example:
      region: preferred        # this is a reference

The region property of a folder is a reference type property. The folder refers to the region that it is in through this reference. The resource specifying the reference is considered the referrer and the resource that it refers to is considered to be the referred.

Referred Type

Each reference can have one or more allowed resources that it refers to. In the example above, we have a region and a folder. The schema documentation for the region property states that the only referred type allowed for this reference is a location.region. When there is only one referred type it is acceptable to specify the reference by blueprint name, as shown in the example.

If a reference accepts multiple types, it is necessary to use the fully-qualified blueprint name. You can use the fully-qualified blueprint name even if only one target type is supported. In the example above, region: preferred could be replaced with region: location.region.preferred as the blueprint engine treats them identically.

Plurality

References can be singular or plural. A singular reference establishes a one-to-one relationship between two resources. A plural reference establishes a one-to-many relationship. The plurality of a reference is coded into the schema and indicated in the schema documentation. A folder establishes a singular reference to a region, because a folder can only exist in a single region.

When a reference is singular, as is the case in the example above (region of folder), you can specify the referred name as a single string property, as is shown in the example.

When a reference is plural, you can choose to express the reference as a list or a string, however the string variation can only be used if there is one referred resource.

Forwarding

It is not necessary to define a resource before it is referenced. For example, you can define a compute.vm at the top of your blueprint which is connected to a networking.subnet defined after, All references are resolved after the entire blueprint set is loaded.