Getting Started¶
Topics
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