testlab 1.20.2 → 1.20.3

Sign up to get free protection for your applications and to get access to all the features.
Files changed (4) hide show
  1. checksums.yaml +8 -8
  2. data/README.md +165 -136
  3. data/lib/testlab/version.rb +1 -1
  4. metadata +2 -2
checksums.yaml CHANGED
@@ -1,15 +1,15 @@
1
1
  ---
2
2
  !binary "U0hBMQ==":
3
3
  metadata.gz: !binary |-
4
- YTQ4NWEwNzRiMjkwMDY1NmI1ZWMxMzkzNzQ5ZDEzYzY3NjNhYWEwZg==
4
+ YjYxZGM4YTFiOGQ0NjIzZTRjZDQ4ZDEzZDg4OWYyOGJkMTA1MWZhMQ==
5
5
  data.tar.gz: !binary |-
6
- ZDdhZWNmZmQwNDk0MjdkNmYxYTE5Y2RjZDVkY2JiOWZjMWVlYjY3Ng==
6
+ ODgxMTk0ZTZjYmVlMTQxYmZmMjAyYjYwNjM2NDQwNGU0YjJiMGFhYQ==
7
7
  SHA512:
8
8
  metadata.gz: !binary |-
9
- OWYwZTJiYjE5MDdlNTc1NTI0ZjZjMjVkOTdmODViMzUyYWE5NzVhOWMwYWI3
10
- MjRmMmVkNDhmYzRkNTE2M2U1NGQyZWM1NmI2NDFlMDc4ZGVhNWE1ODE1ZDkx
11
- MWE0ZTk2Yjk0ZGU1YzUxMWMzODQ2YjQ1MzgzZDYwMjQ3ZjIzNzg=
9
+ NDBkNmVjNjc3MjI4OTU0MzY1MmMyYTAzMmY0NzU4YzA0YmI3NjBmMDJkYWZl
10
+ YmM3MDg3NmZmYWZkNDc2M2JmNTZiOTIxMmZhMDFjNmYyZDlhZmUxMTg0N2M5
11
+ MGJjMDgyMTI3NmY3ZTk0YjA4MTY0MGFiZWQyMGUyNDM2ZTE1Nzk=
12
12
  data.tar.gz: !binary |-
13
- MjQyN2JiYmE5MWIyNGE5OGIzZjhmYTA5ZTJmYjg1M2ZhODZlZGU3MjFhMmM4
14
- YTJjMjY5NmRkMWFkMDkwZmYyYzllOWI4NjY4MzVkNDNjNDA4OGU2MGZkMTEy
15
- ZDhkYmU4YmFjMTFhZjUxZmM0NjE4N2FjYzk3OTMyOWEzZmM4MjY=
13
+ ZDMwYzFjNzUxMmE0MWI1YTRjMGJiZjM0NGU5NzFlMDdmMjQwYzIzMjIwOWUy
14
+ YWJmNTUwMzYyOTczMTZhYWUyNjgxZjZhZGJhZjNlYjY3MTBkNzA3ZDIzMTc3
15
+ ZGVhZTE5NGEzZjQ3NWY0NTE1OTA3OTdjZjI5MGM0N2Q3NzBjNmE=
data/README.md CHANGED
@@ -22,182 +22,184 @@ TestLab can also import and export containers, making it easy to share them. Te
22
22
 
23
23
  TestLab can be run via the command-line or can be interfaced with directly via Ruby code.
24
24
 
25
- # What is a Labfile?
25
+ # Troubleshooting
26
26
 
27
- A `Labfile` defines what your lab will look like using the TestLab DSL.
27
+ To get debug level output run TestLab with a `-v` flag like this:
28
28
 
29
- # Using TestLab Interactively
29
+ tl -v container build -n chef-client
30
30
 
31
- $ tl help
32
- NAME
33
- tl - TestLab - A toolkit for building virtual computer labs
31
+ or you can control this by setting the environment variable `VERBOSE` to `1`:
34
32
 
35
- TestLab is based around the abstraction of three main components: nodes, networks and containers. Nodes represent a system
36
- (bare-metal or virtualized) that hosts containers. Networks represent a Linux bridge on a node. Containers simply represent a Linux
37
- Container (LXC) running on its parent node which is typically connected to a network on the node.
33
+ VERBOSE=1 tl container build -n chef-client
38
34
 
