Topologies
==========

A topology is a specification of which resources from which environments
are being requested from a linchpin run. Since each environment has different sets
of requirements, the exact values and structure of a topology file will vary based
on where resources are to be provisioned. In this document some broad discussion of
topologies will be addressed. More extensive examples pertaining to specific environments
will be given in a separate section of the documentation.

Topology
````````

Broadly speaking, a linchpin topology file is a list of resources to be provisioned from
each environment. It is possible and a very common use case to list multiple resources,
even multiple types of resources, in a single topology file. A less common use case, but
still supported, is to provision multiple resources across multiple environments.

The topology file does not designate the format of the output, nor map the particular
resources that get provisioned into output inventory groups. That is the work of the
layouts file.

Structure
`````````

A topology is a YAML file or a JSON file formatted with a single top-level object.

There are two top level keys in a topology.

The first key is named `topology_name` and is a relatively free-form string that identifies
the user-friendly name for this particular topology. For best practices, this should
resemble the file name and possibly the name of the key from the PinFile.

The second key is the `resource_groups` key. This key is an array of objects.

Resource Group
--------------

Each entry in the `resource_group` key array is itself an object hash with three
object keys.

The first key is `resource_group_name`, and is a user-friendly name for the
resources that will be provisioned from this group definition.

The second key is `res_group_type` and must be a string of a limited set. This set
must match to the particular environment. Some environments can define different types
of valid values. As an example, the value `duffy` will define a resource type to
be provisioned in a Duffy architecture, whereas the value `beaker` will contain definitions
of a set of servers to be provisioned in a Beaker environment.

The third key is `res_defs`. This key defines an array of objects. Each of these objects'
exact form will be dictated by the value of `res_group_type`. To see more information on
the structure of these values, check the example topologies section of this documentation.
