Dedicated page per requirement

docs/modules/ROOT/pages/reference/quality-requirements.adoc

@@ -1,4 +1,12 @@
 = AppCatalog Quality Requirements
 
-These pages contain the formal quality requirements that each of the AppCatalog services should fulfill.
+These pages contain the formal quality requirements that apply to the AppCatalog framework.
 They are general descriptions, for specific services please see the service specification.
+
+////
+Note for future "best practices"
+- We should lower the operational load by using good Kubernetes health checks
+- In a shared cloud environment, it is crucial to secure the services, so no other people have access to it (TLS + auth)
+- Provide connection details Secret in the app namespace
+- Service API shall not use plaintext secrets (use Secret reference instead)
+////

docs/modules/ROOT/pages/reference/quality-requirements/maintainability/readiness-standards.adoc

@@ -0,0 +1,32 @@
+= Service Production Readiness Standards
+
+Source::
+Application Catalog Product Owner
+
+Stimulus::
+Approve service production readiness (new and changing services)
+
+Environment::
+AppCatalog enabled Kubernetes cluster
+
+Artifact::
+// Placeholder for now. Future "Service Hub" docs?
+https://kb.vshn.ch/app-catalog[AppCatalog Documentation]
+
+Response::
+Documentation and specification of all services adhere to a common standard.
+
+Response measure::
+Each service documentation contains at least the following content:
+- Metrics and alerts
+- SLIs
+- Runbooks
+- Tutorials (Getting started)
+- How-to guides
+- Backup and restore reference
+- API reference
+- Operational constraints
+
+Rationale::
+Each service must adhere to a checklist for production readiness.
+The documentation shall be consistent across all services.

docs/modules/ROOT/pages/reference/quality-requirements/portability/backup-exports.adoc

@@ -0,0 +1,23 @@
+= Backups Can Be Exported
+
+Source::
+Service engineer
+
+Stimulus::
+Export an existing backup
+
+Environment::
+AppCatalog enabled Kubernetes cluster
+
+Artifact::
+K8up and restic
+
+Response::
+The backup is in a format that can be exported.
+
+Response measure::
+The backup data can be inspected and used to fully restore a service instance outside of AppCat with conventional tools.
+
+Rationale::
+Vendor lock-in users into the service instances or AppCat framework must be avoided.
+The users should be able to take their data away before canceling their service instances.

docs/modules/ROOT/pages/reference/quality-requirements/portability/provisioning.adoc

@@ -0,0 +1,24 @@
+= Common Interface to Provision Services
+
+Source::
+User
+
+Stimulus::
+Creates an AppCatalog Service
+
+Environment::
+AppCatalog enabled Kubernetes cluster
+
+Artifact::
+`kubectl` or equivalent tool
+
+Response::
+The services are provisioned the same way for any cluster.
+
+Response measure::
+The usage for provisioning services is transparent for any underlying Kubernetes distribution.
+The same API calls and CRs can be used to provision AppCatalog services.
+
+Rationale::
+`kubectl` and equivalent tools shall provide the common means for interacting with the AppCatalog framework.
+In general it doesn't matter where the platform is running on, although there may be cloud provider specific APIs.

docs/modules/ROOT/pages/reference/quality-requirements/reliability/automatic-updates.adoc

@@ -0,0 +1,24 @@
+= Automatic Updates
+
+Source::
+User
+
+Stimulus::
+Uses an AppCatalog Service
+
+Environment::
+AppCatalog enabled Kubernetes cluster
+
+Artifact::
+Crossplane and Helm
+
+Response::
+Approved updates are rolled out to running services automatically in the next maintenance window.
+
+Response measure::
+Affected services are up-to-date with the approved version after the user-provided maintenance window.
+
+Rationale::
+- Up-to-date services generally contain bugfixes and security patches that improve the service's reliability.
+  It is in the interest of service engineers and users that they stay secure.
+- Users shall have the option to choose the maintenance window.

docs/modules/ROOT/pages/reference/quality-requirements/reliability/backup-interval.adoc

@@ -0,0 +1,23 @@
+= Minimum Backup Interval
+
+Source::
+Service engineer
+
+Stimulus::
+Inspect backups
+
+Environment::
+AppCatalog enabled Kubernetes cluster
+
+Artifact::
+Backup tool
+
+Response::
+List of available backups.
+
+Response measure::
+Consecutive backups don't exceed the 24h interval.
+
+Rationale::
+At least one backup per day is the accepted norm for backups.
+Services may define shorter intervals.

docs/modules/ROOT/pages/reference/quality-requirements/reliability/mandatory-updates.adoc

@@ -0,0 +1,28 @@
+= Mandatory Updates
+
+Source::
+Service engineer
+
+Stimulus::
+Desire to roll out mandatory updates to all service instances.
+
+Environment::
+AppCatalog enabled Kubernetes cluster
+
+Artifact::
+tbd
+
+Response::
+Mandatory updates are rolled out immediately.
+
+Response measure::
+Affected services are up-to-date with the mandatory update.
+
+Rationale::
+Service engineers need to be able to roll out mandatory updates to all instances, regardless of their configured maintenance window.
+This allows for special kinds of updates, such as critical security patches.
+
+[NOTE]
+====
+Ideally mandatory updates are announced beforehand.
+====

docs/modules/ROOT/pages/reference/quality-functional.adoc → docs/modules/ROOT/pages/reference/quality-requirements/usability/actionable-alerts.adoc

@@ -1,18 +1,16 @@
-= Functional Suitability
-
-== Day-2 Operations of a Service Are Well-Defined and Automated as Far as Possible
+= Actionable Alerts
 
 Source::
-Engineer
+Service engineer
 
 Stimulus::
-Resolve an open alert from a given AppCatalog Service instance
+Resolve an open alert from a given AppCatalog Service instance.
 
 Environment::
 Monitoring and Alerting
 
 Artifact::
-Alerting software
+AlertManager
 
 Response::
 The alert details include a Runbook URL.
@@ -21,4 +19,5 @@ Response measure::
 The Runbook URL links to the service documentation that contains specific recommendations or instructions how to resolve the given alert.
 
 Rationale::
-Each alert should be actionable for the on-call engineer.
+Each alert should be actionable for the service engineer.
+Alert noise and fatigue must be avoided.