From fad27acd778307daba3cb421c39a54f7d2771422 Mon Sep 17 00:00:00 2001 From: Giulia Naponiello Date: Aug 02 2018 09:16:23 +0000 Subject: Tutorial - How to configure RemoteRule It seems like there is still some confusion on how to configure the Greenwave RemoteRule feature. Maybe this tutorial (that has some extra examples) will help. --- diff --git a/docs/package-specific-policies.rst b/docs/package-specific-policies.rst index ed97c72..ce3813e 100644 --- a/docs/package-specific-policies.rst +++ b/docs/package-specific-policies.rst @@ -51,3 +51,97 @@ To skip this problem, it is possible to submit a waiver with the tool `waiverdb-cli `_. This waiver must have ``testcase`` equal to ``invalid-gating-yaml``. It is not necessary to have a result in Resultsdb for this testcase. + +The side effect is that all the policies defined in the gating.yaml +file will be completely ignored by Greenwave. + + +.. _tutorial-configure-remoterule: + +Tutorial - How to configure the RemoteRule +------------------------------------------ + +If you want to add some additional policies, you can follow this +tutorial. + +We need to write the gating.yaml file. The one for this example will +be this one: + +:: + + --- !Policy + product_versions: + - fedora-28 + decision_context: bodhi_update_push_stable + rules: + - !PassingTestCaseRule {test_case_name: dist.depcheck} + +the decision_context it is not really important at the very moment. + +*NB*. It is not possible to insert a RemoteRule inside a gating.yaml file. +This will provoke an error. + +You need now to push the new file (or the changes) in your dist-git +repo. Once this is done you can build it (in the directory with the +source code of your project): + +:: + + fedpkg build + +Now you can find in the link of the build in Koji the nvr of the build. +Example: ``python-ansi2html-1.1.1-114.fc28`` + +In case of a misconfigured gating.yaml you would need to repeate the +build. To avoid this it is possible to validate the gating.yaml file +before starting the build. +To do that you can use this command (in this example we are using the +Fedora Greenwave instance in production): + +:: + + curl --data-binary "@gating.yaml" -X POST \ + https://greenwave.fedoraproject.org/api/v1.0/validate-gating-yaml + +Greenwave will reply point to the error if there is one. + +To check if the remote policies are loaded correctly, we can call the +Greenwave decision API. Those are the data for the request, we can save +them in a ``data.json`` file: + +:: + + { + "decision_context": "bodhi_update_push_stable", + "product_version": "fedora-28", + "subject_type": "koji_build", + "subject_identifier": "python-ansi2html-1.1.1-114.fc28", + "verbose": true + } + +The ``subject_identifier`` needs to be the same value of the nvr that +we obtained from the Koji build. ``decision_context``, +``product_version`` and ``subject_type`` must match a policy that has +the ``RemoteRule``. You can verify that looking at the +``/api/v1.0/policies`` endpoint. +Example: https://greenwave.fedoraproject.org/api/v1.0/policies + +To call the API we can now use this command (in this example we are +using the Fedora Greenwave instance in production): + +:: + + curl -d "@data.json" -H "Content-Type: application/json" -X POST \ + https://greenwave.fedoraproject.org/api/v1.0/decision + +Since we shouldn't have a result in ResultsDB with testcase +`dist.depcheck``, Greenwave should reply with a negative response, in +particular we should see that some requirements are unsatisfied. +Once you create a result in ResultsDB for that testcase (with +``outcome`` equal to ``PASSED``), you will see that the Greenwave +decision will change and all the requirements will be satisfied (if +everything was configured in the correct way). + +If your gating.yaml file will be misconfigured, Greenwave will reply +that the gating.yaml file is wrong. If you just want to skip this check +without build again, just look at the previous section in this page. diff --git a/docs/policies.rst b/docs/policies.rst index dbfd76a..d148e54 100644 --- a/docs/policies.rst +++ b/docs/policies.rst @@ -217,6 +217,27 @@ This rule allows the packager to configure some additional policies in a :file:`gating.yaml` file configured in the repo. To "activate" this feature is necessary to configure a policy among the others policies configured in the default directory. + +If you want to add a policy for the Fedora Greenwave, you need to change +this file committing and pushing a change with the new policy: +https://infrastructure.fedoraproject.org/cgit/ansible.git/tree/roles/openshift-apps/greenwave/templates/configmap.yml + +Then you need to login to batcave and run the ansible repo to apply the +changes: + +:: + + sudo rbac-playbook openshift-apps/greenwave.yml + +If you have permission problems ask in the IRC freenode channel +#fedora-apps. + +You can: + +* add a rule to an existing Policy +* add a Policy + + Here's an example of a RemoteRule: .. code-block:: console @@ -232,17 +253,20 @@ Here's an example of a RemoteRule: - !RemoteRule {} -It is also required to configure ``KOJI_BASE_URL``, ``DIST_GIT_BASE_URL`` -and ``DIST_GIT_URL_TEMPLATE`` in the configuration settings. +Once the code is pushed, Greenwave will start to check if there is a +gating.yaml file in your dist-git repo. If you didn't configure any +gating.yaml file nothing will change. -Examples: +Greenwave will check if a gating.yaml exists, if it does, it pulls it +down, loads it, and uses it to additionally evaluate the subject of the +decision. + +Greenwave requires these configuration parameters ``KOJI_BASE_URL``, +``DIST_GIT_BASE_URL`` and ``DIST_GIT_URL_TEMPLATE``. Here's the default +for the Fedora instance: .. code-block:: console DIST_GIT_BASE_URL = 'https://src.fedoraproject.org/' DIST_GIT_URL_TEMPLATE = '{DIST_GIT_BASE_URL}{pkg_namespace}/{pkg_name}/raw/{rev}/f/gating.yaml' KOJI_BASE_URL = 'https://koji.fedoraproject.org/kojihub' - -Greenwave checks if a gating.yaml file exists in the specified repo, and, if it -does, it pulls it down, loads it, and uses it to additionally evaluate the -subject of the decision.