Sovereign Cloud Standards
Introduction
The Sovereign Cloud Stack (SCS) provides standards for a range of cloud infrastructure types. It strives for interoperable and sovereign cloud stacks which can be deployed and used by a wide range of organizations and individuals. Wherever feasible, transparency and openness both in respect to the inner workings of the platforms standardised by SCS, as well as the SCS organisation itself are a paradigm we intend to live.
Requirements
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
In addition, "FORBIDDEN" is to be interpreted equivalent to "MUST NOT".
Sovereign Cloud Standard documents
One of the main products of the SCS organisation are Sovereign Cloud Standard documents.
Types of documents
Procedural
A procedural SCS document describes a process, a policy or a guideline to which the SCS community adheres.
Standard
A standard SCS document describes a technical standard for SCS compliant clouds. Note that it may not be necessary for all clouds to implement all standards.
Decision Record
Sometimes during the development of the SCS standard, a complex technical decision needs to be taken, which does not directly result in a new standard.
The SCS document format formally integrates
the documentation of such decisions
as documents of type Decision Record.
Supplement
A supplement extends a Standard with additional information, such as implementation and testing notes, that is merely informative, but not authoritative, and that may be subject to change more frequently than the standard itself.
Document format
The SCS documents are provided in GitHub flavored markdown.
Each document is assigned a unique number.
To disambiguate with other organisations using similar schemes
(such as XEPs, PEPs or IETF RFCs),
the numbers are prefixed with SCS-.
To allow a concept to evolve while allowing breaking changes, each SCS document is associated with a major version number. This major version number is a positive number and the numbering starts at one for each document.
In order to make organisation of the SCS documents easier, each document also has a slugified title. The slugified title MUST NOT be changed after the acceptance of the document into the repository, as it is part of its canonical URL. It MUST consist only of lower-case ASCII letters, numbers and hyphens. It MUST NOT start with a hyphen and SHOULD start with a lower-case letter. It SHOULD NOT contain more than one subsequent hyphen.
The file name of an SCS document is formed using the following pattern:
scs-XXXX-vN-T.md, where
XXXX is replaced with the zero-padded document number,
N is replaced with the major version of the document, and
T is replaced with the slugified title.
For a document with the number 190, with a major version number 2 and a slugified title flavor-naming,
the resulting file name would be scs-0190-v2-flavor-naming.md.
Supplements deviate from this pattern in that they employ a w instead of a v in front of the version
number, and each supplement uses the same document number as the main document it is extending.
The second digit in XXXX describes the track where the document belongs:
| Track | Number |
|---|---|
| Global | 0 |
| IaaS | 1 |
| KaaS | 2 |
| IAM | 3 |
| Ops | 4 |
In addition to the number, each document has the following metadata, embedded in the markdown header.
| Field name | Requirement | Description |
|---|---|---|
type | REQUIRED | one of Procedural, Standard, Decision Record, or Supplement |
status | REQUIRED | one of Proposal, Draft, Stable, Deprecated, or Rejected |
track | REQUIRED | one of Global, IaaS, KaaS, IAM, Ops |
supplements | REQUIRED precisely when type is Supplement | list of documents that are extended by this document (e.g., multiple major versions) |
deprecated_at | REQUIRED if status is Deprecated | ISO formatted date indicating the date after which the deprecation is in effect |
stabilized_at | REQUIRED if status was ever Stable | ISO formatted date indicating the date after which the document was considered stable |
rejected_at | REQUIRED if status is Rejected | ISO formatted date indicating the date on which the document was rejected |
replaced_by | RECOMMENDED if status is Deprecated or Rejected, FORBIDDEN otherwise | List of documents which replace this document. |
replaces | OPTIONAL | List of documents which this document replaces. |
Sections
Standard
Each Standard document MUST have the following sections:
- An Introduction providing context on the document and linking to other relevant materials.
- A Motivation section which details why this document or the thing it describes is necessary.
- A section containing the actual standardization decision.
- A Conformance Tests section that contains hints on how to validate conformance with this spec, ideally links to conformance test cases.
We also RECOMMEND the following sections:
- A Terminology section which briefly describes terms used in the document, including possible abbreviations.
In addition, the following OPTIONAL sections should be considered:
- A Design Considerations section for Standard type documents, which details other choices which have been considered for the specific feature but were ultimately rejected.
- An Open Questions section which links to issues detailing any open discussion points with respect to a document. This section is RECOMMENDED during the discussion phase (pre 1.0.0) as a "table of contents" of things to work on in that context.
- A Related Documents section which references related Standards or Decisions, both upstream and/or other SCS documents.
Decision Record
Each Decision Record document MUST have the following sections:
- An Abstract providing a brief introduction on the topic of the document.
- A Context section describing the issue relevant for motivating this Decision Record.
- A section containing the actual decision that is introduced. The section should also include reasoning for this decision.
We also RECOMMEND the following sections:
- A Terminology section which shortly describes terms used in the document, including possible abbreviations.
- A Related Documents section which references related Standards or Decisions, both upstream and/or other SCS documents.
In addition, the following OPTIONAL sections should be considered:
- A Consequences section describing outcomes from implementing the changes described.
Process
The lifecycle of an SCS document goes through the following phases: Proposal, Draft, Stable, Deprecated, and Rejected.
All decisions for phase transitions follow loose consensus,
where the group which has to form the consensus depends on the track of the document:
- IaaS: The team working on infrastructure-as-a-service topics
- KaaS: The team working on Kubernetes-as-a-service topics
- Ops: The team working on operations topics
- IAM: The team working on identity and access management topics
- Global: The entire SCS community
Supplements may be kept in Draft state, because they are not authoritative.
Proposal phase
Proposal of a new document
To propose a new SCS document, a community participant creates a pull request on GitHub against the standards repository in the SovereignCloudStack organisation.
The pull request MUST add exactly one SCS document,
in the Standards folder.
In the proposal phase,
the document number MUST be replaced with xxxx in the file name,
except for a Supplement, which uses the document number of the document it refers to.
The major version MUST be 1.
For a document with a slugified title flavor-naming,
the file name would for instance be scs-xxxx-v1-flavor-naming.md;
for a Supplement of scs-0100-v3-flavor-naming.md,
the file name might be scs-0100-w1-flavor-naming-implementation-testing.md (note the w1!).
The metadata MUST indicate the intended track and type of the document,
and the status MUST be set to Proposal;
for a Supplement, the supplements field MUST be set
to a list of documents (usually containing one element).
Upon acceptance by the group of people identified by the track,
a number is assigned
(the next unused number)
and the proposer is asked
to rename the file to replace the xxxx with that number.
Note:
Documents on the Design Record track MAY be proposed or accepted directly into Stable state,
if no further discussion is required.
Hereafter,
the pull request can be merged
and henceforth the document is an official SCS document in Draft state.
Proposal of a major update to a stable document
To propose major update to a Stable SCS document, a community participant creates a pull request on GitHub against the standards repository in the SovereignCloudStack organisation.
The pull request MUST add exactly one SCS document,
in the Standards folder.
The document number MUST be the same as the document it is updating,
and the major version number MUST be incremented by 1.
The slugified title MAY be changed.
It MUST refer to the old document in its replaces metadata.
The pull request SHOULD NOT modify the previous document;
deprecation of the previous document
as well as adding the replaced_by metadata is a separate step,
and can only be executed once the new document is Stable.
For a document updating a hypothetical SCS-0390-v3 document,
the file name may be scs-0390-v4-flavor-naming-this-time-its-serious.md.
Other than the file naming difference,
the proposal process is the same as for new documents.
In particular, the new document starts out in Draft state
and does not automatically become part of the normative corpus of an SCS release.
Development phase (Draft)
In this phase, the document is developed inside the SCS community.
It should not be considered to be normative for any SCS release, even if an SCS release happens after the acceptance of the document.
Experimental and exploratory implementations are encouraged, however, implementors must be prepared for breaking changes.
Changes to the documents are gated through pull requests.
Stabilized phase (Stable)
Once the document is deemed ready for production use,
its status is changed to Stable.
If the document in question is a Standard
(and if applicable),
the following conditions MUST all be satisfied before stabilizing:
- the corresponding conformance tests have been implemented according to the general guidelines,
- they have been shown to work with the reference implementation,
- they are documented in the standard or one of its
Supplementdocuments.
After stabilization, changes to the document which may render existing implementations non-conformant MUST NOT be made.
If a breaking change to an existing SCS document is deemed necessary, a new document with a new number shall be created and the old document SHOULD be deprecated.
Deprecation phase (Deprecated)
Should a document become obsolete, it can be deprecated.
Obsoletions SHOULD be announced ahead of their execution by setting the
deprecated_at field to a future date and moving the status to Deprecated.
This signals current and future implementors
that the subject matter of the document
is not considered necessary or state of the art anymore.
If one or more replacement documents for the document exists,
it MUST be listed in the replaced_by metadata field.
Rejection
If a document is removed from the normative corpus of SCS standards,
its status is changed to Rejected.
If one or more replacement documents for the document exists,
it MUST be listed in the replaced_by metadata field.
Open Questions
Stabilization criteria
When should a document be stabilized? Should we require at least one public implementation? Should we require a minimum experimental time? What about non-Standard track documents?
Breaking change criteria
When is a change breaking and cannot be applied to a Stable document? What about previously undefined behaviour (uncovered edge case)? What about ambiguous wording? Do we need a separate "Errata" section?
Design Considerations
Versioning
An alternative to the proposed scheme for stabilization is the use of SemVer-like versioning.
In that case, one would have an individual version number with each document,
where a major version greater than zero indicates a stable document.
The Stable state would be merged with Draft state into an Active state
and shared between the stabilized and the development phase.
The advantages of such an approach are:
- It is easy to recognize whether an SCS document has changed between two SCS releases, just by looking at the released version number.
- It is possible to make breaking changes after stabilization by increasing the major version number.
The disadvantages of that approach are:
-
It is possible to make breaking changes after stabilization. Potentially, an hypothetical SCS-1234 document might refer to something completely different in a hypothetical R15 release than what it meant in R5, if there have been sufficient, gradual breaking changes to the document.
That means that for proper linking, it would be required to always include the major version number when referring to an SCS document.
This implies having to keep all former versions around in a canonical, linkable form. This induces non-trivial organizational and editorial overhead and raises questions around which changes are acceptable to "archived" versions, if any.
-
It would require a clone of the SemVer spec, as that spec is highly specific toward software and does not fully (at least not in the standard-as-written) cover specifics of a standards organisation's use-cases.
Acknowledgements
This document is heavily inspired by XEP-0001, as published by the XMPP Standards Foundation.