From 41935fb6d35342c8227d938caae402f9755031ee Mon Sep 17 00:00:00 2001 From: Timofey Turenko Date: Fri, 9 Feb 2018 20:01:15 +0200 Subject: [PATCH] add README.md for mdbci operations --- maxscale-system-test/README.md | 8 +- maxscale-system-test/mdbci/README.md | 172 +++++++++++++++++++++++++++ 2 files changed, 175 insertions(+), 5 deletions(-) create mode 100644 maxscale-system-test/mdbci/README.md diff --git a/maxscale-system-test/README.md b/maxscale-system-test/README.md index 6f3314a4b..62677172e 100644 --- a/maxscale-system-test/README.md +++ b/maxscale-system-test/README.md @@ -8,17 +8,15 @@ System level tests for MaxScale - >= 4 machines for Master/Slave - >= 4 machines for Galera cluster - environmental variables contains all information about backend: IPs, user names, passwords, paths to tools, etc -- backed can be created with help of [MDBCI tool](https://github.com/OSLL/mdbci) -- configuring of Master/Slave and Galera can be done with help of [build scripts package](https://github.com/mariadb-corporation/build-scripts-vagrant) +- backed can be created with help of [MDBCI tool](https://github.com/mariadb-corporation/mdbci) +- configuring of Master/Slave and Galera can be done with help of [maxscale-system-test/mdbci/run_test.sh script](mdbci/run_test.sh) ## Manuals -[How to run tests](https://github.com/mariadb-corporation/build-scripts-vagrant/blob/master/RUN_TEST.md) +[MDBCI and running tests basics](mdbci/README.md) [Hints: How to write a test](HOW_TO_WRITE_TEST.md) -[Build and test environment setup (if you want to play with MDBCI and Vagrant on your local machine](ENV_SETUP.md) - [Jenkins instructions](JENKINS.md) ## Environmental variables diff --git a/maxscale-system-test/mdbci/README.md b/maxscale-system-test/mdbci/README.md new file mode 100644 index 000000000..18e759eb6 --- /dev/null +++ b/maxscale-system-test/mdbci/README.md @@ -0,0 +1,172 @@ +# Running Maxscale system tests on Virtual Machines with MDBCI + +MDBCI is a tool to manage virtual machines (VMs). +VMs can be described in the simple JSON format. +JSON templates for test configuration can be found in +[maxscale-system-test/mdbci/templates/](templates/) + +'MDBCI_VM_PATH' have to be set before executing any MDBCI commands. +This variable points to the directory to store 'Vagrantfile's +for all VMs as well as all additional files (e.g. *network_config) + +libvirt/qemu and AWS VMs are supported. + +See [MDBCI README](https://github.com/mariadb-corporation/mdbci#mariadb-continuous-integration-infrastructure-mdbci) for details. + +Installation instructions: [PREPARATION_FOR_MDBCI](https://github.com/mariadb-corporation/mdbci/blob/integration/PREPARATION_FOR_MDBCI.md) + +## Basics of test setup + +Test setup is described in template. Templates are stored in +[maxscale-system-test/mdbci/templates/](templates/) +Own template have to be put to the same directory. + +Default environment for tests consists of: +* one VM for Maxscale +* 4 VMs for master/slave setup +* 4 VMs for Galera cluster + +Template for this configuration is +[maxscale-system-test/mdbci/templates/default.json.template](templates/default.json.template) + +Another templates: +| ```nogalera``` |only 1 VM for Maxscale and 4 for Master/Slaves| +| ```twomaxscales``` |2 VMs for Maxscale and 4 for Master/Slaves| +| ```big``` |1 VM for Maxscale, 8 for Master/Slaves and 4 for Galera| +| ```big15``` |1 VM for Maxscale, 15 for Master/Slaves and 4 for Galera| + +```box``` for ```big``` and ```big15``` is hard-coded as ```centos_7_aws_large``` + +Template can contain references to any environmental variables - they all +will be replaced with values before VMs starting + +The [maxscale-system-test/mdbci/run_test.sh](run_test.sh) script +brings test VMs configuration up and tries to execute +```maxscale-system-test``` using 'ctest'. + +Script can be executed without any parameters and without defining any +environmental variables. +In this case, tests will be executed for CentOS 7, MariaDB 10.2 and +Maxscale from current 'develop' repository +[http://max-tst-01.mariadb.com/ci-repository/develop/mariadb-maxscale/](http://max-tst-01.mariadb.com/ci-repository/develop/mariadb-maxscale/) +VMs will not be destroyed after the tests. + +The name of test run (and name of VMs set) is generated based on ```box``` parameter +and current date/time + +### Basic run_test.sh parameters + +|```target``` |name of binary repository to install Maxscale from| +|```box``` |Vagrant box to be used to create VMs | +|```test_set``` |Set of test to be executed in the 'ctest' format| +|```version```|Version of DB server in Master/Slave backend| +|```galera_version```|Version of DB server in Galera backend| +|```product```|Type of backend - 'mariadb' or 'mysql'| +|```template```|Name of *.json.template file with VMs descriptions in MDBCI format| +|```team_keys```|Path to the file with public ssh keys - this file is loaded to VMs| +|```do_not_destroy_vm```|if 'yes' VMs stay alive after test| +|```name```|The name of test run - any string to identify VMs set| + + +For complete list of environmental variables see comments in +[maxscale-system-test/mdbci/run_test.sh](run_test.sh) +and file [maxscale-system-test/mdbci/set_run_test_variables.sh](set_run_test_variables.sh) + +See [https://github.com/mariadb-corporation/mdbci/tree/integration/BOXES](https://github.com/mariadb-corporation/mdbci/tree/integration/BOXES) +for available boxes. + +```test_set``` examples +|```-I 4,4```|Run single test number 4| +|```-I 4,4,1,25,30```|Run tests number 4, 25 and 30 (the number '1' is a 'Stride' parameter)| +|```-I 1,10```|Run tests from 1 to 10| +|```-L REPL_BACKED```|Run all tests with 'REPL_BACKEND' label| +|```-LE UNSTABLE```|Run all tests EXCEPT tests with 'UNSTABLE' label| + +If ```galera_version``` is not defined the value of ```version``` is used also for Galera backend + +### Test execution + +After execution of 'run_test.sh` by default VMs stay alive and other tests can be executed. + +Test use environmental variables to get all infio about test setup (about VMs). + +The script [maxscale-system-test/mdbci/set_env.sh](set_env.sh) +loads all needed values (IPs, paths to ssh keyfiles, +user names, etc) into environmental variables. Script uses +data from ```${MDBCI_VM_PATH}/${name}_network_config``` file +and also calls MDBCI commands. + +Script have to be sourced: + +```bash +source ./mdbci/set_env.sh $name +``` + +or + +```bash +. ./mdbci/set_env.sh $name +``` + +After it, any 'maxscale-system-test ' can be executed, e.g.: + +```bash +./sql_queries +``` + +### Basic MDBCI and Vagrant operations + +#### Restore ${name}.config_file + +```bash +${mdbci_dir}/mdbci show network_config $name +``` + +#### Suspend VMs + +Before rebooting computer it is recommended to suspend +Vagrant-controlled VMs + +```bash +cd ${MDBCI_VM_PATH}/$name +vagrant suspend +``` + +#### Resume suspended VMs + +```bash +cd ${MDBCI_VM_PATH}/$name +vagrant resume +``` + +#### Destroying VMs + +```bash +${mdbci_dir}/mdbci destroy $name +``` + +#### Restoring backend + +Every test before any actions checks backend and tries to restore it if its broken. +To restore backend separatelly and for intial backend setup check_backend' can be used: + +```bash +. ./mdbci/set_env.sh $name +./check_backend +``` + +#### Restoring VMs from snapshot + +'run_test.sh' makes snapshot of all VMs before tests. The name of snapshot is 'clean'. + +In case of problem, after 'snapshot revert' it is recommended to re-create +${name}_network_config file, re-load environmental variables and run +'check_backend' + +```bash +${mdbci_dir}/mdbci snapshot revert --path-to-nodes $name --snapshot-name clean +${mdbci_dir}/mdbci show network_config $name +. ./mdbci/set_env.sh $name +./check_backend +``` +