39
- In addition to the core component abstractions, TestLab shares a series of core tasks that are universal across all of the
40
- components. These are create and destroy, up and down, provision and deprovision. Several other core tasks, such as build,
41
- demolish, recycle and bounce encapsulate the previously mentioned tasks and simply act as convenience tasks.
35
+ Alternately you can silence the output with the `-q` flag or by setting the environment variable `QUIET` to `1`.
42
36
 
43
- You can execute almost all of the tasks against the entire lab, or individual lab components.
37
+ # Reporting Issues and Bugs
44
38
 
45
- When building a lab from scratch, you will typically run 'tl build'. To breakdown your lab, destroying all the components, you will
46
- 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
47
- 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
48
- 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
49
- individual components.
39
+ If you are having issues, please generate a bug report and reference in an issue on GitHub.
50
40
 
51
- You can view the status of the entire lab using 'tl status', or view the status of individual components using 'tl node status',
52
- 'tl network status' or 'tl container status'.
41
+ To generate a bug report run the following command:
53
42
 
54
- You can easily get help for any of the component tasks using the syntax 'tl help <component>'. This can be extended to the
55
- following syntax 'tl help <task>' or 'tl help <component> <task>' for more in-depth help.
43
+ $ tl -q bugreport
44
+ Your bug report is located at "/tmp/testlab-bug-report.1391307431".
56
45
 
57
- SYNOPSIS
58
- tl [global options] command [command options] [arguments...]
46
+ # Getting Help and General Usage
59
47
 
60
- VERSION
61
- 1.9.2
48
+ You can get help a few ways:
62
49
 
63
- GLOBAL OPTIONS
64
- -l, --labfile=path/to/file - Path to Labfile: ${REPO}/Labfile (default: none)
65
- -r, --repo=path/to/directory - Path to Repository directory: ${PWD} (default: /home/zpatten/Dropbox/code/lookout/chef-repo)
66
- -c, --config=path/to/directory - Path to Configuration directory: ${REPO}/.testlab-$(hostname -s) (default: none)
67
- --version - Display the program version
68
- -v, --[no-]verbose - Show verbose output
69
- -q, --[no-]quiet - Quiet mode
70
- --help - Show this message
50
+ * Use the help command to get details on sets of commands or specific commands.
51
+ * On Freenode IRC, in #jovelabs
71
52
 
72
- COMMANDS
73
- help - Shows a list of commands or help for one command
74
- container - Manage lab containers
75
- network - Manage lab networks
76
- node - Manage lab nodes
77
- build - Build the lab (create->up->provision)
78
- demolish - Demolish the lab (deprovision->down->destroy)
79
- bounce - Bounce the lab (down->up)
80
- recycle - Recycle the lab (demolish->build)
81
- create - Create the lab components
82
- destroy - Destroy the lab components
83
- up - On-line the lab components
84
- down - Off-line the lab components
85
- provision - Provision the lab components
86
- deprovision - De-provision the lab components
87
- status - Display the lab status
88
-
89
- ## Getting Help
90
-
91
- TestLab uses the GLI RubyGem, which gives us a command line pattern similar to that of Git. Therefore help is easy to get:
53
+ TestLab uses the GLI RubyGem, which gives us a command line pattern similar to that of Git. Help for commands is not far away, for example:
92
54
 
93
55
  tl help
94
- tl help node
95
- tl help container
96
- tl help network
56
+ tl help node recycle
57
+ tl help network build
58
+ tl help container import
59
+ tl help container demolish
97
60
 
98
- ## Container Help
61
+ You can also shorten commands; for example `tl container recycle` can also be written as `tl con rec`.
99
62
 
100
- Here is a sample of the help output for the container tasks:
63
+ When supplying container names you actually have three options. When you do not supply a container name, it is inferred that you want to run the action against all containers. Alternately you can supply a single container name or a comma delimited list of container names. For example:
101
64
 
102
- $ tl help container
103
- NAME
104
- container - Manage lab containers
65
+ tl container build # build all containers
66
+ tl container build -n chef-client # only build the chef-client container
67
+ tl container build -n chef-server,chef-client # build the chef-server and chef-client container (NOTE: list order dictates execution order)
105
68
 
