add README.md for mdbci operations

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)
+- 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 [build scripts package](https://github.com/mariadb-corporation/build-scripts-vagrant)
+- 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

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
+```
+