Extend implementation notes (#643)

* Extend implementation notes Add and extend some implementation notes derived from the findings of #426. Signed-off-by: Hannes Baum <[email protected]> * Review adjustments Adjustments made possible by the review from @mbuechse. Signed-off-by: Hannes Baum <[email protected]> * Apply suggestions from code review Co-authored-by: Matthias Büchse <[email protected]> Signed-off-by: Martin Morgenstern <[email protected]> * Remove impl note which became redundant after merging main Signed-off-by: Martin Morgenstern <[email protected]> * Remove outdated, wrong file SCS-Spec.Images.yaml Signed-off-by: Matthias Büchse <[email protected]> * Make implementation notes more concrete Signed-off-by: Matthias Büchse <[email protected]> * Update Standards/scs-0210-w1-k8s-version-policy-implementation-testing.md Signed-off-by: Matthias Büchse <[email protected]> * Appease markdown-lint Signed-off-by: Matthias Büchse <[email protected]> --------- Signed-off-by: Hannes Baum <[email protected]> Signed-off-by: Martin Morgenstern <[email protected]> Signed-off-by: Matthias Büchse <[email protected]> Co-authored-by: Martin Morgenstern <[email protected]> Co-authored-by: Matthias Büchse <[email protected]>
SovereignCloudStack · Sep 5, 2024 · a389059 · a389059
1 parent 89f70aa
commit a389059
Show file tree

Hide file tree

Showing 6 changed files with 171 additions and 21 deletions.
diff --git a/Standards/scs-0100-w1-flavor-naming-implementation-testing.md b/Standards/scs-0100-w1-flavor-naming-implementation-testing.md
@@ -15,21 +15,20 @@ The three major versions of the standard that exist so far are very similar, and
 Therefore, the procedures needed to implement or test them are very similar as well. Yet, this document
 will only cover v3, because v1 and v2 are already obsolete by the time of writing.
 
-## Implementation Notes
+## Implementation notes
 
 Every flavor whose name starts with `SCS-` must conform with the naming scheme laid down in the standard.
 
-### Operational Tooling
+### Operational tooling
 
-#### Syntax Check
+#### Syntax check
 
 The [test suite](https://github.com/SovereignCloudStack/standards/tree/main/Tests/iaas/flavor-naming)
 comes with a handy
 [command-line utility](https://github.com/SovereignCloudStack/standards/tree/main/Tests/iaas/flavor-naming/cli.py)
-that can be used to validate flavor names, to
-interactively construct a flavor name via a questionnaire, and to generate prose descriptions for given
-flavor names. See the
-[README](https://github.com/SovereignCloudStack/standards/tree/main/Tests/iaas/flavor-naming/README.md)
+that can be used to validate flavor names, to interactively construct a flavor name
+via a questionnaire, and to generate prose descriptions for given flavor names.
+See the [README](https://github.com/SovereignCloudStack/standards/tree/main/Tests/iaas/flavor-naming/README.md)
 for more details.
 
 The functionality of this script is also (partially) exposed via the web page
@@ -39,12 +38,14 @@ With the OpenStack tooling (`python3-openstackclient`, `OS_CLOUD`) in place, you
 `cli.py -v parse v3 $(openstack flavor list -f value -c Name)` to get a report
 on the syntax compliance of the flavor names of the cloud environment.
 
-#### Flavor Creation
+#### Flavor creation
 
-The [OpenStack Flavor Manager](https://github.com/osism/openstack-flavor-manager) will create a whole set
-of flavors in one go, given a YAML description of this set.
+The [OpenStack Flavor Manager from OSISM](https://github.com/osism/openstack-flavor-manager)
+will create a whole set of flavors in one go.
+To that end, it provides different options: either the standard mandatory and
+possibly recommended flavors can be created, or the user can set a file containing his flavors.
 
-## Automated Tests
+## Automated tests
 
 ### Errors
 
@@ -68,6 +69,6 @@ The script [`flavor-names-openstack.py`](https://github.com/SovereignCloudStack/
 talks to the OpenStack API of the cloud specified by the `OS_CLOUD` environment and queries properties and
 checks the names for standards compliance.
 
-## Manual Tests
+## Manual tests
 
 To be determined.
diff --git a/Standards/scs-0101-w1-entropy-implementation-testing.md b/Standards/scs-0101-w1-entropy-implementation-testing.md
@@ -7,18 +7,20 @@ supplements:
   - scs-0101-v1-entropy.md
 ---
 
-## Implementation
+## Implementation notes
 
-We presume that almost nothing has to be done (or indeed can be done), as
-long as the CPUs and VM images are reasonably recent; only the flavor and
-image attributes have to be set:
+With reasonably recent hardware—x86 CPU with RDRAND/RDSEED (Intel from 2012,
+AMD from 2015) or ARM CPU with FEAT_RNG or FEAT_RNG_TRAP—and recent VM image—Linux
+kernel 5.18 or higher—, there is (almost) nothing to be done.
 
-- flavor: `hw_rng:allowed=True` ,
-- image: `hw_rng_model: virtio` .
+Only the flavor and image attributes required by the standard have to be set:
 
-## Automated Tests
+- flavor extra_spec: `hw_rng:allowed=True` ,
+- image property: `hw_rng_model: virtio` .
 
-### Images Sample
+## Automated tests
+
+### Images sample
 
 Some checks need to be performed on a live instance. For these checks, it is
 necessary to choose a sample of VM images to test on.
@@ -59,6 +61,6 @@ as ensured by the image metadata standard.
 The script [`entropy-check.py`](https://github.com/SovereignCloudStack/standards/blob/main/Tests/iaas/entropy/entropy-check.py)
 connects to OpenStack and performs the checks described in this section.
 
-## Manual Tests
+## Manual tests
 
 None.
diff --git a/Standards/scs-0102-w1-image-metadata-implementation-testing.md b/Standards/scs-0102-w1-image-metadata-implementation-testing.md
@@ -0,0 +1,32 @@
+---
+title: "SCS Image Metadata: Implementation and Testing Notes"
+type: Supplement
+track: IaaS
+status: Proposal
+supplements:
+  - scs-0102-v1-image-metadata.md
+---
+
+
+## Implementation notes
+
+The [OpenStack Image Manager from OSISM](https://github.com/osism/openstack-image-manager)
+will create a set of images from a "spec file" provided by the user, which can also set the required properties
+for these images.
+
+## Automated tests
+
+### Images sample
+
+Some checks need to be performed on a live instance. All publicly available images on this instance
+will be checked for either only the mandatory properties or possibly also the recommended ones.
+Additionally, a user can also decide to test their private images, although this isn't a necessity.
+
+### Implementation
+
+The script [`image-md-check.py`](https://github.com/SovereignCloudStack/standards/blob/main/Tests/iaas/image-metadata/image-md-check.py)
+connects to OpenStack and performs the checks described in this section.
+
+## Manual tests
+
+None.
diff --git a/Standards/scs-0210-w1-k8s-version-policy-implementation-testing.md b/Standards/scs-0210-w1-k8s-version-policy-implementation-testing.md
@@ -0,0 +1,35 @@
+---
+title: "SCS K8S Version Policy: Implementation and Testing Notes"
+type: Supplement
+track: KaaS
+status: Draft
+supplements:
+  - scs-0210-v2-k8s-version-policy.md
+---
+
+## Implementation notes
+
+The standard is quite concise about [the regulations](https://docs.scs.community/standards/scs-0210-v2-k8s-version-policy#decision),
+so they are not restated here. Suffice it to say that a
+CSP must make new versions for their KaaS offering available in a timely fashion, so that
+new versions are available in a short window of time.
+Older versions need to be supported until the end of their support window.
+
+Concrete implementation details can't be given here, since not every CSP does provide
+their versions the same way. The best advice to give is to monitor the
+[Kubernetes releases page](https://kubernetes.io/releases/) closely.
+
+## Automated tests
+
+### Implementation
+
+The script [`k8s_version_policy.py`](https://github.com/SovereignCloudStack/standards/blob/main/Tests/kaas/k8s-version-policy/k8s_version_policy.py)
+connects to an existing K8s cluster and checks the version against a list of versions, that
+are calculated to be inside a recency window.
+
+Note that this implementation is subject to change, because testing an existing cluster is not
+sufficient to guarantee that all active k8s branches are supported and kept up to date.
+
+## Manual tests
+
+None.
diff --git a/Standards/scs-0211-w1-kaas-default-storage-class-implementation-testing.md b/Standards/scs-0211-w1-kaas-default-storage-class-implementation-testing.md
@@ -0,0 +1,39 @@
+---
+title: "SCS KaaS default storage class: Implementation and Testing Notes"
+type: Supplement
+track: KaaS
+status: Proposal
+supplements:
+  - scs-0211-v1-kaas-default-storage-class.md
+---
+
+## Implementation notes
+
+A `StorageClass` is made default by using the `storageclass.kubernetes.io/is-default-class`
+annotation; a standardized name is not given. `ReadWriteOnce` must be supported by the volume,
+and it must be protected against data loss due to hardware failures.
+Therefore, volumes must not be bound to the lifecycle of a Kubernetes node and, at best,
+be backed by some kind of redundant storage.
+Guarantees for latency, bandwidth, IOPS and so on are not given.
+
+The cost-intensive part of this standard would be the hardware failure protection by binding
+the `StorageClass` to redundant, non-lifecycle bound storage, since this would mean that
+storage needs to be provided in a higher capacity to achieve the same usable capacity.
+
+## Automated tests
+
+### Notes
+
+The test for the [SCS Kaas Default storage class](https://github.com/SovereignCloudStack/standards/blob/main/Standards/scs-0211-v1-kaas-default-storage-class.md)
+checks if a default storage class is available and if this storage class can be used
+to create a `PersistentVolume` from a `PersistentVolumeClaim` for a container.
+
+### Implementation
+
+The script [`k8s-default-storage-class-check.py`](https://github.com/SovereignCloudStack/standards/blob/main/Tests/kaas/k8s-default-storage-class/k8s-default-storage-class-check.py)
+connects to an existing K8s cluster and checks for the availability of a default storage class.
+This can also be done via Sonobuoy.
+
+## Manual tests
+
+None.
diff --git a/Standards/scs-0214-w1-k8s-node-distribution-implementation-testing.md b/Standards/scs-0214-w1-k8s-node-distribution-implementation-testing.md
@@ -0,0 +1,41 @@
+---
+title: "Kubernetes Node Distribution and Availability: Implementation and Testing Notes"
+type: Supplement
+track: KaaS
+status: Proposal
+supplements:
+  - scs-0214-v1-k8s-node-distribution.md
+  - scs-0214-v2-k8s-node-distribution.md
+---
+
+## Implementation notes
+
+A Kubernetes clusters control plane must be distributed over multiple physical machines, as well
+as different "failure zones". How these are defined is at the moment up to the CSP.
+Worker nodes can also be distributed over "failure zones", but this isn't a requirement.
+Distribution must be shown through labelling, so that users can access these information.
+
+Node distribution metadata is provided through the usage of the labels
+`topology.kubernetes.io/region`, `topology.kubernetes.io/zone` and
+`topology.scs.community/host-id` respectively.
+
+At the moment, not all labels are set automatically by most K8s cluster utilities, which incurs
+additional setup and maintenance costs.
+
+## Automated tests
+
+### Notes
+
+The test for the [SCS K8s Node Distribution and Availability](https://github.com/SovereignCloudStack/standards/blob/main/Standards/scs-0214-v2-k8s-node-distribution.md)
+checks if control-plane nodes are distributed over different failure zones (distributed into
+physical machines, zones and regions) by observing their labels defined by the standard.
+
+### Implementation
+
+The script [`k8s_node_distribution_check.py`](https://github.com/SovereignCloudStack/standards/blob/main/Tests/kaas/k8s-node-distribution/k8s_node_distribution_check.py)
+connects to an existing K8s cluster and checks if a distribution can be detected with the labels
+set for the nodes of this cluster.
+
+## Manual tests
+
+None.