106
- SYNOPSIS
107
- tl [global options] container [command options] bounce
108
- tl [global options] container [command options] build
109
- tl [global options] container [command options] console
110
- tl [global options] container [command options] [-t container|--to container] copy
111
- tl [global options] container [command options] create
112
- tl [global options] container [command options] demolish
113
- tl [global options] container [command options] deprovision
114
- tl [global options] container [command options] destroy
115
- tl [global options] container [command options] down
116
- tl [global options] container [command options] ephemeral
117
- tl [global options] container [command options] [--output filename] [-c level|--compression level] export
118
- tl [global options] container [command options] [--input filename] import
119
- tl [global options] container [command options] persistent
120
- tl [global options] container [command options] provision
121
- tl [global options] container [command options] recycle
122
- tl [global options] container [command options] [-i filename|--identity filename] [-u username|--user username] ssh
123
- tl [global options] container [command options] ssh-config
124
- tl [global options] container [command options] status
125
- tl [global options] container [command options] up
126
-
127
- COMMAND OPTIONS
128
- -n, --name=container[,container,...] - Optional container ID or comma separated list of container IDs (default: none)
69
+ # Installation
129
70
 
130
- COMMANDS
131
- build - Build containers (create->up->provision)
132
- demolish - Demolish containers (deprovision->down->destroy)
133
- recycle - Recycle containers (demolish->build)
134
- bounce - Bounce containers (down->up)
135
- create - Initialize containers
136
- destroy - Terminate containers
137
- up - On-line containers
138
- down - Off-line containers
139
- provision - Provision containers
140
- deprovision - De-provision containers
141
- status - Display containers status
142
- ssh - Container SSH console
143
- ssh-config - Container SSH configuration
144
- console - Container console
145
- ephemeral - Enable ephemeral mode for containers
146
- persistent - Enable persistent mode for containers
147
- copy - Copy containers
148
- export - Export containers
149
- import - Import containers
71
+ * Install the latest version of VirtualBox: https://www.virtualbox.org/wiki/Downloads
72
+ * Install the latest version of Vagrant: http://www.vagrantup.com/downloads.html
73
+ * Install the latest version of RVM: https://rvm.io/rvm/install
150
74
 
151
- ## Interacting with Containers
75
+ # Updating
152
76
 
153
- Almost all commands dealing will containers will take this argument:
77
+ * Install the latest version of VirtualBox: https://www.virtualbox.org/wiki/Downloads
78
+ * Install the latest version of Vagrant: http://www.vagrantup.com/downloads.html
154
79
 
155
- COMMAND OPTIONS
156
- -n, --name=container[,container,...] - Optional container ID or comma separated list of container IDs (default: none)
80
+ # Lab
157
81
 
158
- You can interact with containers via SSH:
82
+ ## Labfile
159
83
 
160
- tl container ssh -n <name>
84
+ The `Labfile` defines your virtual computer lab. It defines where you want to run your computer lab (i.e. VirtualBox/OpenStack/Bare Metal), what the network topology of that computer lab is and what servers are connect to those networks.
161
85
 
162
- For example:
86
+ You can override the default `Labfile` by setting the path to your alternate `Labfile` via the environment variable `LABFILE` or via a command line argument (see `tl help` for more details) directly to TestLab.
163
87
 
164
- tl container ssh -n server-www-1
88
+ ## Building your Lab
165
89
 
166
- Would connect to the container defined as 'server-www-1' in our Labfile.
90
+ You should build your TestLab node (i.e. VirtualBox VM) and TestLab networks first. This is the foundation which the containers run on. You should attempt to keep your TestLab node intact and only cycle your containers.
167
91
 
168
- You can pass an optional username and/or identity to use. By default TestLab will attempt to SSH as the user defined in the `Labfile` for that container, otherwise the default user for the containers distro is used.
92
+ **The follow commands assume you have functioning VirtualBox, Vagrant and RVM installations.**
169
93
 
170
- $ tl help container ssh
171
- NAME
172
- ssh - Open an SSH console to a container
94
+ tl build
173
95
 
