- Introduction
- Use of the web interface
- Asset cleanup
- Use of the REST API
- Where to now?
This document provides additional information for use of the web interface or the REST API as well as administration information. For administrators it is recommend to have read the Installation Guide first to understand the structure of components as well as the configuration of an installed instance.
In general the web UI should be intuitive or self-explanatory. Look out for the little blue help icons and click them for detailed help on specific sections.
Some pages use queries to select what should be shown. The query parameters are generated on clickable links, for example starting from the index page or the group overview page clicking on single builds. On the query pages there can be UI elements to control the parameters, for example to look for more older builds or only show failed jobs or other settings. Additionally, the query parameters can be tweaked by hand if you want to provide a link to specific views.
The overview page is configurable by the filter box. Also, some additional query parameters can be provided which can be considered advanced or experimental. For example specifying no build will resolve the latest build which matches the other parameters specified. Specifying no group will show all jobs from all matching job groups. Also specifying multiple groups works, see the following example.
Specifying multiple groups with no build will yield the latest build of the first group. This can be useful to have a static URL for bookmarking.
Test suites can be described using API commands or the admin table for any operator using the web UI.
If a description is defined, the name of the test suite on the tests overview page shows up as a link. Clicking the link will show the description in a popup. The same syntax as for comments can be used, that is Markdown with custom extensions such as shortened links to ticket systems.
Based on comments in the individual job results for each build a certificate icon is shown on the group overview page as well as the index page to indicate that every failure has been reviewed, e.g. a bug reference or a test issue reason is stated:
Show bug or label icon on overview if labeled gh#550
-
Show bug icon with URL if mentioned in test comments
-
Show bug or label icon on overview if labeled
For bugreferences write <bugtracker_shortname>#<bug_nr> in a comment, e.g. "bsc#1234", for generic labels use label:<keyword> where <keyword> can be any valid character up to the next whitespace, e.g. "false_positive". The keywords are not defined within openQA itself. A valid list of keywords should be decided upon within each project or environment of one openQA instance.
Related issue: #10212
'Hint:' You can also write (or copy-paste) full links to bugs and issues. The links are automatically changed to the shortlinks (e.g. https://progress.opensuse.org/issues/11110 turns into poo#11110). Related issue: poo#11110
Also github pull requests and issues can be linked using the generic format `<marker>[#<project/repo>]#<id>`, e.g. gh#os-autoinst/openQA#1234, see gh#973
All issue references are stored within the internal database of openQA. The status can be updated using the /bugs API route for example using external tools.
Based on comments on the group overview individual builds can be tagged. As 'build' by themselves do not own any data the job group is used to store this information. A tag has a build to link it to a build. It also has a type and an optional description. The type can later on be used to distinguish tag types.
The generic format for tags is
tag:<build_id>:<type>[:<description>], e.g. tag:1234:important:Beta1.
The more recent tag always wins.
A 'tag' icon is shown next to tagged builds together with the description on the group_overview page. The index page does not show tags by default to prevent a potential performance regression. Tags can be enabled on the index page using the corresponding option in the filter form at the bottom of the page.
As builds can now be tagged we come up with the convention that the 'important' type - the only one for now - is used to tag every job that corresponds to a build as 'important' and keep the logs for these jobs longer so that we can always refer to the attached data, e.g. for milestone builds, final releases, jobs for which long-lasting bug reports exist, etc.
At the top of the test results overview page is a form which allows filtering tests by result, architecture and TODO-status.
There is also a similar form at the bottom of the index page which allows filtering builds by group and customizing the limits.
Assets like ISO files consume a huge amount of disk space. Therefore openQA removes assets automatically according to configurable limits.
This section provides an overall description of the cleanup strategy and how to configure the limits. Cleanup-related parameter for the REST API can be found in the 'Asset handling' section under 'Use of the REST API'.
openQA frequently checks whether assets need to be removed according to the configured limits.
To find out whether an asset should be removed, openQA determines by which job groups the asset is used. If at least one job within a certain job group is using an asset, the asset is considered to be used by that group.
So an asset can be accounted to multiple groups. The assets table which is accessible via the admin menu shows these groups for each asset and also the latest job.
If the size limit for assets by a certain group is exceeded, openQA will remove assets accounted to that group:
-
Assets belonging to old jobs are preferred.
-
Assets belonging to jobs which are still scheduled or running are not considered.
-
Assets which are also accounted to another group that has still space left are not considered.
Assets which do not belong to any group are removed after a configurable duration. Keep in mind that this behavior is also enabled on local instances and affects all cloned jobs (unless cloned into a job group).
To configure the maximum size for the assets of a group, open 'Job groups' in the operators menu and select a group. The size limit for assets can be configured under 'Edit job group properties'. It also shows the size of assets which belong to that group and not to any other group.
Job groups inherit the size limit from their parent group unless the limit is set explicitely. The default size limit for groups can be adjusted in the default_group_limits section of the openQA config file.
openQA includes a client script which - depending on the distribution - is
packaged independantly if you just want to interface with an existing openQA
instance without needing to install the full package. Call
<openqa-folder>/script/client --help for help (openSUSE: openqa-client
--help).
Basics are described in the Getting Started guide.
Tests can be triggered over multiple ways, using clone_job.pl, jobs post,
isos post as well as retriggering existing jobs or whole media over the web
UI.
If one wants to recreate an existing job from any publically available openQA
instance the script clone_job.pl can be used to copy the necessary settings
and assets to another instance and schedule the test. For the test to be
executed it has to be ensured that matching ressources can be found, for
example a worker with matching WORKER_CLASS must be registered. More details
on clone_job.pl can be found in Writing Tests.
Single jobs can be spawned using the jobs post API route. All necessary
settings on a job must be supplied in the API request. The "openQA client" has
examples for this.
The most common way of spawning jobs on production instances is using the
isos post API route. Based on previously defined settings for media, job
groups, machines and test suites jobs are triggered based on template
matching. The Getting Started guide already
mentioned examples. Additionally to the necessary template matching parameters
more parameters can be specified which are forwarded to all triggered jobs.
There are also special parameters which only have an influence on the way the
triggering itself is done. These parameters all start with a leading
underscore but are set as request parameters in the same way as the other
parameters.
| _NO_OBSOLETE |
Do not obsolete jobs in older builds with same DISTRI and VERSION (as is the default behavior). With this option jobs which are currently pending, for example scheduled or running, are not cancelled when a new medium is triggered. |
| _DEPRIORITIZEBUILD |
Setting this switch '1' will not immediately obsolete jobs of old builds but rather deprioritize them up to a configurable limit of priority. |
| _DEPRIORITIZE_LIMIT |
The configurable limit of priority up to which jobs
should be deprioritized. Needs |
| _ONLY_OBSOLETE_SAME_BUILD |
Only obsolete (or deprioritize) jobs for the same BUILD. This is useful for cases where a new build appearing does not necessarily mean existing jobs for earlier builds with the same DISTRI and VERSION are no longer interesting, but you still want to be able to re-submit jobs for a build and have existing jobs for the exact same build obsoleted. |
| _GROUP |
Job templates not matching the given group name are ignored. Does not
affect obsoletion behavior, so you might want to combine with |
| _GROUP_ID |
Same as |
| _PRIORITY |
Sets the priority for the new jobs (which otherwise defaults to the priority of the job template) |
Example for _DEPRIORITIZEBUILD and _DEPRIORITIZE_LIMIT.
openqa-client isos post ISO=my_iso.iso DISTRI=my_distri FLAVOR=sweet \
ARCH=my_arch VERSION=42 BUILD=1234 \
_DEPRIORITIZEBUILD=1 _DEPRIORITIZE_LIMIT=120 \Multiple parameters exist to reference assets to be used by tests, for example
ISO, HDD, ASSET, KERNEL, INITRD. Corresponding files must be
provided within the path /var/lib/openqa/share/factory local to the openQA
web-UI. All assets specified in this way in any job are tracked by openQA and
considered by the automatic cleanup described under 'Asset cleanup'.
Multiple options can be used based on special suffix types. These types can also be combined, for example ISO_1_DECOMPRESS_URL.
| _<NR> |
To specify multiple assets of the same type use a number digit, for
example |
| _URL |
Before starting these jobs try to download these assets into the asset directory of the openQA web-UI from trusted domains specified in /etc/openqa/openqa.ini. |
| _DECOMPRESS_URL |
Specify a compressed asset to be downloaded that will be uncompressed by openQA. Specify the non-suffixed parameter additionally to provide a rename target, for example ISO_1_DECOMPRESS_URL=http://host/foo2.iso.xz and ISO_1=foo.iso |
For test developers it is recommended to continue with the Test Developer Guide.