diff --git a/sidebarsStandards.js b/sidebarsStandards.js index d645de2bcc..27ec888089 100644 --- a/sidebarsStandards.js +++ b/sidebarsStandards.js @@ -18,6 +18,11 @@ const sidebars = { id: 'certification/scopes-versions' }, items: require('./sidebarsCertificationItems.js') // this file will be generated entirely by `populateCerts.js` via npm post-install hook found in the package.json + }, + { + type: 'doc', + label: 'Compliance Check Pipeline', + id: 'certification/pipeline' } ] }, diff --git a/standards/certification/pipeline.md b/standards/certification/pipeline.md new file mode 100644 index 0000000000..278dd36d1c --- /dev/null +++ b/standards/certification/pipeline.md @@ -0,0 +1,218 @@ +# SCS Compliance Check Pipeline Manual + +The SCS compliance check suite runs automated tests, generates a signed report for the run, and feeds it to +the compliance monitor. Roughly speaking, this process has to be performed daily, for instance, using a +continuous-integration "pipeline". + +Providers of public clouds do not need to use their own pipelines; those clouds can be tested via the +official SCS compliance check pipeline. + +Alternatively, if using this pipeline is not feasible (for instance, for private clouds) or not desired, +cloud-service providers can run the tests and feed the compliance monitor themselves. + +The next subsection shows common requirements for each of these two cases. The two subsections after that +are each dedicated to the specific cases. + +## Common requirements for the compliance checks + +### for SCS-compatible IaaS + +You need an OpenStack project that allows for at least one server and one router, possibly more if it's going +to be used for purposes other than compliance testing (such as the +[OpenStack Health Monitor](https://github.com/SovereignCloudStack/openstack-health-monitor) or the +[SCS Health Monitor](https://github.com/SovereignCloudStack/scs-health-monitor)). + +1. Create an application credential. It must be possible to create resources such as servers, routers, etc. + +2. Create a new branch in [the standards repository](https://github.com/SovereignCloudStack/standards): + + - `git clone git@github.com:SovereignCloudStack/standards.git` + - `cd standards` + - `git checkout -b feat/add_my_cloud` + +3. Add your subject to the results table. This is necessary so your subject shows up in the + [compliance monitor web-site](https://compliance.sovereignit.cloud/page/table). Add the following lines + (substituting all-caps parts): + + ```diff + | [gx-scs](https://github.com/SovereignCloudStack/docs/blob/main/community/cloud-resources/plusserver-gx-scs.md) | Dev environment provided for SCS & GAIA-X context | plusserver GmbH | + {#- #} [{{ results | pick('gx-scs', iaas) | summary }}]({{ detail_url('gx-scs', iaas) }}) {# -#} + | [HM](https://health.gx-scs.sovereignit.cloud:3000/) | + +| [SUBJECT_NAME](YOUR_URL) | DESCRIPTION | COMPANY_NAME | + +{#- #} [{{ results | pick('SUBJECT_NAME', iaas) | summary }}]({{ detail_url('SUBJECT_NAME', iaas) }}) {# -#} + +| [HM](HEALTH_MONITOR_URL) | + ``` + + Ideally, insert the lines at a position that keeps the part of the table below `gx-scs` sorted. + +Now you can proceed with the steps from one of the next subsections, depending on whether you want to +check suite run by the SCS pipeline or not. + +## How to add a new test subject to the official pipeline + +### for SCS-compatible IaaS + +We are going to create a pull request that is very similar to real-life example that +[adds the test subject `scaleup-occ2`](https://github.com/SovereignCloudStack/standards/pull/797). +(However, note that this example also adds an optional GitHub workflow, which we won't do here.) + +1. Modify [playbooks/clouds.yaml.j2](https://github.com/SovereignCloudStack/standards/blob/main/playbooks/clouds.yaml.j2). + This is necessary so that the tests can access your cloud. + You can use the following template (replace all-caps parts): + + ```yaml + SUBJECT_NAME: + region_name: REGION + interface: "public" + identity_api_version: 3 + auth_type: "v3applicationcredential" + auth: + auth_url: AUTH_URL + application_credential_id: "{{ clouds_conf.SUBJECT_NAME_ac_id }}" + application_credential_secret: "{{ clouds_conf.SUBJECT_NAME_a_ac_secret }}" + ``` + + Note that you need to replace dashes (and other special characters) by underscores in the last two lines. + +2. Add your subject to [Tests/config.toml](https://github.com/SovereignCloudStack/standards/blob/main/Tests/config.toml). + This is necessary so that your cloud will be included in the nightly tests. Add a line like so: + + ```diff + [presets.all] + scopes = [ + "scs-compatible-iaas", + ] + subjects = [ + "gx-scs", + + "SUBJECT_NAME", + ``` + + Ideally, insert your subject so that the list (after `gx-scs`) remains sorted. + +3. Add your subject to [compliance-monitor/bootstrap.yaml](https://github.com/SovereignCloudStack/standards/blob/main/compliance-monitor/bootstrap.yaml). + This is necessary to that the reports will be accepted as genuine. Add a section like so: + + ```diff + - subject: artcodix + delegates: + - zuul_ci + + - subject: SUBJECT_NAME + + delegates: + + - zuul_ci + ``` + + Again, insert your subject so that the list (after `gx-scs`) remains sorted. + +4. Finally, add secrets to [.zuul.d/secure.yaml](https://github.com/SovereignCloudStack/standards/blob/main/.zuul.d/secure.yaml). + This is necessary so the tests can access your cloud. + + This step is the most involved, and you can always have us do it for you; in that case, please send us + the application credential id and secret via an encrypted channel, e.g. Matrix. + + To proceed, you need `zuul-client` installed: + + ```shell + pipx install zuul-client + ``` + + Then you can execute: + + ```shell + $ zuul-client --zuul-url https://zuul.sovereignit.cloud/ encrypt --tenant scs --project SovereignCloudStack/standards + + + + ... + - secret: + name: + data: + : !encrypted/pkcs1-oaep + - ... + + $ zuul-client --zuul-url https://zuul.sovereignit.cloud/ encrypt --tenant scs --project SovereignCloudStack/standards + + + + ... + - secret: + name: + data: + : !encrypted/pkcs1-oaep + - ... + ``` + + Copy the parts of the respective outputs starting in the final line shown here (the one starting `-`). + Insert them like so: + + ```diff + + SUBJECT_NAME_ac_id: !encrypted/pkcs1-oaep + + - ENCRYPTED_ID + + SUBJECT_NAME_ac_secret: !encrypted/pkcs1-oaep + + - ENCRYPTED_SECRET + ``` + + Note that you have to use the same keys as in Step 3 (that is, with special characters replaced). + +5. Commit your changes and open a pull request: + + ```shell + git commit -asm "Add SUBJECT_NAME" + git push # the output of this command will show you the URL for creating the pull request + ``` + +## How to feed the compliance monitor yourself + +Note: you may have to adapt these instructions to your infrastructure. For instance, the secrets +we create here are stored locally. If you want to include the check suite into your own +continuous-integration pipeline, you may want to use some dedicated credential store and mechanism for +injecting secrets. You may want to take inspiration from our own Zuul setup by looking at +[.zuul.d](https://github.com/SovereignCloudStack/standards/tree/main/.zuul.d) and +[playbooks](https://github.com/SovereignCloudStack/standards/tree/main/playbooks). + +1. Install requirements. + + ```shell + virtualenv .venv + . .venv/bin/activate + pip install -r requirements.txt + pip install passlib argon2_cffi # these are only needed for step 2 + ``` + +2. Run our support script (substitute `$SUBJECT_NAME` appropriately): + + ```shell + Tests/add_subject.py $SUBJECT_NAME + ``` + + Follow the instructions. + At the end, it will tell you to amend the file `compliance-monitor/boostrap.py`. Do so. + +3. Make sure you have `$SUBJECT_NAME` in your `.config/openstack/clouds.yaml` like so: + + ```yaml + SUBJECT_NAME: + region_name: REGION + interface: "public" + identity_api_version: 3 + auth_type: "v3applicationcredential" + auth: + auth_url: AUTH_URL + application_credential_id: "APPLICATION_CREDENTIAL_ID" + application_credential_secret: "APPLICATION_CREDENTIAL_SECRET" + ``` + +4. Perform a test run of the check suite like so: + + ```shell + python3 Tests/scs-test-runner.py --config Tests/config.toml run --scope scs-compatible-iaas --subject $SUBJECT_NAME + ``` + + If the report can't be submitted at the very end, this is to be expected, because the keyfile is not yet + known to the compliance monitor. To change this, we proceed to the next step. + +5. Commit your changes and open a pull request: + + ```shell + git commit -asm "Add SUBJECT_NAME" + git push # the output of this command will show you the URL for creating the pull request + ```