1TUNIR(8) Tunir TUNIR(8)
2
6 tunir - Tunir, the simple CI with a big heart.
7 Tunir is a simple testing tool. The goal is to have a system which is
9 simple to setup, and easy to maintain.
10 NOTE:
12 Please use the gotun project if you want to spin up your instances
13 on AWS or OpenStack.
14 Contents:
16
18 I have used Jenkins before. I was maintaining one instance in one of my
19 VPS instance. The amount of RAM required by Jenkins was too much for
20 my small VM. I can admit that I am not a great sys-admin anyway.
21 As part of my daily job, I have to test the latest cloud images we
23 build under Fedora project. While doing so, I figured out that most of
24 it can be automated if we have a system to create/maintain/terminate
25 cloud instances. Of course I do not want any actual cloud, it will be a
26 different monster to maintain.
27 This is the point where I came up with Tunir. Tunir is a simple testing
29 tool that will help me run automated tests for the cloud images. I kept
30 the system generic enough to execute any kind of tests people want.
31 The configuration is very minimal with Tunir. There is also a golang
33 verion called gotun which has better option to run the tests inside
34 OpenStack or AWS.
35
37 Tunir is written in Python. Currently it works with Python2.7+
38 Clone the repository
40 $ git clone https://github.com/kushaldas/tunir.git
41 Install the dependencies
43 We are currently depended on the following projects or libraries.
44 · libvirt
46 · libguestfs
48 · libguestfs-tools
50 · ansible
52 · paramiko
54 · vagrant-libvirt
56 · pycrypto
58 · net-tools
60 · typing
62 · python-systemd (python2-systemd package in Fedora)
64 · Ansible (optional)
66 · libcloud
68 You can install them in Fedora by the following command:
70 $ sudo dnf install libguestfs-tools python-paramiko docker-io vagrant-libvirt ansible net-tools python-crypto python2-typing python2-systemd python-libcloud
72 NOTE:
74 Remember to install python2-systemd package using dnf only
75
77 Tunir is a mini continuous integration (CI) system which can run a set
78 of commands/tests in a new cloud VM, or bare metal, or in Vagrant boxes
79 based on the job configurations.
80 The current version can be used along with cron to run at predefined
82 times. Tunir prints the output in the terminal, it also saves each com‐
83 mand it ran, and the output in a text file located at
84 '/var/run/tunir/tunir_results.txt'.
85 Configuring a new job
87 There are two different kinds of job configuration files, the newer one
88 is Multi-VM config which can take any qcow2 image and use them to boot
89 up one or more VMs. The other option is to use a JSON file based con‐
90 figuration which can be used for vm(s), vagrant images, or bare metal
91 remote system based testing.
92 For a Multi-VM configuration for a job called default create
94 default.cfg file as explained below. We will also require another
95 default.txt file which will contain the steps for testing.
96 jobname.cfg
98 New in version 0.14.
99 The following example contains a job where we are creating two VMs from
102 the given image files. The images can be either standard cloud image,
103 or Atomic image. We generate ssh keys for each run, and use that to
104 login to the box.
105 [general]
107 cpu = 1
108 ram = 1024
109 [vm1]
111 user = fedora
112 image = /home/Fedora-Cloud-Base-20141203-21.x86_64.qcow2
113 [vm2]
115 user = fedora
116 image = /home/Fedora-Cloud-Base-20141203-21.x86_64.qcow2
117 The above configuration file is self-explanatory. Each of the vm(s)
119 created from the above configuration will get all the other vms' IP
120 details in the /etc/hosts along with vm name. Means vm1 can ping vm2
121 and vice versa. For each run, Tunir creates a new RSA key pair and
122 pushes the public key to each vm, and uses the private key to do ssh
123 based authentication.
124 How to execute a multivm job?
126 $ sudo tunir --multi jobname
127 The above commands expects a jobname.cfg, and a jobname.txt containing
129 the commands, in the current directory. You can see below for an exam‐
130 ple of jobname.txt.
131 Debugging test vm(s)
133 New in version 0.14.
134 This can also be used a quick way to get a few vm(s) up. While using
137 Multi-VM configuration, one can pass --debug command line argument, and
138 this will make sure that the vm(s) do not get destroyed at the end of
139 the tests. It will create a destroy.sh file, and print the path at the
140 end of the run. All the vm(s) will be in running condition. You can ssh
141 into them by using private.key file found in the same directory of the
142 destroy.sh.
143 When your debugging is done, you can execute the shell script to clean
145 up all the running instances and any temporary file created by the pre‐
146 vious run.
147 # sh /tmp/tmpXYZ/destroy.sh
149 WARNING:
151 The private key remains on the disk while running Tunir in the debug
152 mode. Please remember to execute the destroy.sh script to clean up
153 afterwards.
154 jobname.json
156 This file is the main configuration for the job when we just need only
157 one vm, or using Vagrant, or testing on a remote vm/bare metal box.
158 Below is the example of one such job.
159 {
161 "name": "jobname",
162 "type": "vm",
163 "image": "/home/vms/Fedora-Cloud-Base-20141203-21.x86_64.qcow2",
164 "ram": 2048,
165 "user": "fedora",
166 }
167 The possible keys are mentioned below.
169 name The name of the job, which must match the filename.
171 type The type of system in which the tests will run. Possible values
173 are vm, docker, bare.
174 image Path to the cloud image in case of a VM. You can provide docker
176 image there for Docker-based tests, or the IP/hostname of the
177 bare metal box.
178 ram The amount of RAM for the VM. Optional for bare or Docker types.
180 user The username to connect to.
182 password
184 The password of the given user. Right now for cloud VM(s) con‐
185 nect using ssh key.
186 key The path to the ssh key, the password value should be an empty
188 string for this.
189 port The port number as string to connect. (Required for bare type
191 system.)
192 jobname.txt
194 This text file contains the bash commands to run in the system, one
195 command per line. In case you are rebooting the system, you may want to
196 use SLEEP NUMBER_OF_SECONDS command there.
197 If a command starts with @@ sign, it means the command is supposed to
199 fail. Generally, we check the return codes of the commands to find if
200 it failed, or not. For Docker container-based systems, we track the
201 stderr output.
202 We can also have non-gating tests, means these tests can pass or fail,
204 but the whole job status will depend on other gating tests. Any command
205 in jobname.txt starting with ## sign will mark the test as non-gating.
206 Example:
208 ## curl -O https://kushal.fedorapeople.org/tunirtests.tar.gz
210 ls /
211 ## foobar
212 ## ls /root
213 ## sudo ls /root
214 date
215 @@ sudo reboot
216 SLEEP 40
217 ls /etc
218 POLL directive
220 New in version 0.17.
221 We also have a POLL directive, which can be used to keep polling the vm
224 for a successful ssh connection. It polls after every 10 seconds, and
225 timeout is currently set for 300 seconds. One should this one instead
226 of SLEEP directive after a reboot.
227 For Multi-VM configurations
229 New in version 0.14.
230 In case where we are dealing with multiple VMs using .cfg file in our
233 configuration, we prefix each line with the vm name (like vm1, vm2,
234 vm3). This marks which command to run on which vm. The tool first
235 checks the available vm names to these marks in the jobname.txt file,
236 and it will complain about any extra vm marked in there. If one does
237 not provide vm name, then it is assumed that the command will execute
238 only on vm1 (which is the available vm).
239 vm1 sudo su -c"echo Hello > /abcd.txt"
241 vm2 ls /
242 vm1 ls /
243 In the above example the line 1, and 3 will be executed on the vm1, and
245 line 2 will be executed on vm2.
246 Using Ansible
248 NOTE:
249 If you want to run Ansible playbooks in your test, please have a
250 look at the gotun project, it has better support for running Ansi‐
251 ble, or any other tool in the host as the part of the test.
252 New in version 0.14.
254 Along with Multi-VM configuration, we got a new feature of using
257 Ansible to configure the vm(s) we create. To do so, first, create the
258 required roles, and playbook in a given path. You can write down the
259 group of hosts with either naming like vm1, vm2, vm3 or give them
260 proper names like kube-master.example.com. For the second case, we also
261 have to pass these hostnames in each vm definition in the configuration
262 file. We also provide the path to the directory containing all ansible
263 details with ansible_dir value.
264 Example configuration
266 [general]
268 cpu = 1
269 ram = 1024
270 ansible_dir = /home/user/contrib/ansible
271 [vm1]
273 user = fedora
274 image = /home/user/Fedora-Cloud-Atomic-23-20160308.x86_64.qcow2
275 hostname = kube-master.example.com
276 [vm2]
278 user = fedora
279 image = /home/user/Fedora-Cloud-Atomic-23-20160308.x86_64.qcow2
280 hostname = kube-node-01.example.com
281 [vm3]
283 user = fedora
284 image = /home/user/Fedora-Cloud-Atomic-23-20160308.x86_64.qcow2
285 hostname = kube-node-02.example.com
286 In the above example, we are creating 3 vm(s) with given hostnames.
288 NOTE:
290 If the number of CPU is not mentioned in the general section, Tunir
291 will get 1 virtual CPU for the vm.
292 How to execute the playbook(s)?
294 In the jobname.txt you should have a PLAYBOOK command as given below
295 PLAYBOOK atom.yml
297 vm1 sudo atomic run projectatomic/guestbookgo-atomicapp
298 In this example, we are running a playbook called atom.yml, and then in
300 the vm1 we are using atomicapp to start a nulecule app :)
301 Execute tests on multiple pre-defined VM(s) or remote machines
303 [general]
304 cpu = 1
305 ram = 1024
306 ansible_dir = /home/user/contrib/ansible
307 pkey = /home/user/.ssh/id_rsa
308 [vm1]
310 user = fedora
311 ip = 192.168.122.100
312 [vm2]
314 user = fedora
315 ip = 192.168.122.101
316 [vm3]
318 user = fedora
319 ip = 192.168.122.102
320 Example of configuration file to run the tests on a remote machine
322 The configuration:
323 {
325 "name": "remotejob",
326 "type": "bare",
327 "image": "192.168.1.100",
328 "ram": 2048,
329 "user": "fedora",
330 "key": "/home/password/id_rsa"
331 "port": "22"
332 }
333 Start a new job
335 $ sudo ./tunir --job jobname
336 Job configuration directory
338 You can actually provide a path to tunir so that it can pick up job
339 configuration and commands from the given directory.:
340 $ sudo ./tunir --job jobname --config-dir /etc/tunirjobs/
342 Timeout issue
344 In case if one of the commands fails to return within 10 minutes (600
345 seconds), tunir will fail the job with a timeout error. It will be
346 marked at the end of the results. You can change the default value in
347 the config file with a timeout key. In the below example I am having
348 300 seconds as timeout for each command.:
349 {
351 "name": "jobname",
352 "type": "vm",
353 "image": "file:///home/vms/Fedora-Cloud-Base-20141203-21.x86_64.qcow2",
354 "ram": 2048,
355 "user": "fedora",
356 "password": "passw0rd",
357 "timeout": 300
358 }
360
362 Vagrant is a very well known system among developers for creating
363 lightweight development systems. Now from tunir 0.7 we can use Vagrant
364 boxes to test. In Fedora, we can have two different kind of vagrant
365 provider, libvirt, and virtualbox.
366 WARNING:
368 The same host can not have both libvirt and virtualbox.
369 NOTE:
371 Please create /var/run/tunir directory before running vagrant jobs.
372 How to install vagrant-libvirt?
374 Just do
375 # dnf install vagrant-libvirt
377 The above command will pull in all the required dependencies.
379 How to install Virtualbox and vagrant?
381 Configure required virtualbox repo
382 # curl http://download.virtualbox.org/virtualbox/rpm/fedora/virtualbox.repo > /etc/yum.repos.d/virtualbox.repo
384 # dnf install VirtualBox-4.3 vagrant -y
385 # dnf install kernel-devel gcc -y
386 # /etc/init.d/vboxdrv setup
387 Now try using --provider option with vagrant command like
389 # vagrant up --provider virtualbox
391 Example of a libvirt based job file
393 {
394 "name": "fedora",
395 "type": "vagrant",
396 "image": "/var/run/tunir/Fedora-Cloud-Atomic-Vagrant-22-20150521.x86_64.vagrant-libvirt.box",
397 "ram": 2048,
398 "user": "vagrant",
399 "port": "22"
400 }
401 Example of a Virtualbox based job file
403 {
404 "name": "fedora",
405 "type": "vagrant",
406 "image": "/var/run/tunir/Fedora-Cloud-Atomic-Vagrant-22-20150521.x86_64.vagrant-virtualbox.box",
407 "ram": 2048,
408 "user": "vagrant",
409 "port": "22",
410 "provider": "virtualbox"
411 }
412 NOTE:
414 We have a special key provider in the config for Virtualbox based
415 jobs.
416
418 NOTE:
419 Please use the gotun project if you want to spin up your instances
420 on AWS or OpenStack.
421 Now we have support to use AWS for testing using Tunir. We can have
423 both HVM, and paravirtual types of instances to run the test. You will
424 require Python libcloud for the same.
425 NOTE:
427 It boots up the instances in us-west-1 zone.
428 Example of HVM
430 The following is a JSON file containing the config of a HVM instance.
431 {
433 "name": "awsjob",
434 "type": "aws",
435 "image": "ami-a6fc90c6",
436 "ram": 2048,
437 "user": "fedora",
438 "key": "PATH_TO_PEM",
439 "size_id": "m3.2xlarge",
440 "access_key": "YOUR_ACCESS_KEY",
441 "secret_key": "YOUR_SECRET_KEY",
442 "keyname": "YOUR_KEY_NAME",
443 "security_group": "THE_GROUP_WITH_SSH",
444 "virt_type": "hvm",
445 "timeout": 30
446 }
447 WARNING:
449 Remember that m3 instances are capable of running HVM.
450 Example of paravirtual
452 Another example with paravirtual type of instance.
453 {
455 "name": "awsjob",
456 "type": "aws",
457 "image": "ami-efff938f",
458 "ram": 2048,
459 "user": "fedora",
460 "key": "PATH_TO_PEM",
461 "size_id": "m1.xlarge",
462 "access_key": "YOUR_ACCESS_KEY",
463 "secret_key": "YOUR_SECRET_KEY",
464 "keyname": "YOUR_KEY_NAME",
465 "security_group": "THE_GROUP_WITH_SSH",
466 "virt_type": "paravirtual",
467 "aki": "aki-880531cd",
468 "timeout": 30
469 }
470 · genindex
472 · modindex
474 · search
476
478 Kushal Das
479
481 2015-2017, Kushal Das
4820.17 Mar 03, 2017 TUNIR(8)