Common Workflows¶
Having a basic understanding of LinchPin is crucial to this section. Knowing the basic CLI operations leads nicely into using LinchPin in powerful ways.
Topics
Using linchpin fetch
¶
The linchpin fetch
command provides a simple way to access a resource from
a remote location. One could simply perform a git clone, or use wget to
download a workspace
. However, linchpin fetch
makes this process
simpler, and includes some tooling to make the workflow smooth.
$ linchpin fetch --help
Usage: linchpin fetch [OPTIONS] REMOTE
Fetches a specified linchpin workspace or component from a remote location
Options:
-t, --type TYPE Which component of a workspace to fetch.
(Default: workspace)
-r, --root ROOT Use this to specify the location of the
workspace within the root url. If root is not
set, the root of the given remote will be used.
--dest DEST Workspaces destination, the fetched workspace
will be relative to this location. (Overrides
-w/--workspace)
--branch REF Specify the git branch. Used only with git
protocol (eg. master).
--git Remote is a Git repository (default)
--web Remote is a web directory
--nocache Do not check the cached time, just copy the
data to the destination
-h, --help Show this message and exit.
Retrieve a Remote Workspace¶
This document will cover how to use linchpin fetch
to obtain a workspace
from a git repository. An example for fetching an http workspace can be
found here.
First, determine the destination. By default, the destination location
is the current working directory. In this guide, we’ll use /tmp/workspaces
.
$ mkdir /tmp/workspaces
$ cd /tmp/workspaces
Using the simplest possible linchpin fetch
command will fetch the
workspaces from git://github.com/herlo/lp_test_workspace.
$ linchpin fetch git://github.com/herlo/lp_test_workspace
destination workspace: /tmp/workspaces/
$ pwd
/tmp/workspaces
$ ls -l
total 4
-rw-rw-r-- 1 herlo herlo 980 Sep 5 13:53 linchpin.log
drwxrwxr-x 5 herlo herlo 140 Sep 5 13:54 multi-target
drwxrwxr-x 2 herlo herlo 80 Sep 5 13:54 openstack
drwxrwxr-x 3 herlo herlo 120 Sep 5 13:54 os-server-addl-vols
The directory structure of https://github.com/herlo/lp_test_workspace should match the local directory as shown above.
As can be easily seen, linchpin fetch
performed a git clone. Then copied
all of the directories to the current directory. linchpin fetch
assumes the
root of the repository is a workspace.
Additional Options¶
If pulling all workspaces was not the intended action, there are other useful options. First, perform a little clean up.
$ cd && rm -rf /tmp/workspaces # remove the workspaces directory
$ ls -l /tmp/workspaces
ls: cannot access '/tmp/workspaces/': No such file or directory
Note
From here on in, this guide will use the LinchPin git repository. There are several :lp_dir:`workspaces <docs/source/examples/workspaces>` with useful use cases. Feel free to peruse them as desired. This guide will use these workspaces going forward.
To clone from a repository with multiple workspaces (eg. the linchpin
repository), a root must be specified. It is also recommended to use the
--dest
flag.
$ linchpin fetch git://github.com/CentOS-PaaS-SIG/linchpin \
> --root workspaces/simple --dest /tmp/workspaces
Created destination workspace: /tmp/workspaces/simple
In this example, there are additional options. Let’s cover them in detail:
--root ROOT
This is the root of the repository. Normally, the root of the repository is used. However, if the workspaces reside elsewhere (eg. workspaces), use this option.
--dest DESTINATION
If the current working directory is not the desired location, use this option.
Performing a listing will show how these options affected the fetch.
$ ls -R /tmp/workspaces/
/tmp/workspaces/:
simple
/tmp/workspaces/simple:
PinFile README.rst
As expected, the simple
root was pulled down, and placed inside the
/tmp/workspaces
directory on the local machine.
To have all workspaces copied into /tmp/workspaces, a change is needed.
$ linchpin fetch git://github.com/CentOS-PaaS-SIG/linchpin \
> --root workspaces --dest /tmp
destination workspace: /tmp/workspaces
Note
An observant user will notice that the same destination was used.
This is because linchpin fetch
maps the ROOT to the destination
automatically. This behavior can be adjusted by removing the –dest
option and specifying –workspace instead.
Listing the files again reveals more workspaces.
$ ls /tmp/workspaces/
dummy-aws dummy-two os-server-addl-vols random simple
Take a moment and investigate each of these workspaces.
Contents of a Workspace¶
Whether a workspace watch was created, or pulled using linchpin fetch
, they
all should have some common components.
README.rst
A short description of the purpose for (or use case) the workspace
PinFile
A declarative file which indicates which resources should be provisioned, any inventory layout to be generated, hooks, and other configurations
Note
The PinFile
can be in YAML, JSON format. It can also be a script
that returns JSON to STDOUT
No other requirements are put on a workspace. However, there can be several other files or directories. See Managing Resources for more information.