Stephan Lo
f797af114b
Configure markdownlint with rules aligned to technical documentation standards and Docsy theme conventions. Design Decisions: - Enable core quality rules (heading hierarchy, consistent list styles) - Allow inline HTML for Docsy shortcodes and components - Permit bare URLs (common in technical documentation) - Make code block language hints optional (pragmatic for existing content) - Set maximum 2 consecutive blank lines (balanced readability) - Enforce single trailing newline (POSIX standard) - Use asterisk for unordered lists (consistency) - Allow 2-space list indentation (Markdown standard) Auto-fixed Issues: - Converted dash lists to asterisk lists (568 fixes) - Removed trailing spaces (211 fixes) - Added missing trailing newlines (74 fixes) - Added blank lines around lists and headings (100+ fixes) Remaining Style Warnings (intentionally accepted): - MD029: List numbering variations in meeting notes (75 instances) - MD036: Bold text for section headers in ADRs (13 instances) - MD025: Multiple H1 in notes/brainstorming docs (10 instances) - MD032/MD022: Minor spacing variations (15 instances) Test Results: ✅ Hugo build: 227 pages generated successfully ✅ HTML validation: No errors ✅ Link checking: All links valid (except dev-only livereload) ✅ Markdown linting: Only non-critical style warnings remain The configuration balances strict quality checks with pragmatic flexibility for diverse content types (documentation, ADRs, meeting notes, tutorials).
2.8 KiB
| title | weigth | description |
|---|---|---|
| Validation and Verification | 100 | How does CNOE ensure equality between actual and desired state |
Definition
The CNOE docs do somewhat interchange validation and verification but for the most part they adhere to the general definition:
Validation is used when you check your approach before actually executing an action.
Examples:
- Form validation before processing the data
- Compiler checking syntax
- Rust's borrow checker
Verification describes testing if your 'thing' complies with your spec
Examples:
- Unit tests
- Testing availability (ping, curl health check)
- Checking a ZKP of some computation
In CNOE
It seems that both validation and verification within the CNOE framework are not actually handled by some explicit component but should be addressed throughout the system and workflows.
As stated in the docs, validation takes place in all parts of the stack by enforcing strict API usage and policies (signing, mitigations, security scans etc, see usage of kyverno for example), and using code generation (proven code), linting, formatting, LSP. Consequently, validation of source code, templates, etc is more a best practice rather than a hard fact or feature and it is up to the user to incorporate them into their workflows and pipelines. This is probably due to the complexity of the entire stack and the individual properties of each component and applications.
Verification of artifacts and deployments actually exists in a somewhat similar state. The current CNOE reference-implementation does not provide sufficient verification tooling.
However, as stated in the docs
within the framework cnoe-cli is capable of extremely limited verification of
artifacts within kubernetes. The same verification is also available as a step
within a backstage
plugin. This is pretty
much just a wrapper of the cli tool. The tool consumes CRD-like structures
defining the state of pods and CRDs and checks for their existence within a
live cluster (example).
Depending on the aspiration of 'verification' this check is rather superficial and might only suffice as an initial smoke test. Furthermore, it seems like the feature is not actually used within the CNOE stacks repo.
For a live product more in depth verification tools and schemes are necessary to verify the correct configuration and authenticity of workloads, which is, in the context of traditional cloud systems, only achievable to a limited degree.
Existing tools within the stack, e.g. Argo, provide some verification capabilities. But further investigation into the general topic is necessary.