From 93227e362aee5de718f37e214bd3886649f4b2bb Mon Sep 17 00:00:00 2001 From: Pavel Raiskup Date: Wed, 5 Nov 2014 13:46:19 +0100 Subject: controller/README: reworked from top-srcdir README * README: Made as symlink to controller/README. * controller/Makefile.am: Distribute the README and configuration file template. * controller/README: Reworked version of README following current API. * controller/doc/dtf-controller/OSID.sh.template: New configuration template. * tester/dtf-prepare-testsuite: Prepare also basic taskdir structure. --- README | 57 +----------- controller/Makefile.am | 6 +- controller/README | 118 +++++++++++++++++++++++++ controller/doc/dtf-controller/OSID.sh.template | 20 +++++ tester/dtf-prepare-testsuite | 11 +++ 5 files changed, 155 insertions(+), 57 deletions(-) mode change 100644 => 120000 README create mode 100644 controller/README create mode 100644 controller/doc/dtf-controller/OSID.sh.template diff --git a/README b/README deleted file mode 100644 index de16e14..0000000 --- a/README +++ /dev/null @@ -1,56 +0,0 @@ -GENERAL INFO -============ - -System checking (dummy) testsuite fw. The tests are *expected* to be -destructive and always performed under root account; test writer should only -make sure that no test conflicts with others (so that all tests are able to run -on one machine successfully in any order). - -TODO: bash-only, unix.. - -OVERVIEW -======== - - -Each file should consist of config.sh and runtest.sh. Both are supposed to be -"sourced" into another scripts (so no need to have execute permissions). Each -test case should have its own directory. - -USAGE (locally) -=============== - -The most simple usage is like `./run`. Script is able to search for available -test-cases and then run them on local machine. Note that this is not generaly -safe and you should avoid that in most cases. For more info, run -`./run --help`. TODO: The testsuite is root-only. - -REMOTE RUN -========== - -You need to have OpenStack credentials file in ./private/ostack.yml configured. -The file should look like (be sure that only you can read that file): - $ cat ./private/ostack.yml: - --- - os_username: os1username - os_tenant_id: 9df30fc192f5xxxxxxxxxxxxxxxx0110 - os_nova_password: your_os_password - -Then it should be enough to run: - - $ ./run_remote - -API for config.sh file -====================== - -Variables which should/may be defined in config.sh file. - -$DTF_TEST_ID - unique ID of task. Without spaces. - -$DTF_TEST_DESCRIPTION - descriptive info about test, will be used for -generating html or otherwise formated result output. - -REQUIREMENTS -============ - -Packages needed to successful run - * ansible (remote running) diff --git a/README b/README new file mode 120000 index 0000000..6f1e091 --- /dev/null +++ b/README @@ -0,0 +1 @@ +controller/README \ No newline at end of file diff --git a/controller/Makefile.am b/controller/Makefile.am index 0df88b8..e271af9 100644 --- a/controller/Makefile.am +++ b/controller/Makefile.am @@ -6,6 +6,9 @@ bin_SCRIPTS = \ bin/dtf-return-machine \ bin/dtf-controller +doc_DATA = README \ + doc/dtf-controller/OSID.sh.template + sysconf_DATA = etc/dtf.sh pkgdata_DATA = $(srcdir)/share/dtf-controller/parse_credsfile @@ -89,7 +92,8 @@ CONTROLLERDATA = \ EXTRA_DIST = \ $(CONTROLLERSOURCES) \ $(CONTROLLERDATA) \ - $(srcdir)/libexec/dtf-wait-for-ssh + $(srcdir)/libexec/dtf-wait-for-ssh \ + $(srcdir)/doc/dtf-controller/OSID.sh.template CLEANFILES = $(GENERATED_FILES) .dep $(TEST_GEN_FILES_LIST) diff --git a/controller/README b/controller/README new file mode 100644 index 0000000..136c476 --- /dev/null +++ b/controller/README @@ -0,0 +1,118 @@ +Dummy (or Destructive) Testsuite Framework (DTF) +================================================ + +Testsuite supported by this framework is expected¹ to be destructive, may +require root permissions or basically whatever. So do not run such testsuite on +your machine unless you *really* know what you are doing. It is always better +to create temporary virtual machine to run them there (we have some tooling for +OpenStack VM provisioning). + + +WORK-FLOW +--------- + +In general, we expect these steps for running the testsuite: + + * generate self-standing testsuite tarball + * start (temporary) virtual machine + * copy the test tarball on the new machine and perform testing + * collect the results from VM + * terminate the VM + +However, the testsuite is designed so it may be developed (and thus run) +locally. + +OVERVIEW +-------- + +The framework consists of basically two parts, 'tester' and 'controller'. + +The 'tester' component is something like tool-set to help users with writing +theirs 'testsuites'. That is (a) convenient (Bash) library available for +for testsuite, (b) main running script (named 'run', it is also part of DTF API) +and (c) tooling which helps with testsuite initialization. + +The 'controller' part is tool-set which helps you to automatize running of the +testsuite on remote boxes (currently on OpenStack VMs only). + + +PORTABILITY +----------- + +Currently, the tools here are mostly written in Bash (not shell) and Perl and +thats the reason why you need² to have these languages working on your system. +Also, it was tested only on GNU/Linux operating system. + + +CREATE TESTSUITE +---------------- + +Each testsuite must be self-standing, distributable and ideally non-destructive. +Creating testsuite should follow this cook-book: + +* Create the directory structure: + + $ mkdir YOURPKG_TEST_DIR + $ dtf-prepare-testsuite YOURPKG_TEST_DIR + + Then prepares the 'dtflib', 'run' script and basic dummy task for you. The + dummy test-case created is in 'YOURPKG_TEST_DIR/tasks/sample/runtest.sh'. + + Be aware of the fact that 'dtf-prepare-testsuite' is expected to be always run + against latest GIT version of that script. The 'dtflib' and 'run' files (and + probably other) will then be copied from GIT. + +* Test the sample: + + $ ./YOURPKG_TEST_DIR/run + RUN dummy-sample ... [ OK ] + + The 'runtest.sh' file must have the 'run()' function defined and should follow + the exit-status API defined in 'run' script. + +* To distribute the tarball, just run: + + $ ./YOURPKG_TEST_DIR/run --dist | gzip > testsuite.tar.gz + + Also, please look at the `YOURPKG_TEST_DIR/run --help` output. + + +REMOTE RUN +---------- + +To perform this task easily, we expect you to have access to some OpenStack +instance. You need to have OpenStack credentials file in +'~/.dtf/private/os/OSID.yml' (note the OSID identifier). The file should look +like (be sure that only *you* can read that file): + + $ cat ~/.dtf/private/os/OSID.yml + --- + os_auth_url: http://control.example.com:5000/v2.0 + os_tenant_id: 9df30fc192f5xxxxxxxxxxxxxxxx0110 + os_tenant_name: Your OS Project + os_username: os1username + os_nova_password: your_os_password + +Also, you must have your distribution images prepared available in OpenStack. +This needs to be configured for DTF in '~/.dtf/os/OSID.sh'. See the +'OSID.sh.template' doc file for example configuration. + +Then it should be enough to run: + + $ dtf-run-remote --distro=fedora --distro-version=20 --taskdir YOUR_TEST_DIR + ... + + +REQUIREMENTS +------------ + +Packages needed to successful run + * ansible (for remote runs) + * Perl + * Bash + * perl(Text::Xslate) + * perl(YAML::Syck) + +---- +¹ However, making tests it non-destructive is highly recommended. +² More portable approach was still not needed. diff --git a/controller/doc/dtf-controller/OSID.sh.template b/controller/doc/dtf-controller/OSID.sh.template new file mode 100644 index 0000000..e37909d --- /dev/null +++ b/controller/doc/dtf-controller/OSID.sh.template @@ -0,0 +1,20 @@ +declare -A os_flavor_ids os_image_ids + +export os_flavor_ids=[] +export os_image_ids=[] + +os_flavor_ids["fedora19"]="a4827976-e727-4135-ba59-7d5fdb9ce4e2" +os_image_ids["fedora19"]="8ef96554-5f93-4cae-8c4f-225c6239eb49" + +os_flavor_ids["fedora20"]="a4827976-e727-4135-ba59-7d5fdb9ce4e2" +os_image_ids["fedora20"]="5fd723b7-e00d-49d3-b17b-65af842d02ab" + +os_flavor_ids["fedora21"]="a4827976-e727-4135-ba59-7d5fdb9ce4e2" +os_image_ids["fedora21"]="27358d7b-7c31-444b-8d92-6f3bc81777e0" + +os_flavor_ids["fedorarawhide"]="a4827976-e727-4135-ba59-7d5fdb9ce4e2" +os_image_ids["fedorarawhide"]="cc98b503-d849-48bc-8541-b1a903b1f564" + +export os_keypair=your-keypair-id +export os_security_group=your-sec-group-id +export os_network_dev=os-project-network-id diff --git a/tester/dtf-prepare-testsuite b/tester/dtf-prepare-testsuite index 76031a9..0e1c54c 100755 --- a/tester/dtf-prepare-testsuite +++ b/tester/dtf-prepare-testsuite @@ -6,3 +6,14 @@ srcdir=$(cd -P -- "$(dirname -- "$0")" && pwd -P) || exit 1 ln -sf "$srcdir/run" "$tasks_srcdir" ln -sf "$srcdir/libdtf" "$tasks_srcdir" +mkdir -p "$tasks_srcdir/tasks/sample" + +cat < "$tasks_srcdir/tasks/sample/runtest.sh" +export DTF_TEST_ID="dummy-sample" +export DTF_TEST_DESCRIPTION="Just an example." + +run() +{ + return 0 +} +EOF -- cgit