Skip to content

Commit a749e4d

Browse files
mbuechsegarloff
mbuechse
and
garloff
authored
Add rudimentary docs for compliance check pipeline (#272)
Signed-off-by: Matthias Büchse <[email protected]> Co-authored-by: Kurt Garloff <[email protected]>
1 parent bc298f3 commit a749e4d

File tree

2 files changed

+233
-0
lines changed

2 files changed

+233
-0
lines changed

‎sidebarsStandards.js

+5
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,11 @@ const sidebars = {
1818
id: 'certification/scopes-versions'
1919
},
2020
items: require('./sidebarsCertificationItems.js') // this file will be generated entirely by `populateCerts.js` via npm post-install hook found in the package.json
21+
},
22+
{
23+
type: 'doc',
24+
label: 'Compliance Check Pipeline',
25+
id: 'certification/pipeline'
2126
}
2227
]
2328
},

‎standards/certification/pipeline.md

+228
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
# SCS Compliance Check Pipeline Manual
2+
3+
The SCS compliance check suite runs automated tests, generates a signed report for the run, and feeds it to
4+
the compliance monitor. Roughly speaking, this process has to be performed daily, for instance, using a
5+
continuous-integration "pipeline".
6+
7+
Providers of public clouds do not need to use their own pipelines; those clouds can be tested via the
8+
official SCS compliance check pipeline.
9+
10+
Alternatively, if using this pipeline is not feasible (for instance, for private clouds) or not desired,
11+
cloud-service providers can run the tests and feed the compliance monitor themselves.
12+
13+
The next subsection shows common requirements for each of these two cases. The two subsections after that
14+
are each dedicated to the specific cases.
15+
16+
## Common requirements for the compliance checks
17+
18+
### for SCS-compatible IaaS
19+
20+
You need an OpenStack project that allows for at least one server and one router, possibly more if it's going
21+
to be used for purposes other than compliance testing (such as the
22+
[OpenStack Health Monitor](https://github.com/SovereignCloudStack/openstack-health-monitor) or the
23+
[SCS Health Monitor](https://github.com/SovereignCloudStack/scs-health-monitor)).
24+
25+
1. Create an application credential. It must be possible to create resources such as servers, routers, etc.
26+
27+
2. Create a new branch in [the standards repository](https://github.com/SovereignCloudStack/standards):
28+
29+
- `git clone [email protected]:SovereignCloudStack/standards.git`
30+
- `cd standards`
31+
- `git checkout -b feat/add_my_cloud`
32+
33+
**CAUTION**: If you are not a member of the SCS Github org, this won't work.
34+
Ask the SCS team (or other members) to add you. Alternatively, you may fork the repository on
35+
Github first and then clone the fork.
36+
37+
3. Add your subject to the results table. This is necessary so your subject shows up in the
38+
[compliance monitor web-site](https://compliance.sovereignit.cloud/page/table). Add the following lines
39+
(substituting all-caps parts except `HM`):
40+
41+
```diff
42+
| [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 |
43+
{#- #} [{{ results | pick('gx-scs', iaas) | summary }}]({{ detail_url('gx-scs', iaas) }}) {# -#}
44+
| [HM](https://health.gx-scs.sovereignit.cloud:3000/) |
45+
+| [SUBJECT_NAME](YOUR_URL) | DESCRIPTION | COMPANY_NAME |
46+
+{#- #} [{{ results | pick('SUBJECT_NAME', iaas) | summary }}]({{ detail_url('SUBJECT_NAME', iaas) }}) {# -#}
47+
+| [HM](HEALTH_MONITOR_URL) |
48+
```
49+
50+
Ideally, insert the lines at a position that keeps the part of the table below `gx-scs` sorted.
51+
52+
Now you can proceed with the steps from one of the next subsections, depending on whether you want to
53+
check suite run by the SCS pipeline or not.
54+
55+
## How to add a new test subject to the official pipeline
56+
57+
### for SCS-compatible IaaS
58+
59+
We are going to create a pull request that is very similar to real-life example that
60+
[adds the test subject `scaleup-occ2`](https://github.com/SovereignCloudStack/standards/pull/797).
61+
(However, note that this example also adds an optional GitHub workflow, which we won't do here.)
62+
63+
1. Modify [playbooks/clouds.yaml.j2](https://github.com/SovereignCloudStack/standards/blob/main/playbooks/clouds.yaml.j2).
64+
This is necessary so that the tests can access your cloud.
65+
You can use the following template (replace all-caps parts):
66+
67+
```yaml
68+
SUBJECT_NAME:
69+
region_name: REGION
70+
interface: "public"
71+
identity_api_version: 3
72+
auth_type: "v3applicationcredential"
73+
auth:
74+
auth_url: AUTH_URL
75+
application_credential_id: "{{ clouds_conf.SUBJECT_NAME_ac_id }}"
76+
application_credential_secret: "{{ clouds_conf.SUBJECT_NAME_a_ac_secret }}"
77+
```
78+
79+
Note that you need to replace dashes (and other special characters) by underscores in the last two lines.
80+
81+
2. Add your subject to [Tests/config.toml](https://github.com/SovereignCloudStack/standards/blob/main/Tests/config.toml).
82+
This is necessary so that your cloud will be included in the nightly tests. Add a line like so:
83+
84+
```diff
85+
[presets.all]
86+
scopes = [
87+
"scs-compatible-iaas",
88+
]
89+
subjects = [
90+
"gx-scs",
91+
+ "SUBJECT_NAME",
92+
```
93+
94+
Ideally, insert your subject so that the list (after `gx-scs`) remains sorted.
95+
96+
3. Add your subject to [compliance-monitor/bootstrap.yaml](https://github.com/SovereignCloudStack/standards/blob/main/compliance-monitor/bootstrap.yaml).
97+
This is necessary to that the reports will be accepted as genuine. Add a section like so:
98+
99+
```diff
100+
- subject: artcodix
101+
delegates:
102+
- zuul_ci
103+
+ - subject: SUBJECT_NAME
104+
+ delegates:
105+
+ - zuul_ci
106+
```
107+
108+
Again, insert your subject so that the list (after `gx-scs`) remains sorted.
109+
110+
4. Finally, add secrets to [.zuul.d/secure.yaml](https://github.com/SovereignCloudStack/standards/blob/main/.zuul.d/secure.yaml).
111+
This is necessary so the tests can access your cloud.
112+
113+
This step is the most involved, and you can always have us do it for you; in that case, please send us
114+
the application credential id and secret via an encrypted channel, e.g. Matrix.
115+
116+
To proceed, you need `zuul-client` installed:
117+
118+
```shell
119+
pipx install zuul-client
120+
```
121+
122+
Then you can execute:
123+
124+
```shell
125+
$ zuul-client --zuul-url https://zuul.sovereignit.cloud/ encrypt --tenant scs --project SovereignCloudStack/standards
126+
<PASTE application credential id HERE>
127+
<HIT ctrl-d>
128+
129+
...
130+
- secret:
131+
name: <name>
132+
data:
133+
<fieldname>: !encrypted/pkcs1-oaep
134+
- ...
135+
136+
$ zuul-client --zuul-url https://zuul.sovereignit.cloud/ encrypt --tenant scs --project SovereignCloudStack/standards
137+
<PASTE application credential secret HERE>
138+
<HIT ctrl-d>
139+
140+
...
141+
- secret:
142+
name: <name>
143+
data:
144+
<fieldname>: !encrypted/pkcs1-oaep
145+
- ...
146+
```
147+
148+
Copy the parts of the respective outputs starting in the final line shown here (the one starting `-`).
149+
Insert them like so:
150+
151+
```diff
152+
+ SUBJECT_NAME_ac_id: !encrypted/pkcs1-oaep
153+
+ - ENCRYPTED_ID
154+
+ SUBJECT_NAME_ac_secret: !encrypted/pkcs1-oaep
155+
+ - ENCRYPTED_SECRET
156+
```
157+
158+
Note that you have to use the same keys as in Step 1 (that is, with special characters replaced).
159+
160+
5. Commit your changes and open a pull request:
161+
162+
```shell
163+
git commit -asm "Add SUBJECT_NAME"
164+
git push # the output of this command will show you the URL for creating the pull request
165+
```
166+
167+
## How to feed the compliance monitor yourself
168+
169+
### for SCS-compatible IaaS
170+
171+
Note: you may have to adapt these instructions to your infrastructure. For instance, the secrets
172+
we create here are stored locally. If you want to include the check suite into your own
173+
continuous-integration pipeline, you may want to use some dedicated credential store and mechanism for
174+
injecting secrets.
175+
176+
You may want to take inspiration from our own Zuul setup by looking at
177+
[.zuul.d](https://github.com/SovereignCloudStack/standards/tree/main/.zuul.d) and
178+
[playbooks](https://github.com/SovereignCloudStack/standards/tree/main/playbooks).
179+
However, don't be overwhelmed by the complexities of Zuul; it's well possible to use other solutions,
180+
including a cronjob.
181+
182+
1. Install requirements.
183+
184+
```shell
185+
virtualenv .venv
186+
. .venv/bin/activate
187+
pip install -r requirements.txt
188+
pip install passlib argon2_cffi # these are only needed for Step 2
189+
```
190+
191+
2. Run our support script (substitute `$SUBJECT_NAME` appropriately):
192+
193+
```shell
194+
Tests/add_subject.py $SUBJECT_NAME
195+
```
196+
197+
Follow the instructions.
198+
At the end, it will tell you to amend the file `compliance-monitor/boostrap.py`. Do so.
199+
200+
3. Make sure you have `$SUBJECT_NAME` in your `.config/openstack/clouds.yaml` like so:
201+
202+
```yaml
203+
SUBJECT_NAME:
204+
region_name: REGION
205+
interface: "public"
206+
identity_api_version: 3
207+
auth_type: "v3applicationcredential"
208+
auth:
209+
auth_url: AUTH_URL
210+
application_credential_id: "APPLICATION_CREDENTIAL_ID"
211+
application_credential_secret: "APPLICATION_CREDENTIAL_SECRET"
212+
```
213+
214+
4. Perform a test run of the check suite like so:
215+
216+
```shell
217+
python3 Tests/scs-test-runner.py --config Tests/config.toml run --scope scs-compatible-iaas --subject $SUBJECT_NAME
218+
```
219+
220+
If the report can't be submitted at the very end, this is to be expected, because the keyfile is not yet
221+
known to the compliance monitor. To change this, we proceed to the next step.
222+
223+
5. Commit your changes and open a pull request:
224+
225+
```shell
226+
git commit -asm "Add SUBJECT_NAME"
227+
git push # the output of this command will show you the URL for creating the pull request
228+
```

0 commit comments

Comments
 (0)