Getting Started

Foreword

Now that LinchPin is installed according to Installation, it is time to see how it works. This guide is essentially a quick start guide to getting up and running with LinchPin.

LinchPin is a command-line utility, a Python API, and Ansible playbooks. This document focuses on the command-line interface.

Terminology

LinchPin, while it attempts to be a simple tool for provisioning resources, still does have some complexity. To that end, this section attempts to define the minimal bits of terminology needed to understand how to use the linchpin command-line utility.

Topology

The topology is a set of rules, written in YAML, that define the way the provisioned systems should look after executing linchpin. Generally, the topology and topology_file values are interchangeable, except where the YAML is specifically indicated. A simple dummy topology is shown here.

---
topology_name: "dummy_cluster" # topology name
resource_groups:
  -
    resource_group_name: "dummy"
    resource_group_type: "dummy"
    resource_definitions:
      -
        name: "web"
        type: "dummy_node"
        count: 3

This topology describes a set of three (3) dummy systems that will be provisioned when linchpin up is executed. The names of the systems will be ‘web_#.example.net’, where # indicates the count (usually 0, 1, and 2). Once provisioned, the resources will be output and stored for reference. The output resources data can then be used to generated an inventory, or passed as part of a linchpin destroy action.

Inventory Layout

The inventory_layout or layout mean the same thing, a YAML definition for providing an Ansible static inventory file, based upon the provided topology. A YAML layout is stored in a layout_file.

---
inventory_layout:
  vars:
    hostname: __IP__
  hosts:
    example-node:
      count: 3
      host_groups:
        - example
  host_groups:
    example:
      vars:
        test: one

The above YAML allows for interpolation of the ip address, or hostname as a component of a generated inventory. A host group called example will be added to the Ansible static inventory, along with a section called example:vars containing test = one. The resulting static Ansible inventory is shown here.

[example:vars]
test = one

[example]
web-2.example.net hostname=web-2.example.net
web-1.example.net hostname=web-1.example.net
web-0.example.net hostname=web-0.example.net

[all]
web-2.example.net hostname=web-2.example.net
web-1.example.net hostname=web-1.example.net
web-0.example.net hostname=web-0.example.net

PinFile

A PinFile takes a topology and an optional layout, among other options, as a combined set of configurations as a resource for provisioning. An example Pinfile is shown.

dummy1:
  topology: dummy-cluster.yml
  layout: dummy-layout.yml

The PinFile collects the given topology and layout into one place. Many targets can be referenced in a single PinFile.

The target above is named dummy1. This target is the reference to the topology named dummy-cluster.yml and layout named dummy-layout.yml. The PinFile can also contain definitions of hooks that can be executed at certain pre-defined states.

Running linchpin

As stated above, this guide is about using the command-line utility, linchpin. First off, simply execute linchpin to see some options.

$ linchpin
Usage: linchpin [OPTIONS] COMMAND [ARGS]...

  linchpin: hybrid cloud orchestration

Options:
  -c, --config PATH       Path to config file
  -w, --workspace PATH    Use the specified workspace if the familiar Jenkins
                          $WORKSPACE environment variable is not set
  -v, --verbose           Enable verbose output
  --version               Prints the version and exits
  --creds-path PATH       Use the specified credentials path if WORKSPACE
                          environment variable is not set
  -h, --help              Show this message and exit.

Commands:
  init     Initializes a linchpin project.
  up       Provisions nodes from the given target(s) in...
  destroy  Destroys nodes from the given target(s) in...

What can be seen immediately is a simple description, along with options and arguments that can be passed to the command. The three commands found near the bottom of this help are where the focus will be for this document.

Initialization (init)

Running linchpin init will generate the directory structure needed, along with an example PinFile, topology, and layout files. One important option here, is the –workspace. When passing this option, the system will use this as the location for the structure. The default is the current directory.

$ export WORKSPACE=/tmp/workspace
$ linchpin init
PinFile and file structure created at /tmp/workspace
$ cd /tmp/workspace/
$ tree
.
├── credentials
├── hooks
├── inventories
├── layouts
│   └── example-layout.yml
├── PinFile
├── resources
└── topologies
    └── example-topology.yml

At this point, one could execute linchpin up and provision a single libvirt virtual machine, with a network named linchpin-centos71. An inventory would be generated and placed in inventories/libvirt.inventory. This can be known by reading the topologies/example-topology.yml and gleaning out the topology_name value.

Provisioning (up)

Once a PinFile, topology, and optionally a layout are in place, provisioning can happen.

Note

For this section, the dummy tooling will be used as it is much simpler and doesn’t require anything extra to be configured. The dummy provider creates a temporary file, which represents provisioned hosts. If the temporary file does not have any data, hosts have not been provisioned, or they have been recently destroyed.

The dummy topology, layout, and PinFile are shown above in the appropriate sections. The tree would be very simple.

$ tree
.
├── inventories
├── layouts
│   └── dummy-layout.yml
├── PinFile
├── resources
└── topologies
    └── dummy-cluster.yml

Performing the command linchpin up should generate resources and inventory files based upon the topology_name value. In this case, is dummy_cluster.

$ linchpin up
target: dummy1, action: up

$ ls {resources,inventories}/dummy*
inventories/dummy_cluster.inventory  resources/dummy_cluster.output

To verify resources with the dummy cluster, check /tmp/dummy.hosts

$ cat /tmp/dummy.hosts
web-0.example.net
web-1.example.net
web-2.example.net

This is reflected in both the resources (not shown) and inventory files.

[example:vars]
test = one

[example]
web-2.example.net hostname=web-2.example.net
web-1.example.net hostname=web-1.example.net
web-0.example.net hostname=web-0.example.net

[all]
web-2.example.net hostname=web-2.example.net
web-1.example.net hostname=web-1.example.net
web-0.example.net hostname=web-0.example.net

Teardown (destroy)

As expected, LinchPin can also perform teardown of resources. A teardown action generally expects that resources have been provisioned. However, because Ansible is idempotent, linchpin destroy will only check to make sure the resources are up. Only if the resources are already up will the teardown happen.

The command linchpin destroy will either use resources and/or topology files to determine the proper teardown procedure. The dummy Ansible role does not use the resources, only the topology during teardown.

$ linchpin destroy
target: dummy1, action: destroy

$ cat /tmp/dummy.hosts
-- EMPTY FILE --

Note

The teardown functionality is slightly more limited around ephemeral resources, like networking, storage, etc. It is possible that a network resource could be used with multiple cloud instances. In this way, performing a linchpin destroy does not teardown certain resources. This is dependent on each providers implementation.

See specific implementations for each of the providers.

Multi-Target Actions

LinchPin can provision or teardown any number of resources. If a PinFile has multiple targets, and is called without a target name, all targets will be executed. Given this PinFile.

example:
  topology: example-topology.yml
  layout: example-layout.yml

example2:
  topology: example2-topology.yml
  layout: example2-layout.yml

dummy1:
  topology: dummy-cluster.yml
  layout: dummy-layout.yml

A call to linchpin up would provision and generate an Ansible static inventory for each target.

$ linchpin up
target: dummy1, action: up

target: example2, action: up

target: example, action: up

See also

Command-Line Reference
Linchpin Command-Line Interface
User Mailing List
Subscribe and participate. A great place for Q&A
irc.freenode.net
#linchpin IRC chat channel