Having a basic understanding of LinchPin is crucial to this section. Knowing the basic CLI operations leads nicely into using LinchPin in powerful ways.
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
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.
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
First, determine the destination. By default, the destination location
is the current working directory. In this guide, we’ll use
$ 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.
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
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
$ 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:
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.
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
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.
Whether a workspace watch was created, or pulled using
linchpin fetch, they
all should have some common components.
A short description of the purpose for (or use case) the workspace
A declarative file which indicates which resources should be provisioned, any inventory layout to be generated, hooks, and other configurations
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.