Use case: setup SQUAD with LAVA¶
Introduction¶
Once SQUAD installation is complete, a typical use case would be integrating it with a LAVA instance. The purpose of this use case is to describe a step-by-step set up of SQUAD with LAVA to submit and fetch jobs. If you haven't yet set up SQUAD, take a step back and follow Installation Instructions for production environments
Setting up a LAVA instance¶
LAVA has its own extensive documentation on how to get a server up and running. If you don't have it already, please refer to LAVA installation to configure yourself one. From this point it's taken that you have enough access to a running LAVA v2 instance that jobs can be submitted to and fetched from.
- Note:
Make sure that your LAVA instance has
event notifications
enabled, as it is disabled by default. See LAVA event notifications for details.
Creating a Backend for a LAVA instance¶
Log in into SQUAD admin view (/admin
) and access ci > backends > add backend
for inclusion form. Fill up accordingly:
name: name of the backend. Example: validation.linaro.org
url: LAVA RPC2 endpoint, it's how SQUAD will communicate with LAVA. Example: https://validation.linaro.org/RPC2
username: a LAVA user with enough access to submit jobs
token: a generated token for the user above, used to securely connect to the LAVA instance. See LAVA authentication tokens for details
implementation type: leave it as
lava
backend settings: used to spare specific settings for LAVA instances. For details see Backend settings
poll interval: number of minutes to wait before fetching a job from LAVA
max fetch attempts: max number of times SQUAD will attempt to fetch a job from LAVA
poll enabled: if this is disabled SQUAD will not try to poll jobs from LAVA
Creating a Project in SQUAD¶
SQUAD needs minimal data to start working with LAVA: Group and Project.
By logging in the admin view, go to core > groups > add
to add a new
group and core > projects > add
to add a new project. These are trivial
to create, but please feel free to contact us if any help is needed.
Submitting and fetching test jobs¶
Given that all steps above are working correctly, you are ready to submit your first job through SQUAD. You can learn from LAVA documentation how to write new test definitions or use existing ones. For the sake of simplicity, we'll stick to LAVA's example of first job and use it to call SQUAD api for submitting a new test job:
wget https://validation.linaro.org/static/docs/v2/examples/test-jobs/qemu-pipeline-first-job.yaml
curl localhost:8000/api/submitjob/<group-slug>/<project-slug>/<build-version>/<env> \
--header "Authorization: token $SQUAD_TOKEN" \
--form "backend=<backend-name>" \
--form "definition=@qemu-pipeline-first-job.yaml"
Where group-slug
and project-slug
are the ones created in steps above, whereas
build-version
and env
do not need to exist before submitting a job. For clarification buid-version
is usually a git-commit hash and env
is commonly the board target that a job is running.
Although it's not covered in this tutorial, creating a squad-token
is straightforward, do so
by logging into admin view and go to auth token > tokens > add
to add an auth token for a user.
Lastly, backend-name
is the one created in the sections above.
Extra use cases¶
The example above showed a simplistic SQUAD instance working along with a LAVA one. More can be done by using SQUAD's backend API to transform it into a proxy between a CI system (e.g. Jenkins) and a LAVA server. An instance of SQUAD is currently running at https://qa-reports.linaro.org and its set up is fully automated through ansible scripts at https://github.com/Linaro/qa-reports.linaro.org.