Introduction
There may be times that you wish to influence the building and testing carried out on your change. You might for example be fixing an issue that affects a particular distribution or combination of distributions, for this reason you can change the tests carried out by indicating in the commit message the changes you require. Test Parameter sessions are in addition to the normal tests that would be run against a patch. This allows a patch with specific or unusual testing requirements to ensure that sufficient additional testing is run to gain confidence in the change being made. For patches that are of an experimental nature (i.e. developer is not sure of functionality, or only wants a limited set of tests to be run just to try something), it is also possible to submit a patch with the fortestonly
parameter.
To run additional sessions for your patch, add 'Test-Parameters: ' with space-separated name value pairs to your commit message.
For example:
Test-Parameters: envdefinitions=ONLY=32 testlist=conf-sanity
This will cause Autotest to run the normal test sessions plus 1 additional session where only conf-sanity test #32 will run.
Multiple 'Test-Parameters:' lines can be defined:
Test-Parameters: testgroup=review-ldiskfs clientdistro=sles12sp3 serverdistro=sles12sp3 Test-Parameters: testgroup=review-ldiskfs clientdistro=ubuntu1804 serverdistro=el7
Long lists can be catered for by escaping the carriage return:
Test-Parameters: ostcount=2 clients=1 ostsizegb=2 mdssizegb=2 envdefinitions=SLOW=yes \ testlist=sanity,liblustre
Quotations can be used when spaces are necessary in a value:
Test-Parameters: testlist=sanity envdefinitions=SANITY_EXCEPT="101g 102i"
The test parameter sessions can be influenced in many ways, see the General Parameters and Node Parameters sections below for all of the options.
General Parameters
Below is the list of general test parameters that can be used to run custom test sessions. These parameters differ from the node_parameters in that these do not need to be specified with a node type prefix.
For all of the examples below the 'Test-Parameters:' marker has been omitted to simplify the examples.
Pass through options for auster.
Valid values: See "Auster usage help" section on the Setting up a Lustre Test Environment wiki.
austeroptions=-R
When true, the MGT will share a partition with an MDT. When false, AT will create an additional partition to be used by just the MGT.
NOTE: mdtfilesystemtype will override mgtfilesystemtype when combinedmdsmgs is true. If standalonemgs is set to true, this option will be ignored.
Valid values: true, false (no value is the same as true)
# creates a shared partition to be used by the MGT and a MDT - typically not necessary since this is the default combinedmdsmgs # or combinedmdsmgs=true # creates an additional partition to be used by the MGT combinedmdsmgs=false
Comma separated environment definitions passed to the test environment. For definitions requiring spaces, enclose them in quotations.
NOTE: Be very careful setting environment variables directly (for example OSTFSTYPE=zfs) because Autotest creates a config file based on the environment it builds. If you ask for something at odds with Autotest's expectations you will see failure instead of success. In this case, for example, you should use the filesystemtype keyword described on this page. Autotest will then create the appropriate environment variables, the same is true for other things like ostcount instead of OSTCOUNT, ostsizegb instead of OSTSIZE, etc. Only use the envdefinitions variable when a direct variable is not listed here.
envdefinitions=SLOW=yes # multiple definitions, one with spaces that must be enclosed in quotations envdefinitions=SLOW=yes,SANITY_EXCEPT="101g 102i"
Setup cluster in failover configuration
Valid values: true, false (no value is the same as true)
# enable failover failover # or failover=true # disable failover setup failover=false
Patch will be built by Jenkins but Autotest will not run any testing.
Valid values: true, false (no value is the same as true)
# mark build as for build only forbuildonly # or forbuildonly=true # disable forbuildonly - typically not necessary since the default is false forbuildonly=false
The fortestonly
parameter marks that the patch is not intended for landing. Any testlist=
specified with Test-Parameters:
fortestonly
will replace the default tests that will be run, so it is possible to run only a subset of tests. Patches marked with fortestonly
will not receive the Verified
label from Maloo and cannot be landed. In order to land such a patch, it should be rebased and submitted without the fortestonly
keyword once the patch is known to be good, or the commit comment in Gerrit should be edited to remove the fortestonly
label which will rebuild and retest the patch and will preserve any reviews that the patch has received).
Valid values: true, false (no value is the same as true)
# mark build as for test only fortestonly # or fortestonly=true # mark patch as for build only and run a custom list of test fortestonly testlist=conf-sanity # disable fortestonly - typically not necessary since the default is false fortestonly=false
Sets the file system type for all server nodes (MDS, MGS and OSS).
NOTE: fstype should not be used in combination with <mdt/mgt/ost>filesystemtype.
Valid values: ldiskfs, zfs
# set all server nodes to use zfs fstype=zfs # set all server nodes to use ldiskfs fstype=ldiskfs # this may result in an unexpected configuration fstype=zfs mdtfilesystemtype=ldiskfs
Use iSCSI for failover testing
Valid values: 0 (no iSCSI), 1 (iSCSI)
# do not setup iscsi iscsi=0 # setup iscsi iscsi=1
Sets the size of the partitions on the MDS in GB.
Valid values: > 0 and must be an integer. When setting this value, take into consideration your mdtcount value and that most test nodes have ~90GB of disk space.
# configure 2GB partitions on the MDS mdssizegb=2
The total number of MDTs across all of the MDSs.
Valid values: 1 - 4 per MDS
# create 4 MDTs per MDS mdscount=2 mdtcount=8 # create 1 MDT per MDS mdscount=4 mdtcount=4
Configure the file system type to use on the MDTs.
NOTE: <mdt/mgt/ost>filesystemtype should not be used in combination with fstype.
Valid values: ldiskfs, zfs
# configure the MDTs to use zfs mdtfilesystemtype=zfs # configure the MDTs to use ldiskfs mdtfilesystemype=ldiskfs # this may result in an unexpected configuration fstype=zfs mdtfilesystemtype=ldiskfs
Sets the size of the partition on the MGS in GB. This value is only applicable when the session is using a stand alone MGS.
Valid values: > 0 and must be an integer. When setting this value, take into consideration that most test nodes have ~90GB of disk space.
# configure a 2GB partition on the MGS mgssizegb=2
Configure the file system type to use on the MGTs.
NOTE: The default value for combinedmdsmgs is true, therefore it must be set to false in order to configure a different file system type for the MGT. Also, <mdt/mgt/ost>filesystemtype should not be used in combination with fstype.
Valid values: ldiskfs, zfs
# configure the MGTs to use zfs mgtfilesystemtype=zfs combinedmdsmgs=false # configure the MGTs to use ldiskfs mgtfilesystemype=ldiskfs combinedmdsmgs=false # since combinedmdsmgs defaults to true, mgtfilesystemtype will be ignored and # the MGT will use ldiskfs mdtfilesystemtype=ldiskfs mgtfilesystemype=zfs # do not do this - may result in an unexpected configuration fstype=zfs mgtfilesystemtype=ldiskfs
Marks the test session as optional: does not impact the verified value from Maloo and is only run if resources are immediately available.
Valid values: true, false (no value is the same as true)
# mark a session as optional optional # or optional=true # mark a session as required - typically not necessary since false is the default optional=false
The total number of OSTs across all of the OSSs.
Valid values: 1 - 4 per OSS
# create 4 OSTs per OSS osscount=2 ostcount=8 # create 1 OST per OSS osscount=4 ostcount=4
Configure the file system type to use on the OSTs.
NOTE: <mdt/mgt/ost>filesystemtype should not be used in combination with fstype.
Valid values: ldiskfs, zfs
# configure the OSTs to use zfs ostfilesystemtype=zfs # configure the OSTs to use ldiskfs ostfilesystemype=ldiskfs # do not do this - may result in an unexpected configuration fstype=zfs ostfilesystemtype=ldiskfs
Sets the size of the partitions on the OSS in GB.
Valid values: > 0 and must be an integer. When setting this value, take into consideration your ostcount value and that most test nodes have ~90GB of disk space.
# configure 2GB partitions on the OSS ostsizegb=2
When true, Autotest will continue the session after a suite crashes. The session will continue with the suite following the one that crashed. When false, Autotest will stop the session and upload the results to Maloo immediately.
Valid values: true, false (no value is the same as true)
# configure the session to continue after a suite crashes - typically not necessary since the default is true resumeaftercrash # or resumeaftercrash=true # configure the session to stop after a suite crashes resumeaftercrash=false
Marks the session as enforcing: is used to determine the verified value from Maloo.
Valid values: true, false (no value is the same as true)
# mark the session as enforcing - typically not needed since the default is true signofftest # or signofftest=true # mark the session as not enforcing signofftest=false
Provisions a separate test node as the MGS. The MGS will be setup with the same parameters as the MDS unless they're overwritten.
Valid values: true, false (no value is the same as true)
# configure the session to run with a stand alone MGS standalonemgs # or standalonemgs=true # configure the session to run with the MGS on the MDS but separate partitions standalonemgs=false combinedmdsmgs=false # configure the session to run with the MGS on the MDS and have the MGT share # a partition with a MDT standalonemgs=false combinedmdsmgs=true # configure the session to run with a stand alone MGS with a different file # system type than the OSS and MDS standalonemgs mgtfilesystemtype=zfs mdtfilesystemtype=ldiskfs ostfilesystemtype
Configure the test session to run a specific test group. Specifying a test group makes it easy to run a typical test grouping with small modifications since the session will inherit all of the values from the base test with any overrides applied (see the code block below for examples).
NOTE: testgroup can be combined with testlist to run a test group plus additional suites
Valid values: See the Test Groups section for a complete list
# run a typical review-ldiskfs session with a stand alone MGS testgroup=review-ldiskfs standalonemgs # run failover with a specific server version testgroup=failover serverversion=2.11.50 # run review-dne-part-1 with additional suites testgroup=review-dne-part-1 testlist=sanity-lfsck,sanity-sec
Configure the test session to run a specific list of suites. testlist can be combined with testgroup to run a test group plus additional suites.
Valid values: sanity, sanityn, conf-sanity, mmp, replay-single, replay-dual, lnet-selftest, etc.
# run a custom list of suites testlist=sanity,sanity-sec,sanity-hsm # run review-dne-part-1 with additional suites testlist=sanity-lfsck,sanity-sec testgroup=review-dne-part-1
Configures the session to re-provision all of the nodes instead of simply reboot them.
Valid values: true, false (no value is the same as true)
# re-provision nodes after a timeout timeoutreprovision # or timeoutreprovision=true # reboot the nodes after a timeout - typically not necessary since reboot is the default timeoutreprovision=false
The trivial
keyword can be used to reduce the testing time (both wall-clock time as well as total test system hours) for patches that do not affect code functionality, such as changes to whitespace, comments, man pages, and test scripts (in conjunction with the testlist
keyword to ensure the modified test script is run if it isn't already). Patches marked with trivial
in the Test-Parameters:
list will run the review-ldiskfs
test session instead of the regular tests, so it currently runs only sanity
and lnet-selftest
to ensure basic functionality. If changes are only being made to a test script outside of those already run by default, an additional testlist=<test-script(s)>
keyword should be added with a comma-separated list of modified tests to ensure they are run to validate the changes. The trivial
keyword will reduce the test completion time from approximately 10h elapsed and 30h of total test system time to approximately 3h elapsed/system time. This saves test system resources that may be better spent on other patches.
Valid values: true, false (no value is the same as true)
# mark the patch as trivial trivial # or trivial=true # mark the patch as non-trivial - typically not necessary since this is the default trivial=false
Node Parameters
Node parameters are used to change how specific node types are configured. They must be prefixed with the node type being changed. Valid node types are client, mds, mgs, oss and server. Server is an alias that allows users to modify a value for all server node types (mds, mgs and oss). For example instead of writing
mdsdistro=el7 mgsdistro=el7 ossdistro=el7
Users can simply write
serverdistro=el7
Sets the architecture for the specified node. This attribute can be a string to represent a single architecture for all of the nodes or an array when the architecture is mixed. When using an array of architectures the number of architectures must match the count attribute for the specified node type.
Valid values: x86_64, ppc64, aarch64 (architecture must have been built for patch)
# all clients will use x86_64 clientarch=x86_64 # 1 client will use ppc64 and 1 x86_64 clientarches=ppc64,x86_64 clientcount=2 # this would fail since 3 clients were requested and only 2 architectures listed clientarches=ppc64,x86_64 clientcount=3
Used in conjunction with job to install a specific build on the specified node. job must be specified with buildno and version cannot be specified with buildno.
Valid values: Any valid Jenkins build number for the specified job
# install the server with a specific job/build combination serverbuildno=343 serverjob=lustre-master # this would fail since serverjob is not specified serverbuildno=343
The number of nodes to use for the specified node type.
NOTE: For MDS and OSS nodes, it's best to also set mdtcount / ostcount to ensure you have the expected number of targets.
Valid values:
clientcount | 2 - 4 |
mdscount | 1 - 4 |
osscount | 1 - 4 |
# configure session to run with 4 clients, 2 MDSs and 1 OSS clientcount=4 mdscount=2 osscount=1
Distribution to use for the specified node type.
Valid values: el7, el7.5, el7.6, ubuntu1604, ubuntu1804, sles12sp3, etc. (The distribution specified must have been built for the patch being tested. The distros built can be seen on the patch's build page in Jenkins.)
# specify the client to use el7 and all servers sles12sp3 clientdistro=el7 serverdistro=sles12sp3 # specify the client to use ubuntu1804, MDS to use el7 and OSS to use sles12sp3 clientdistro=ubuntu1804 mdsdistro=el7 ossdistro=sles12sp3
The IB stack to use for the specified node type.
Valid values: inkernel, ofa (The IB stack type must have been built for the build being tested. The stack types can be seen on the patch's build page in Jenkins.)
clientibstack=inkernel
Used with buildno to install a specific build on the specified node. buildno must be specified with job. version cannot be specified with job.
Valid values: Any valid Jenkins job, such as lustre-reviews, lustre-master, etc.
# install the server with a specific job/build combination serverjob=lustre-b2_10 serverbuildno=123 # this would fail since buildno is not specified for client serverjob=lustre-b2_10 serverbuildno=123 clientjob=lustre-master
Enables selinux on the specified node type.
Valid values: true, false (no value is the same as true)
# enables selinux on clients clientselinux # or clientselinux=true # disables selinux on clients - not typically necessary since false is the default clientselinux=false
The version of Lustre to use for the specified node type.
NOTE: version cannot be specified with job and build
Valid values: For a list of valid versions see the Versions section.
# specify patch level versions clientversion=2.10.3 serverversion=2.11.0 # specify minor versions which uses the highest patch level version clientversion=2.10 serverversion=2.11
Versions
Versions are pointers to job/build combinations and simplify using a specific Lustre version on a test node. Versions can be specified in the test parameters using the version node parameter. If there is a version missing send an email to charlie@whamcloud.com
Version | Build |
---|---|
2.7.0 (2.7) | |
2.8.0 (2.8) | |
2.9.0 (2.9) | |
2.10.0 | |
2.10.1 | |
2.10.2 | |
2.10.3 | |
2.10.4 | |
2.10.5 | |
2.10.6 (2.10) | https://build.whamcloud.com/job/lustre-b2_10/152 |
2.11.0 (2.11) | |
2.12.0 (2.12) | https://build.whamcloud.com/job/lustre-b2_12/2 |
Test Groups
Test groups are set lists of Lustre test suites managed by Autotest.
Name | Suites |
---|---|
review-ldiskfs | lnet-selftest, sanity |
review-dne-part-1 | sanity, sanityn, recovery-small, lustre-rsync-test |
review-dne-part-2 | runtests, ost-pools, sanity-hsm, sanity-scrub, sanity-lfsck, sanity-sec, mds-survey, large-scale |
review-dne-part-3 | conf-sanity |
review-dne-part-4 | mmp, replay-single, sanity-pfl, sanity-flr, sanity-dom, sanity-quota, replay-ost-single, insanity |
review-dne-zfs | runtests, sanity, sanityn, replay-single, conf-sanity, recovery-small, replay-ost-single, insanity, sanity-quota, lustre-rsync-test, ost-pools, sanity-lfsck, sanity-hsm |
review-dne-zfs-part-1 | sanity, sanityn, recovery-small, lustre-rsync-test |
review-dne-zfs-part-2 | runtests, ost-pools, sanity-hsm, sanity-scrub, sanity-lfsck, sanity-sec, mds-survey, large-scale |
review-dne-zfs-part-3 | conf-sanity |
review-dne-zfs-part-4 | mmp, replay-single, sanity-pfl, sanity-flr, sanity-dom, sanity-quota, replay-ost-single, insanity |
review-zfs | sanity-quota, sanity-flr, replay-single, replay-ost-single, insanity |
review-zfs-part-1 | runtests, sanity, sanityn, sanity-quota, ost-pools, sanity-lfsck, sanity-hsm, sanity-flr |
review-zfs-part-2 | replay-single, conf-sanity, recovery-small, replay-ost-single, insanity, lustre-rsync-test, large-scale, mds-survey |
review-ldiskfs-arm | sanity, lnet-selftest |
failover | recovery-mds-scale, recovery-random-scale, recovery-double-scale, recovery-small, replay-ost-single, replay-dual, replay-vbr, mmp, replay-single |
full | runtests, sanity, sanity-scrub, sanity-benchmark, sanity-lfsck, sanityn, sanity-hsm, sanity-flr, sanity-dom, sanity-lsnapshot, conf-sanity, racer, replay-single, recovery-small, replay-ost-single, replay-dual, replay-vbr, insanity, sanity-quota, sanity-sec, sanity-pfl, lustre-rsync-test, metadata-updates, ost-pools, mds-survey, mmp, performance-sanity, parallel-scale, large-scale, lnet-selftest, obdfilter-survey, parallel-scale-nfsv3, parallel-scale-nfsv4, posix |
full-patchless | runtests, sanity, sanity-scrub, sanity-benchmark, sanity-lfsck, sanityn, sanity-hsm, sanity-flr, sanity-dom, sanity-lsnapshot, racer, insanity, sanity-quota, sanity-sec, sanity-pfl, lustre-rsync-test, metadata-updates, ost-pools, mds-survey, mmp, performance-sanity, parallel-scale, large-scale, lnet-selftest, obdfilter-survey, parallel-scale-nfsv3, parallel-scale-nfsv4, posix |
regression | runtests, sanity, sanity-scrub, metadata-updates, sanity-benchmark, sanityn, lfsck, racer, replay-single, conf-sanity, recovery-small, replay-ost-single, replay-dual, replay-vbr, insanity, sanity-quota, ost-pools, mmp, lnet-selftest, obdfilter-survey, performance-sanity, parallel-scale, sanity-sec, lustre-rsync-test, parallel-scale-nfsv3, parallel-scale-nfsv4 |
review | runtests, sanity, sanityn, replay-single, conf-sanity, recovery-small, replay-ost-single, insanity, sanity-quota, lustre-rsync-test, ost-pools, lnet-selftest, sanity-lfsck, sanity-hsm |
review-dne | runtests, sanity, sanityn, conf-sanity, recovery-small, replay-single, replay-ost-single, insanity, sanity-quota, sanity-sec, lustre-rsync-test, ost-pools, lnet-selftest, mmp, sanity-scrub, sanity-lfsck, sanity-hsm |
review-mc | runtests, sanity, sanityn, replay-single, conf-sanity, recovery-small, replay-ost-single, insanity, sanity-quota, lustre-rsync-test, ost-pools, lnet-selftest, sanity-lfsck, sanity-hsm |
tiny | sanity |
basic | sanity, mmp, conf-sanity |
daos-regression | runtests, sanity, sanityn, sanity-daos, lnet-selftest, conf-sanity, replay-single, replay-ost-single, replay-dual, replay-vbr, recovery-small |
development | metadata-updates |