Add quality requirements for AppCat

Guardfile

@@ -0,0 +1,16 @@
+# run the containter
+# docker run --name antora --rm --publish 35729:35729 --publish 2020:2020 --volume "$(pwd)":/preview/antora -d vshn/antora-preview:2.3.12 --antora=docs --style=vshn
+
+group :documentation do
+    # Rebuild documentation when modifying files
+    guard :shell do
+        watch(/(.*).adoc/) do
+            `docker exec -it antora antora --cache-dir=/preview/public/.cache/antora /preview/playbook.yml`
+        end
+    end
+
+    # Refresh browser when folder with HTML files changes
+    guard :livereload do
+        watch(/(.*).adoc/)
+    end
+end

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

@@ -0,0 +1,12 @@
+= AppCatalog Quality Requirements
+
+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/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-requirements/usability/actionable-alerts.adoc

@@ -0,0 +1,22 @@
+= Actionable Alerts
+
+Source::
+Service engineer
+
+Stimulus::
+Resolve an open alert from a given AppCatalog Service instance.
+
+Environment::
+Monitoring and Alerting
+
+Artifact::
+AlertManager
+
+Response::
+The alert details include a Runbook URL.
+
+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 service engineer.

docs/modules/ROOT/pages/reference/quality-requirements/usability/api-declarative.adoc

@@ -0,0 +1,23 @@
+= Declarative Configuration of Instances
+
+Source::
+User
+
+Stimulus::
+Changes the manifest of an AppCatalog service.
+
+Environment::
+AppCatalog enabled Kubernetes cluster
+
+Artifact::
+`kubectl` or equivalent tool
+
+Response::
+Service instance configuration is changed according to desired state using the supported provisioning methods.
+
+Response measure::
+Observed service instance state is updated in the manifest.
+
+Rationale::
+Service instance provisioning (complete stack) should be as user-friendly as deploying a custom application in Kubernetes with GitOps in mind.
+This gives users a native Kubernetes experience by using `kubectl` and equivalent tools.

docs/modules/ROOT/pages/reference/quality-requirements/usability/api-validation.adoc

@@ -0,0 +1,23 @@
+= Service Instance API Validation
+
+Source::
+User
+
+Stimulus::
+Provision an AppCatalog Service instance with an invalid API spec.
+
+Environment::
+AppCatalog enabled Kubernetes cluster
+
+Artifact::
+`kubectl` or equivalent tool
+
+Response::
+The provisioning of the service instance fails with an message containing the reason why the provisioning fails.
+
+Response measure::
+The provisioning is aborted.
+
+Rationale::
+Services with excessive resource usage or special configurations aren't commercially reasonable.
+Each service must document and enforce constraints that limit the resources and impact of abnormal conditions so that the user cannot use it out of certain boundaries.

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

@@ -0,0 +1,28 @@
+= Service Istance Logs
+
+Source::
+User
+
+Stimulus::
+Desire to view the logs of a service instance.
+
+Environment::
+Converged Cluster
+
+Artifact::
+`kubectl`
+
+Response::
+All logs of the service are visible.
+
+Response measure::
+The service's logs can be viewed via kubectl.
+
+Rationale::
+To give the users more insight with issues they might have by using the services.
+
+[NOTE]
+====
+Currently only available for Helm-based services.
+Cloud Instances are currently excluded.
+====

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

@@ -0,0 +1,32 @@
+= Provisioning Time
+
+Source::
+User
+
+Stimulus::
+Orders a service via the provided APIs.
+
+Environment::
+AppCatalog enabled Kubernetes cluster ("Converged Cluster")
+
+Artifact::
+`kubectl` or equivalent tool
+
+Response::
+Service ready (status condition)
+
+Response measure::
+Service ready depending on service architecture in normal conditions:
+- Standalone: within 10 minutes
+- Replicated: within 20 minutes
+- Clustered: within 30 minutes
+
+Rationale::
+The user can work with the instance in an acceptable time frame.
+
+[NOTE]
+====
+- The provided APIs can vary according to the environment.
+- The service is provisioned asynchronously and its readiness status has to be polled regularly.
+- Services with Cloud Instance architecture type are excluded and they "take as long as needed".
+====

docs/modules/ROOT/partials/nav-reference.adoc

@@ -0,0 +1,20 @@
+* xref:app-catalog:ROOT:reference/quality-requirements.adoc[Quality Requirements]
+
+** Maintainability
+*** xref:app-catalog:ROOT:reference/quality-requirements/maintainability/readiness-standards.adoc[Service Production Readiness Standards]
+
+** Portability
+*** xref:app-catalog:ROOT:reference/quality-requirements/portability/backup-exports.adoc[Backups Can Be Exported]
+*** xref:app-catalog:ROOT:reference/quality-requirements/portability/provisioning.adoc[Common Interface to Provision Services]
+
+** Reliability
+*** xref:app-catalog:ROOT:reference/quality-requirements/reliability/automatic-updates.adoc[Automatic Updates]
+*** xref:app-catalog:ROOT:reference/quality-requirements/reliability/mandatory-updates.adoc[Mandatory Updates]
+*** xref:app-catalog:ROOT:reference/quality-requirements/reliability/backup-interval.adoc[Minimum Backup Interval]
+
+** Usability
+*** xref:app-catalog:ROOT:reference/quality-requirements/usability/actionable-alerts.adoc[Actionable Alerts]
+*** xref:app-catalog:ROOT:reference/quality-requirements/usability/api-declarative.adoc[Declarative Configuration of Instances]
+*** xref:app-catalog:ROOT:reference/quality-requirements/usability/api-validation.adoc[Service Instance API Validation]
+*** xref:app-catalog:ROOT:reference/quality-requirements/usability/automated-provisioning.adoc[Automated Provisioning of a Service]
+*** xref:app-catalog:ROOT:reference/quality-requirements/usability/logs.adoc[Service Istance Logs]