README.md in testlab-1.1.0 vs README.md in testlab-1.2.0
- old
+ new
@@ -20,21 +20,41 @@
TestLab can be run via the command-line or can be interfaced with directly via Ruby code.
# Using TestLab Interactively
-The TestLab command-line program `tl` follows in the style of git:
-
- $ tl help
+ $ tl
NAME
tl - TestLab - A toolkit for building virtual computer labs
+ TestLab is based around the abstraction of three main components: nodes, networks and containers. Nodes represent a system
+ (bare-metal or virtualized) that hosts containers. Networks repesent a Linux bridge on a node. Containers simply represent a
+ Linux Container (LXC) running on its parent node which is typically connected to a network on the node.
+
+ In addition to the core component abstractions, TestLab shares a series of core tasks that are universal across all of the
+ components. These are create and destroy, up and down, provision and deprovision. Several other core tasks, such as build,
+ demolish, recycle and bounce encapsulate the previously mentioned tasks and simply act as convenience tasks.
+
+ You can execute almost all of the tasks against the entire lab, or individual lab components.
+
+ When building a lab from scratch, you will typically run 'tl build'. To breakdown your lab, destroying all the components, you
+ will typically run 'tl demolish'. If you want to re-build the lab you can run 'tl recycle' which will run the demolish task
+ followed by the build task against all the lab components. If you want to power-cycle the entire lab you can run 'tl bounce'
+ which will run the down task followed by the up task against all the lab components. Again these tasks can be run against the
+ lab as a whole or individual components.
+
+ You can view the status of the entire lab using 'tl status', or view the status of individual components using 'tl node status',
+ 'tl network status' or 'tl container status'.
+
+ You can easily get help for any of the component tasks using the syntax 'tl help <component>'. This can be extended to the
+ following syntax 'tl help <task>' or 'tl help <component> <task>' for more in-depth help.
+
SYNOPSIS
tl [global options] command [command options] [arguments...]
VERSION
- 0.9.1
+ 1.1.0
GLOBAL OPTIONS
-l, --labfile=path/to/file - Path to Labfile: ${REPO}/Labfile (default: none)
-r, --repo=path/to/directory - Path to Repository directory: ${PWD} (default: /home/zpatten/code/chef-repo)
-c, --config=path/to/directory - Path to Configuration directory: ${REPO}/.testlab-$(hostname -s) (default: none)
@@ -46,41 +66,84 @@
COMMANDS
help - Shows a list of commands or help for one command
container - Manage lab containers
network - Manage lab networks
node - Manage lab nodes
+ build - Build the lab (create->up->provision)
+ demolish - Demolish the lab (deprovision->down->destroy)
+ bounce - Bounce the lab (down->up)
+ recycle - Recycle the lab (demolish->build)
create - Create the lab components
destroy - Destroy the lab components
up - On-line the lab components
down - Off-line the lab components
provision - Provision the lab components
deprovision - De-provision the lab components
- build - Build the lab
- demolish - Demolish the lab
status - Display the lab status
-You stand up your lab with the following command:
-
- tl build
-
-You can down the entire lab (this would only down the containers and networks on the Local provider for example):
-
- tl down
-
-You can also demolish it (only works for VM backed providers; this would be a NO-OP on the Local provider for example):
-
- tl demolish
-
## Getting Help
TestLab uses the GLI RubyGem, which gives us a command line pattern similar to that of Git. Therefore help is easy to get:
tl help
tl help node
tl help container
tl help network
+## Container Help
+
+Here is a sample of the help output for the container tasks:
+
+ $ tl help container
+ NAME
+ container - Manage lab containers
+
+ SYNOPSIS
+ tl [global options] container [command options] bounce
+ tl [global options] container [command options] build
+ tl [global options] container [command options] console
+ tl [global options] container [command options] [-t container|--to container] copy
+ tl [global options] container [command options] create
+ tl [global options] container [command options] demolish
+ tl [global options] container [command options] deprovision
+ tl [global options] container [command options] destroy
+ tl [global options] container [command options] down
+ tl [global options] container [command options] ephemeral
+ tl [global options] container [command options] [--output filename] [-c level|--compression level] export
+ tl [global options] container [command options] [--input filename] import
+ tl [global options] container [command options] persistent
+ tl [global options] container [command options] provision
+ tl [global options] container [command options] recycle
+ tl [global options] container [command options] [-i filename|--identity filename] [-u username|--user username] ssh
+ tl [global options] container [command options] ssh-config
+ tl [global options] container [command options] status
+ tl [global options] container [command options] up
+
+ COMMAND OPTIONS
+ -n, --name=container[,container,...] - Optional container ID or comma separated list of container IDs (default: none)
+
+ COMMANDS
+ build - Build containers (create->up->provision)
+ demolish - Demolish containers (deprovision->down->destroy)
+ recycle - Recycle containers (demolish->build)
+ bounce - Bounce containers (down->up)
+ create - Initialize containers
+ destroy - Terminate containers
+ up - On-line containers
+ down - Off-line containers
+ provision - Provision containers
+ deprovision - De-provision containers
+ status - Display containers status
+ ssh - Container SSH console
+ ssh-config - Container SSH configuration
+ console - Container console
+ ephemeral - Enable ephemeral mode for containers
+ persistent - Enable persistent mode for containers
+ copy - Copy containers
+ export - Export containers
+ import - Import containers
+
## Interacting with Containers
Almost all commands dealing will containers will take this argument:
COMMAND OPTIONS
@@ -107,89 +170,75 @@
COMMAND OPTIONS
-u, --user=username - Specify an SSH Username to use (default: none)
-i, --identity=key - Specify an SSH Identity Key to use (default: none)
-You can individually online, offline, create or destroy containers:
+You can individually create or destroy, online or offline and provision or deprovision containers:
- tl container down -n server-www-1
+ tl container create -n server-www-1
+ tl container destroy -n server-www-1
+
tl container up -n server-www-1
+ tl container down -n server-www-1
+
tl container provision -n server-www-1
tl container deprovision -n server-www-1
-You can recycle a container, effectively destroying then creating it again, provisioning it back to a "pristine" condition.
+You can recycle a container, destroying then creating it again, provisioning it back to a "pristine" condition based on the `Labfile`:
tl container recycle -n server-www-1
+You can bounce a container, offlining then onlining it again:
+
+ tl container bounce -n server-www-1
+
## Ephemeral Container Cloning
As it stands attempting to iterate infrastructure with Vagrant is a slow and painful process. Enter LXC and ephemeral cloning. The idea here is that you have a container that is provisioned to a "pristine" state according to the `Labfile`. You then clone this container and run actions against the container. After running your actions against the container you want to maybe tweak your Chef cookbook, for example, and re-run it against the container. Running an ever changing cookbook in development against the same system over and over again causes drift and problems. With the cloning you can instantly reinstate the container as it was when you first cloned it.
-Here we are cloning the container for the first time. It takes a bit longer than normal because TestLab is actually shutting down the container so it can be retained as the "pristine" copy of it, and starting up a ephemeral container in its place. Subsequent calls to clone are very fast.
+In order to use the ephemeral cloning in LXC, we first need to put our container or containers into an ephemeral mode. This allows TestLab to do certain operations on the backend to prepare the container for ephemeral cloning. Then when you are finished, you can easily return the container to a persistent mode.
- $ tl container clone -n server-www-1
- [TL] TestLab v0.6.1 Loaded
- [TL] container server-www-1 clone # Completed in 13.0116 seconds!
- $ tl container clone -n server-www-1
- [TL] TestLab v0.6.1 Loaded
- [TL] container server-www-1 clone # Completed in 0.9169 seconds!
- $ tl container clone -n server-www-1
- [TL] TestLab v0.6.1 Loaded
- [TL] container server-www-1 clone # Completed in 1.0794 seconds!
- $ tl container clone -n server-www-1
- [TL] TestLab v0.6.1 Loaded
- [TL] container server-www-1 clone # Completed in 1.0281 seconds!
+For example, to put the container into the ephemeral mode:
-The idea in the above example is that you run the initial clone command to put your container into an ephemeral clone state. You would then modify the container in some fashion, test, etc. When you where done with that iteration you would run the clone command again, losing all the changes you did to the container, replacing it with a new clean cloned copy of your original container. RRP (Rinse, Repeat, Profit)
+ $ tl container ephemeral -n chef-client
+ [TL] TestLab v1.1.0 Loaded
+ [TL] container chef-client ephemeral # Completed in 17.3453 seconds!
+ [TL] TestLab v1.1.0 Finished (17.8546 seconds)
-We can also see the containers status reflects that it is a clone currently:
+Now with our container in the ephemeral mode, we can run all of the normal container tasks against it with one simple caveat. When you offline the container and bring it back online, it will be reverted to the original state it was in before you put it into the ephemeral mode. The short of all this is, you can do what you will to the container, but the moment you bounce it (offline then online it) it reverts. This, as you can imagine, is extremely useful for developing applications and infrastructure as code.
- $ tl container status -n server-www-1
- [TL] TestLab v0.6.1 Loaded
- +----------------------------------------------+
- | NODE_ID: vagrant |
- | ID: server-www-1 |
- | CLONE: true |
- | FQDN: server-www-1.default.zone |
- | STATE: running |
- | DISTRO: ubuntu |
- | RELEASE: precise |
- | INTERFACES: labnet:eth0:10.10.0.21/16 |
- | PROVISIONERS: Resolv/AptCacherNG/Apt/Shell |
- +----------------------------------------------+
+You can quickly revert that chef node back to it's previous state in the event the cookbook you are developing has wrecked the node. For web developers, imagine having a mysql server running in an ephemeral container; you can quickly roll back all database operations just by bouncing the container.
-We can easily revert it back to a full container if we want to make "permanent" changes to it:
+This is effectively transactions for infrastructure.
- $ tl container up -n server-www-1
+To put the container back into the default, persistent mode:
-We can even recycle it while it is in a cloned state:
+ $ tl container persistent -n chef-client
+ [TL] TestLab v1.1.0 Loaded
+ [TL] container chef-client persistent # Completed in 17.3692 seconds!
+ [TL] TestLab v1.1.0 Finished (17.8692 seconds)
- $ tl container recycle -n server-www-1
-We can run provision against a clone as well (note: running `build`, calls `up`, which would revert us back to a non-cloned container and we would not want this to happen):
-
- $ tl container provision -n server-www-1
-
## Network Routes
TestLab will add network routes for any networks defined in the `Labfile` witch have the `TestLab::Provisioner::Route` provisioner class specified for them. This will allow you to directly interact with containers over the network. Here is an example of the routes added with the multi-network `Labfile`.
- $ tl network route show -n labnet
- [TL] TestLab v0.6.1 Loaded
+ $ tl network route show
+ [TL] TestLab v1.1.0 Loaded
TestLab routes:
- 10.10.0.0 192.168.33.239 255.255.0.0 UG 0 0 0 vboxnet0
- 10.11.0.0 192.168.33.239 255.255.0.0 UG 0 0 0 vboxnet0
+ 172.16.0.0 192.168.33.2 255.255.255.0 UG 0 0 0 vboxnet0
+ [TL] TestLab v1.1.0 Finished (0.5063 seconds)
These routes can be manually manipulated as well (regardless of if you have specified the `TestLab::Provisioner::Route` provisioner class for the networks via the `Labfile`):
$ tl help network route
NAME
route - Manage routes
SYNOPSIS
- tl [global options] network route [command options] add
- tl [global options] network route [command options] del
- tl [global options] network route [command options] show
+ tl [global options] network route add
+ tl [global options] network route del
+ tl [global options] network route show
COMMANDS
add - Add routes to lab networks
del - Delete routes to lab networks
show - Show routes to lab networks