174
- SYNOPSIS
175
- tl [global options] container ssh [command options]
96
+ ## Demolishing your Lab
97
+
98
+ You should demolish your TestLab node gracefully if possible. This can be easily accomplished.
99
+
100
+ **The follow commands assume you have functioning VirtualBox, Vagrant and RVM installations.**
101
+
102
+ tl demolish
103
+
104
+ ## Importing Labs
105
+
106
+ Importing entire labs with an embedded `Labfile` is coming soon.
107
+
108
+
109
+ ## Containers
110
+
111
+ ### Building Containers
112
+
113
+ You should import containers because it saves a lot of time. Building containers from scratch is a time consuming process. Using shipping container images and ultimately lab images greatly accelerates the speed at which you can move.
114
+
115
+ **The follow commands assume you have a functioning TestLab node.**
116
+
117
+ tl container build --force # Force all defined containers to build even if some can be imported
118
+ tl container build # Attempts to import all defined containers, building those which can not be imported
119
+ tl container build -n chef-client --force # Force the 'chef-client' container to build from scratch even if it can be imported
120
+
121
+ ### Importing Containers
122
+
123
+ You should import containers because it saves a lot of time. Building containers from scratch is a time consuming process. Using shipping container images and ultimately lab images greatly accelerates the speed at which you can move.
124
+
125
+ **The follow commands assume you have a functioning TestLab node.**
126
+
127
+ tl container import # Attempts to import all defined containers
128
+ tl container import -n chef-client # Attempts to only import the 'chef-client' container
129
+ tl container import -n chef-server,chef-client # Attempts to only import the 'chef-server' and 'chef-client' container
130
+
131
+ ### Demolishing Containers
176
132
 
177
- COMMAND OPTIONS
178
- -u, --user=username - Specify an SSH Username to use (default: none)
179
- -i, --identity=key - Specify an SSH Identity Key to use (default: none)
133
+ You can easily remove all the containers your have defined in your `Labfile` as well as single containers. You should generally demolish your containers instead of destroying them because the demolish action involves decommissioning.
180
134
 
181
- You can individually create or destroy, online or offline and provision or deprovision containers:
135
+ **The follow commands assume you have a functioning TestLab node with running containers.**
182
136
 
183
- tl container create -n server-www-1
184
- tl container destroy -n server-www-1
137
+ tl container demolish # Demolish all defined containers
138
+ tl container demolish -n chef-client # Only demolish the 'chef-client' container
139
+ tl container demolish -n chef-client,chef-server # Only demolish the 'chef-client' and 'chef-server' containers
185
140
 
186
- tl container up -n server-www-1
187
- tl container down -n server-www-1
141
+ ### Connecting to Containers
188
142
 
189
- tl container provision -n server-www-1
190
- tl container deprovision -n server-www-1
143
+ **The follow commands assume you have a functioning TestLab node with running containers.**
191
144
 
192
- You can recycle a container, destroying then creating it again, provisioning it back to a "pristine" condition based on the `Labfile`:
145
+ #### Console
193
146
 
194
- tl container recycle -n server-www-1
147
+ You can easily open an LXC console to a container. This would be similar to what you get when using IPMI to get a console.
195
148
 
196
- You can bounce a container, offlining then onlining it again:
149
+ tl container console -n chef-client
197
150
 
198
- tl container bounce -n server-www-1
151
+ #### SSH
199
152
 
