From 0c5fef6e0e3a6ac055a0d0454a1859b41a553592 Mon Sep 17 00:00:00 2001 From: Lukas Holecek Date: Wed, 20 Mar 2024 12:11:01 +0100 Subject: [PATCH] Improve documentation JIRA: RHELWF-10507 --- docs/index.rst | 4 ++ docs/policies.rst | 136 +++++++++++++++++++++++++++++----------------- 2 files changed, 90 insertions(+), 50 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index b2a9b4fe..cf78da07 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,6 +11,10 @@ Greenwave gating points in a software delivery pipeline, based on test results stored in `ResultsDB`_ and waivers stored in `WaiverDB`_. +**Gating** serves as a way to stop broken or non-compliant builds (RPM, +container image, module, compose…) from getting shipped to customers or getting +through other gating points (for example tagging a build as stable). + .. toctree:: :maxdepth: 2 :caption: Contents: diff --git a/docs/policies.rst b/docs/policies.rst index 060d71bd..49290c96 100644 --- a/docs/policies.rst +++ b/docs/policies.rst @@ -2,11 +2,37 @@ Writing Policies ================ +Greenwave policies are part of the server configuration and define which test +cases are required to pass for specific decision contexts (or gating points), +subject types, product versions or even for individual artifact names +(packages, modules, images…). + When you ask Greenwave for a decision, it checks all the configured policies to find which ones are applicable to the subject of the decision. It then evaluates all the rules in each applicable policy and makes a decision based on whether they are *all* satisfied. +Greenwave decision requests need the following parameters to identify the +policies to use: + +- decision_context +- product_version +- subject_type + +Greenwave policies need the following parameters: + +- decision_contexts +- product_versions +- subject_type +- rules +- id + +Optionally, policies can define applicable "package" (the name from NVR) +allowlist and blocklist using parameters ``packages`` and +``excluded_packages``. This works only for subject types that support NVR +formatted subject identifiers (``is_nvr`` in :ref:`subject-types` +configuration). + Policies are YAML files, loaded from the directory given by the ``POLICIES_DIR`` configuration setting (by default, :file:`/etc/greenwave/policies`). @@ -138,7 +164,11 @@ Subject types Greenwave can make decisions about any type of software artefacts, the value of this field just needs to be a string. -But these are common examples of types (just for reference): +The subject types can be configured in server (``SUBJECT_TYPES_DIR`` points to +the directory with the configuration YAML files). This customization can be +listed via API :http:get:`/api/v1.0/subject_types`. + +These are common examples of types: ``koji_build`` A build stored in the `Koji`_ build system. Builds are identified by their @@ -171,39 +201,39 @@ Rule types PassingTestCaseRule ------------------- - For this rule to be satisfied, there must be a result in ResultsDB for the - given ``test_case_name`` with an outcome of ``PASSED`` or ``INFO``, *or* - there must be a corresponding waiver in WaiverDB for the given test case. +For this rule to be satisfied, there must be a result in ResultsDB for the +given ``test_case_name`` with an outcome of ``PASSED`` or ``INFO``, *or* +there must be a corresponding waiver in WaiverDB for the given test case. - The rule requires all matching latest test results with distinct triplets - ``system_architecture``, ``system_variant`` and ``scenario`` (which are - defined in result data) to pass or be waived. +The rule requires all matching latest test results with distinct triplets +``system_architecture``, ``system_variant`` and ``scenario`` (which are +defined in result data) to pass or be waived. - Optional ``scenario`` property can be specified to consider only results - with a given scenario name. +Optional ``scenario`` property can be specified to consider only results +with a given scenario name. - Optional ``valid_since`` and ``valid_until`` properties declare a date/time - range for which the rule is applicable. The range is compared to subject's - build time from Koji if available or the current date/time. The default - value is ``null`` for both, indicating that the rule is always valid. The - comparison logic is following:: +Optional ``valid_since`` and ``valid_until`` properties declare a date/time +range for which the rule is applicable. The range is compared to subject's +build time from Koji if available or the current date/time. The default +value is ``null`` for both, indicating that the rule is always valid. The +comparison logic is following:: - if valid_since != null and subject_time < valid_since then - rule is not applicable - else if valid_until != null and subject_time >= valid_until then - rule is not applicable - else - rule is applicable + if valid_since != null and subject_time < valid_since then + rule is not applicable + else if valid_until != null and subject_time >= valid_until then + rule is not applicable + else + rule is applicable - Removing the rule is equivalent to setting ``valid_until`` to the current - date/time. This is preferable since it won't affect previous decisions. - Similarly, adding new rule with ``valid_since`` set to the current or a - future date/time does not affect previous decisions. +Removing the rule is equivalent to setting ``valid_until`` to the current +date/time. This is preferable since it won't affect previous decisions. +Similarly, adding new rule with ``valid_since`` set to the current or a +future date/time does not affect previous decisions. - In the following example, on ``2021-10-02`` (if not specified, the time - defaults to 00:00 UTC), compose test results for test case - ``compose.autocloud`` start requiring scenario ``x86_64.uefi`` instead of - ``x86_64.64bit``. +In the following example, on ``2021-10-02`` (if not specified, the time +defaults to 00:00 UTC), compose test results for test case +``compose.autocloud`` start requiring scenario ``x86_64.uefi`` instead of +``x86_64.64bit``. .. code-block:: yaml :linenos: @@ -229,36 +259,42 @@ PassingTestCaseRule RemoteRule ---------- - See the :ref:`remoterule-configure-additional-policies` section below for - some information about how RemoteRule works and how to configure it. +See the :ref:`remoterule-configure-additional-policies` section below for +some information about how RemoteRule works and how to configure it. Testing your policy changes =========================== -If you're writing a new policy, you can use the Greenwave dev server to try it -out and experiment with how if affects Greenwave's decisions. - -First, follow the steps in the :doc:`dev-guide` to get the dev server running -locally. - -Then, add your new or modified policy in the :file:`conf/policies/` directory -of your source tree. Note that Greenwave currently loads policies once at -startup, it doesn't reload them at runtime. Therefore you should restart the -dev server whenever you make a change to the policies. - -Now, you can use :program:`curl` or your favourite HTTP client to ask -Greenwave for a decision: +Before requesting a new policy, you can verify the rules for the policy by +passing ``rules`` to API :http:post:`/api/v1.0/decision` instead of the +``decision_context`` attribute. .. code-block:: bash - curl http://localhost:5005/api/v1.0/decision \ - --header 'Content-Type: application/json' \ - --data '{"product_version": "fedora-27", - "decision_context": "bodhi_update_push_stable", - "subject": [{"item": "akonadi-calendar-tools-17.12.1-1.fc27", - "type": "koji_build"}]}' - + curl https://greenwave.fedoraproject.org/api/v1.0/decision \ + --json '{ + "product_version": "fedora-27", + "subject_identifier": "akonadi-calendar-tools-17.12.1-1.fc27", + "subject_type": "koji_build", + "rules": [ + {"type": "PassingTestCaseRule", "test_case_name": "example1.test.case.name"}, + {"type": "PassingTestCaseRule", "test_case_name": "example2.test.case.name"}, + { + "type": "RemoteRule", + "source": "https://gitlab.example.com/ci/policies/-/raw/master/{subject_id}.yml" + } + ]}' + + +Updating existing policies +========================== + +Modifying rules in policies would normally break previous gating decisions. To +avoid this, use ``valid_since`` when adding new rules and ``valid_until`` +instead of removing rules. + +For details, see: :ref:`PassingTestCaseRule` .. _remoterule-configure-additional-policies: