Skip to content

Latest commit

 

History

History
57 lines (34 loc) · 4.81 KB

preserve_hosts.md

File metadata and controls

57 lines (34 loc) · 4.81 KB
Raw

How to Preserve Hosts

Motivation

Often when developing acceptance tests to be run with beaker, you'll want to be able to quickly iterate on those tests in an already setup System Under Test (SUT) configuration. Beaker provides the ability to do that using its preserved hosts functionality.

But Is This The Right Solution?

Many people are of the opinion that if you have to login to a SUT, then you've already failed, and that the purpose of good automation is so that you don't ever have to do this. Beaker supports a diverse group of developers and testers, and we try to remain flexible and support multiple approaches to these problems.

Another approach you might take to debugging failed tests, during development or test runs in your Continuous Integration (CI) systems, is to archive any artifacts or log files from the SUTs, so that you can read them all from the beaker coordinator. Beaker provides a Domain-Specific Language (DSL) method to accomodate this workflow, called archive_file_from. Check out the how-to article on this method for details on it.

That being said, the preserved hosts functionality is still useful, particularly for new development. In this case, you might not be able to necessarily tell what files you might need from your SUTs, and exploration might be necessary.

How Do I Use It?

Note that where you decide to use this option will affect its precedence. You can learn more about this in our argument processing & precedence doc.

Command-Line Option

The primary way that this option is provided is through the command line, where it's represented by the --preserved-hosts option. It defaults to never, and if you run beaker --help, you'll see the range of values that can be taken:

$ beaker --help
    ...
    --preserve-hosts [MODE]      How should SUTs be treated post test
                                 Possible values:
                                 always (keep SUTs alive)
                                 onfail (keep SUTs alive if failures occur during testing)
                                 onpass (keep SUTs alive if no failures occur during testing)
                                 never (cleanup SUTs - shutdown and destroy any changes made during testing)
                                 (default: never)
    ...

Local Options or Global Config

You can also provide a value for this option wherever you can provide a value that gets merged into beaker's global options hash. The two ways to do this are to provide it in a local options file, or in the global CONFIG section of your hosts file. To learn more about how to set these options, check out the Options File Values and the CONFIG Section of a Hosts File sections of the argument processing & precedence doc.

Either way, the underlying property name that you will have to set if you use these options is :preserve_hosts.

What Does It Do (In Detail)?

Using the preserved hosts functionality outputs a hosts_preserved.yml file into the directory that holds all of the log files for a particular beaker run. The short way to access that directory is to look into the log/latest path, which is a symlink to the actual log directory for the run.

The hosts_preserved.yml file generated by a run differs from the original hosts file passed into Beaker in a number of ways:

  • all suites are emptied - the host names are updated to point to the IPs (or hostnames) of the VMs since they exist and no longer need provisioning - the provision option is set to false (check Beaker Test Run's provisioning section for details).

Beaker will also output the lines included below at the end of the run:

You can re-run commands against the already provisioned SUT(s) with:
/.../beaker --hosts log/centos7-64mdac-ubuntu1504-64a/2016-07-18_13_42_44/hosts_preserved.yml --tests smoke_simple.rb --preserve-hosts onpass

The important piece here is the hosts argument, in that it's informing you of where the preserved hosts file is located. Of course, until you kick off another beaker run, you can also reach this file with the log/latest/hosts_preserved.yml symlink, as mentioned at the beginning of this section.

What Do I Do With It?

For subsequent runs, if you want to set something, you'll have to pay attention to the precedence of your arguments, to be sure that you are overriding what is set in the preserved hosts file. Checkout the argument processing & precedence doc for more details on the precedence order of options parsing.