200
- ## Ephemeral Container Cloning
153
+ You can easily open an SSH console to a container. Simply use the SSH command and supply the name of the container you wish to connect to, in this example we are SSH'ing to the chef-client container.
154
+
155
+ tl container ssh -n chef-client
156
+
157
+ #### TCP/UDP/ICMP
158
+
159
+ You can easily use any type of IP based network communication to talk to your containers. Your container names will resolve for all containers and for your local machine. For example if you had a web server running on a container called www-app you could direct your web browser at 'http://www-app' to connect to it.
160
+
161
+ If you have a container named chef-client and you want to ping it, simply run ping against the host; for example:
162
+
163
+ $ ping -c 5 chef-client
164
+ PING chef-client (100.64.13.253) 56(84) bytes of data.
165
+ 64 bytes from chef-client (100.64.13.253): icmp_req=1 ttl=63 time=0.463 ms
166
+ 64 bytes from chef-client (100.64.13.253): icmp_req=2 ttl=63 time=0.472 ms
167
+ 64 bytes from chef-client (100.64.13.253): icmp_req=3 ttl=63 time=0.483 ms
168
+ 64 bytes from chef-client (100.64.13.253): icmp_req=4 ttl=63 time=0.493 ms
169
+ 64 bytes from chef-client (100.64.13.253): icmp_req=5 ttl=63 time=0.492 ms
170
+ --- chef-client ping statistics ---
171
+ 5 packets transmitted, 5 received, 0% packet loss, time 3999ms
172
+ rtt min/avg/max/mdev = 0.463/0.480/0.493/0.026 ms
173
+
174
+ If you have a container named chef-server and you want to NMAP scan it, simply run nmap against the host; for example:
175
+
176
+ $ nmap -sT -vv chef-server
177
+ Starting Nmap 5.21 ( http://nmap.org ) at 2014-01-30 17:18 PST
178
+ Initiating Ping Scan at 17:18
179
+ Scanning chef-server (100.64.13.1) [2 ports]
180
+ Completed Ping Scan at 17:18, 0.00s elapsed (1 total hosts)
181
+ Initiating Connect Scan at 17:18
182
+ Scanning chef-server (100.64.13.1) [1000 ports]
183
+ Discovered open port 80/tcp on 100.64.13.1
184
+ Discovered open port 22/tcp on 100.64.13.1
185
+ Discovered open port 443/tcp on 100.64.13.1
186
+ Discovered open port 444/tcp on 100.64.13.1
187
+ Discovered open port 4000/tcp on 100.64.13.1
188
+ Completed Connect Scan at 17:18, 0.06s elapsed (1000 total ports)
189
+ Nmap scan report for chef-server (100.64.13.1)
190
+ Host is up (0.0029s latency).
191
+ Scanned at 2014-01-30 17:18:14 PST for 0s
192
+ Not shown: 995 closed ports
193
+ PORT STATE SERVICE
194
+ 22/tcp open ssh
195
+ 80/tcp open http
196
+ 443/tcp open https
197
+ 444/tcp open snpp
198
+ 4000/tcp open remoteanything
199
+ Read data files from: /usr/share/nmap
200
+ Nmap done: 1 IP address (1 host up) scanned in 0.10 seconds
201
+
202
+ ### Ephemeral Container Cloning
201
203
 
202
204
  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.
203
205
 
@@ -223,7 +225,6 @@ To put the container back into the default, persistent mode:
223
225
  [TL] container chef-client persistent # Completed in 17.3692 seconds!
224
226
  [TL] TestLab v1.1.0 Finished (17.8692 seconds)
225
227
 
226
-
227
228
  ## Network Routes
228
229
 
229
230
  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`.
@@ -250,6 +251,34 @@ These routes can be manually manipulated as well (regardless of if you have spec
250
251
  del - Delete routes to lab networks
251
252
  show - Show routes to lab networks
252
253
 
254
+ # Reference
255
+
256
+ ## APT-Cacher NG
257
+
258
+ If you are prompted for login credentials while using the APT-Cacher NG web UI you should use username admin, password admin .
259
+
260
+ If you start seeing APT errors in your containers, it is likely because you have some corruption or some other issue with APT-Cacher NG's cache. Access the URL below if you need to have APT-Cacher NG repair itself.
261
+
262
+ http://100.64.13.254:3142/acng-report.html
263
+
264
+ ## Chef-Server Web UI
265
+
266
+ You can access the Chef server's web UI using the following URL.
267
+
268
+ https://chef-server:444
269
+
270
+ ## Chef-Server API
271
+
272
+ You can access the Chef server's API using the following URL.
273
+
274
+ https://chef-server
275
+
276
+ ## Linux Containers (LXC)
277
+
278
+ ### Service Startup Delay
279
+
280
+ LXC takes around 1-2 minutes before it will switch the runlevel in your container and start executing daemons which are set to start on boot. Because of this if you import a container from an image or clone a container, upon starting that container you will experience this delay before services are automatically started up. There is one exception to this and that is the SSH daemon is started immediately by LXC. This means you can manually SSH in, or use some other method such as capistrano, to start your required services; but it is advisable that you wait and allow the system to start the services as this would indicate that it would properly startup in production. With some containers such as the chef-server; we use it's provisioner to start the services we want when TestLab brings the container online.
281
+
253
282
  # Using TestLab Programmatically
254
283
 
255
284
  Accessing TestLab via code is meant to be fairly easy and straightforward. To get an instance of TestLab you only need about four lines of code:
@@ -1,6 +1,6 @@
1
1
  class TestLab
2
2
  unless const_defined?(:VERSION)
3
3
  # TestLab Gem Version
4
- VERSION = "1.20.2"
4
+ VERSION = "1.20.3"
5
5
  end
6
6
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: testlab
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.20.2
4
+ version: 1.20.3
5
5
  platform: ruby
6
6
  authors:
7
7
  - Zachary Patten
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2014-02-02 00:00:00.000000000 Z
11
+ date: 2014-02-03 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: gli