Managing Resources

Resources in LinchPin generally consist of Virtual Machines, Containers, Networks, Security Groups, Instances, and much more. Detailed below are examples of topologies, layouts, and PinFiles used to manage resources.

PinFiles

These PinFiles represent many combinations of complexity and providers.

PinFiles are processed top to bottom.

YAML

PinFiles written using YAML format:

The combined format is only available in v1.5.0+

JSON

New in version 1.5.0

PinFiles written using JSON format.

Jinja2

New in version 1.5.0

These PinFiles are examples of what can be done with templating using Jinja2.

Beaker Template

This template would be processed with a dictionary containing a key named arches.

$ linchpin -p PinFile.beaker.template \
    --template-data '{ "arches": [ "x86_64", "ppc64le", "s390x" ]}' up

Libvirt Template and Data

This template and data can be processed together.

$ linchpin -vp PinFile.libvirt-mi.template \
    --template-data Data.libvirt-mi.yml up

Scripts

New in version 1.5.0

Scripts that generate valid JSON output to STDOUT can be processed and used.

$ linchpin -vp ./scripts/generate_dummy.sh up

Output PinFile

New in version 1.5.0

An output file can be created on an up/destroy action. Simply pass the --output-pinfile option with a path to a writable file location.

$ linchpin --output-pinfile /tmp/Pinfile.out -vp ./scripts/generate_dummy.sh up
..snip..
$ cat /tmp/Pinfile.out
{
    "dummy": {
        "layout": {
            "inventory_layout": {
                "hosts": {
                    "example-node": {
                        "count": 3,
                        "host_groups": [
                            "example"
                        ]
                    }
                },
                "vars": {
                    "hostname": "__IP__"
                }
            }
        },
        "topology": {
            "topology_name": "dummy_cluster",
            "resource_groups": [
                {
                    "resource_group_name": "dummy",
                    "resource_definitions": [
                        {
                            "count": 3,
                            "type": "dummy_node",
                            "name": "web"
                        },
                        {
                            "count": 1,
                            "type": "dummy_node",
                            "name": "test"
                        }
                    ],
                    "resource_group_type": "dummy"
                }
            ]
        }
    }
}

Topologies

These topologies represent many combinations of complexity and providers. Topologies process resource_definitions top to bottom according to the file.

Topologies have evolved a little and have a slightly different format between versions. However, older versions still work on v1.5.0+ (until otherwise noted).

The difference is quite minor, except in two providers, beaker and openshift.

Topology Format Pre v1.5.0

---
topology_name: "dummy_cluster" # topology name
resource_groups:
  - resource_group_name: "dummy"
    resource_group_type: "dummy"
    resource_definitions:
      - name: "web"
        type: "dummy_node" <-- this is called 'type`
        count: 1

v1.5.0+ Topology Format

---
topology_name: "dummy_cluster" # topology name
resource_groups:
  - resource_group_name: "dummy"
    resource_group_type: "dummy"
    resource_definitions:
      - name: "web"
        role: "dummy_node" <-- this is called 'role`
        count: 1

The subtle difference is in the resource_definitions section. In the pre-v1.5.0 topology, the key was type, in v1.5.0+, the key is role.

Note

Pay attention to the callout in the code blocks above.

For details about the differences in beaker and openshift, see Topology Incompatibilities.

YAML

New in version 1.5.0

Topologies written using YAML format:

Older topologies, supported in v1.5.0+

JSON

New in version 1.5.0

Topologies can be written using JSON format.

Jinja2

New in version 1.5.0

Topologies can be processed as templates using Jinja2.

Jenkins-Slave Template

This topology template would be processed with a dictionary containing one key named arch.

The PinFile.jenkins.yml contains the reference to the jenkins-slave topology.

jenkins-slave:
  topology: jenkins-slave.yml
  layout: jenkins-slave.yml
$ linchpin -p PinFile.jenkins --template-data '{ "arch": "x86_64" }' up

Layouts

Inventory Layouts (or just layout) describe what an Ansible inventory might look like after provisioning. A layout is needed because information about the resources provisioned are unknown in advance.

Layouts, like topologies and PinFiles are processed top to bottom according to the file.

YAML

Layouts written using YAML format:

JSON

New in version 1.5.0

Layouts can be written using JSON format.

Jinja2

New in version 1.5.0

Topologies can be processed as templates using Jinja2.

Dummy Template

This layout template would be processed with a dictionary containing one key named node_count.

The PinFile.dummy.json contains the reference to the dummy.json layout.

{
    "dummy": {
        "topology": "dummy.json",
        "layout": "dummy.json"
    }
}
$ linchpin -p PinFile.dummy.json --template-data '{ "node_count": 2 }' up

Advanced layout examples can be found by reading ra_inventory_layouts.