vshn · tobru · Dec 31, 2024 · Jan 3, 2025 · Jan 3, 2025 · Jan 3, 2025
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,17 @@
+repos:
+  - repo: local
+    hooks:
+      - id: adr-status-valid
+        name: Validate ADR status
+        entry: hack/adr-tool.py
+        args:
+          - validate
+        language: python
+        files: ^docs/modules/ROOT/pages/adr/
+      - id: adr-index
+        name: Generate ADR Index
+        entry: hack/adr-tool.py
+        args:
+          - generate
+        language: python
+        files: ^docs/modules/ROOT/pages/adr/
diff --git a/docs/modules/ROOT/pages/adr/0001-architecture-decision-records.adoc b/docs/modules/ROOT/pages/adr/0001-architecture-decision-records.adoc
@@ -0,0 +1,73 @@
+= ADR 0001 - Architecture Decision Records
+:adr_author:    Tobias Brunner
+:adr_owner:     Schedar
+:adr_reviewers: Schedar
+:adr_date:      2025-01-01
+:adr_upd_date:  2025-01-06
+:adr_status:    draft
+:adr_tags:      processes
+
+include::partial$adr-meta.adoc[]
+
+[NOTE]
+.Summary
+====
+Architecture Decision Records (ADR) are our way to document decisions, ideas, architecture, processes, tools and other important aspects of the engineering process. It helps us to understand the "why".
+====
+
+== Context
+
+Throughout the lifetime of any given engineering task, lots of decisions have to be made.
+Some of them are quick and easy with a neglectable impact on the whole system, some of them have a broader impact.
+Most of the time, "future us" doesn't know anymore _why_ something is done in a particular way.
+Also, it might not be clear by just reading the code, other influences of a decision are not available in the code.
+
+== Decision
+
+We will write ADRs to document our decisions on the architecture, processes, ideas and tools.
+
+An ADR is a AsciiDoc file in the folder `docs/modules/ROOT/pages/adr/NNNN-slugified-title.adoc`.
+
+ADRs will be numbered sequentially and monotonically. Numbers will not be reused.
+
+If a decision is reversed, we will keep the old one around, but mark it as superseded. It's still relevant to know that it was the decision, but is no longer the decision.
+
+An existing ADR can be updated with new knowledge which has to be marked appropriately, for example with an annotation `Update: 2025-01-06`.
+A new ADR must be created for significant changes.
+
+We will use a format with just a few parts, so each document is easy to digest.
+If, for any reason, the format can be adjusted for a particular ADR.
+
+Status::
+* Draft: ADR still being worked on - no decision has been taken yet.
+* Accepted: The decision is accepted.
+* Implemented: ADRs which were accepted and are implemented.
+* Rejected: The ADR has been rejected. It's still here for history reasons and to understand why it has been rejected.
+* Obsolete: ADRs kept for historical reasons, but don't reflect the current or impending state of the codebase or project.
+
+Title::
+ADRs have names that are short noun phrases. For example, "ADR 0001: Architecture Decision Records" or "ADR 0042: StackGres for Managed PostgreSQL service"
+
+Context::
+This section describes the forces at play, including technological, political, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts.
+
+Decision::
+This section describes our response to these forces. It is stated in full sentences, with active voice. "We will ..."
+
+Consequences::
+This section describes the resulting context, after applying the decision. All consequences should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future.
+
+The whole document should short and concise.
+We will write each ADR as if it is a conversation with a future VSHNeer.
+This requires good writing style, with full sentences organized into paragraphs. Bullets are acceptable only for visual style, not as an excuse for writing sentence fragments.
+
+== Consequences
+
+ADRs will help current and future VSHNeers understand the "why".
+
+Initially, writing ADRs will feel like additional work or a burden. Over time, it will prove its value.
+
+Keeping ADRs up-to-date (status, updated date) is a manual effort which might lead into outdated information.
+
+The motivation behind previous decisions is visible for every VSHNeer, present and future.
+Nobody is left scratching their heads to understand, "What were they thinking?" and the time to change old decisions will be clear from changes in the project's context.
diff --git a/docs/modules/ROOT/pages/adr/0002-service-documentation.adoc b/docs/modules/ROOT/pages/adr/0002-service-documentation.adoc
@@ -0,0 +1,27 @@
+= ADR 0002 - Service Documentation
+:adr_author:    Tobias Brunner
+:adr_owner:     Schedar
+:adr_reviewers: Schedar
+:adr_date:      2025-01-06
+:adr_upd_date:  2025-01-06
+:adr_status:    draft
+:adr_tags:      processes
+
+include::partial$adr-meta.adoc[]
+
+[NOTE]
+.Summary
+====
+TODO
+====
+
+
+== Context
+
+
+
+== Decision
+
+
+
+== Consequences
diff --git a/docs/modules/ROOT/pages/adr/index.adoc b/docs/modules/ROOT/pages/adr/index.adoc
@@ -0,0 +1,10 @@
+= ADR Index
+:navtitle: ADRs
+
+[cols="3,1,1,1"]
+|===
+|Title |Status |Date |Updated
+
+|xref:adr/0001-architecture-decision-records.adoc[] |draft |2025-01-01 |2025-01-06
+|xref:adr/0002-service-documentation.adoc[] |draft |2025-01-06 |2025-01-06
+|===
diff --git a/docs/modules/ROOT/pages/adr/working-with.adoc b/docs/modules/ROOT/pages/adr/working-with.adoc
@@ -0,0 +1,15 @@
+= Working with ADRs
+
+As decided in xref:adr/0001-architecture-decision-records.adoc[], we use ADRs.
+This page helps to work with ADRs.
+
+TODO
+
+== Related Links
+
+* https://adr.github.io/[Homepage of the ADR GitHub Organization^]
+* https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html[Michael Nygard - Documenting Architecture Decisions^]
+* https://mbuege.com/2022/11/14/architecture-decision-records/[Matthias Büge - Architecture Decision Records^]
+* https://18f.gsa.gov/2021/07/06/architecture_decision_records_helpful_now_invaluable_later/[18F - Architecture Decision Records: Helpful now, invaluable later^]
+* https://github.com/joelparkerhenderson/architecture-decision-record[GitHub joelparkerhenderson/architecture-decision-record^]
+* https://www.heise.de/hintergrund/Gut-dokumentiert-Architecture-Decision-Records-4664988.html?seite=all[Heise - Gut dokumentiert: Architecture Decision Records^]
diff --git a/docs/modules/ROOT/pages/service/postgresql.adoc b/docs/modules/ROOT/pages/service/postgresql.adoc
@@ -0,0 +1,15 @@
+= Service: PostgreSQL
+:svc_name:       PostgreSQL by VSHN
+:svc_owner:      Schedar
+:svc_deploytech: Operator (Stackgres)
+:svc_status:     production
+
+include::partial$service-meta.adoc[]
+
+== Architecture
+
+Brief introduction on the architecture of the service, to get an understanding how it is working.
+
+== Related ADRs
+
+* TODO
diff --git a/docs/modules/ROOT/partials/adr-meta.adoc b/docs/modules/ROOT/partials/adr-meta.adoc
@@ -0,0 +1,23 @@
+[.meta-info-table,cols="1h,2"]
+|===
+|Author
+|{adr_author}
+
+|Owner
+|{adr_owner}
+
+|Reviewers
+|{adr_reviewers}
+
+|Date Created
+|{adr_date}
+
+|Date Updated
+|{adr_upd_date}
+
+|Status
+|[.{adr_status} .status-macro]#{adr_status}#
+
+|Tags
+|{adr_tags}
+|===
diff --git a/docs/modules/ROOT/partials/nav-adrs.adoc b/docs/modules/ROOT/partials/nav-adrs.adoc
@@ -0,0 +1,2 @@
+** xref:adr/0001-architecture-decision-records.adoc[]
+** xref:adr/0002-service-documentation.adoc[]
diff --git a/docs/modules/ROOT/partials/nav.adoc b/docs/modules/ROOT/partials/nav.adoc
@@ -3,145 +3,21 @@
 ** xref:app-catalog:ROOT:explanations/why_exists.adoc[Why does it exist?]
 ** xref:app-catalog:ROOT:explanations/app_catalog.adoc[Concept]
 ** xref:app-catalog:ROOT:reference/glossary.adoc[]
-* Architecture
-** xref:app-catalog:ROOT:reference/arch-control-plane.adoc[]
-** AppCat Usage Reporting
-*** xref:app-catalog:ROOT:reference/vshn-usage-reporting.adoc[]
-*** xref:app-catalog:ROOT:reference/cloud-usage-reporting.adoc[]
-** xref:app-catalog:ROOT:reference/service-maturity.adoc[]
-** xref:app-catalog:ROOT:reference/framework-requirements.adoc[]
-** xref:app-catalog:ROOT:reference/slareports.adoc[]
-** Separate Control Plane from Service Clusters
-*** xref:app-catalog:ROOT:reference/control-plane-pitfalls.adoc[]
-*** xref:app-catalog:ROOT:reference/sli-prober-architecture.adoc[]
-** xref:app-catalog:ROOT:reference/ci-cd.adoc[]
-** xref:app-catalog:ROOT:reference/quality-requirements.adoc[Quality Requirements]
-*** xref:app-catalog:ROOT:reference/quality-requirements/maintainability/readiness-standards.adoc[Maintainability]
-*** xref:app-catalog:ROOT:reference/quality-requirements/portability/backup-exports.adoc[Portability]
-*** 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/provisioning-time.adoc[Automated Provisioning of a Service]
-**** xref:app-catalog:ROOT:reference/quality-requirements/usability/logs.adoc[Service Instance Logs]
-
-** Archive
-*** xref:app-catalog:ROOT:reference/billing-appuio.adoc[Billing on APPUiO Cloud]
-*** xref:app-catalog:ROOT:reference/billing-naming.adoc[]
-
-* Exoscale
-** xref:app-catalog:ROOT:how-tos/exoscale_dbaas/price-api.adoc[Exoscale Price API]
-** xref:app-catalog:ROOT:reference/exoscale-osbapi.adoc[]
+* xref:service/postgresql.adoc[Service: PostgreSQL]
 ** Runbooks
-*** xref:app-catalog:ROOT:runbooks/exoscale/restore_dbaas.adoc[]
-
-* Decisions
-** PostgreSQL by VSHN
-*** xref:app-catalog:ROOT:explanations/decisions/postgresql.adoc[Operator evaluation]
-*** xref:app-catalog:ROOT:explanations/decisions/postgres-monitoring.adoc[Availability Check]
-*** xref:app-catalog:ROOT:explanations/decisions/postgres-upgrades.adoc[Upgrade Policy]
-** Redis by VSHN
-*** xref:app-catalog:ROOT:explanations/decisions/redis.adoc[Chart evaluation]
-*** xref:app-catalog:ROOT:explanations/decisions/redis-upgrades.adoc[Upgrade Policy]
-** MariaDB By VSHN
-*** xref:app-catalog:ROOT:explanations/decisions/mariadb.adoc[Chart/Operator evaluation]
-*** xref:app-catalog:ROOT:explanations/decisions/mariadb-proxy.adoc[Proxy for HA setups]
-** ObjectStorage by VSHN
-*** xref:app-catalog:ROOT:explanations/decisions/local-objectstorage-provider.adoc[Provider Evaluation]
-*** xref:app-catalog:ROOT:explanations/decisions/local-objectstorage-sli.adoc[SLI]
-** xref:app-catalog:ROOT:explanations/decisions/nextcloud.adoc[Nextcloud by VSHN]
-** xref:app-catalog:ROOT:explanations/decisions/mongodb.adoc[MongoDB by VSHN]
-** xref:app-catalog:ROOT:explanations/decisions/secret-pki-mgmt.adoc[Secret and PKI Management by VSHN]
-** xref:app-catalog:ROOT:explanations/decisions/capacity-alerting.adoc[Converged Service Capacity Alerting]
-** xref:app-catalog:ROOT:explanations/decisions/logging.adoc[Converged Service Logging]
-** xref:app-catalog:ROOT:explanations/decisions/crossplane.adoc[Crossplane as Control Plane]
-** xref:app-catalog:ROOT:explanations/decisions/composition-deployments.adoc[Composition Deployments]
-** xref:app-catalog:ROOT:explanations/decisions/api-design.adoc[API Design]
-** xref:app-catalog:ROOT:explanations/decisions/sla-reports.adoc[SLA Reports]
-** xref:app-catalog:ROOT:explanations/decisions/converged-service-loc.adoc[Converged Service Provisioning Location]
-** xref:app-catalog:ROOT:explanations/decisions/generic-metrics.adoc[]
-** xref:app-catalog:ROOT:explanations/decisions/apiserver.adoc[API Server Replacement]
-** xref:app-catalog:ROOT:explanations/decisions/deletion-protection.adoc[]
-** xref:app-catalog:ROOT:explanations/decisions/user-management.adoc[]
-** xref:app-catalog:ROOT:explanations/decisions/comp-function-error-handling.adoc[]
-** xref:app-catalog:ROOT:explanations/decisions/release_process.adoc[]
-** Archive
-*** xref:app-catalog:ROOT:explanations/decisions/archive/converged-service-impl.adoc[Converged Service Provisioning Implementation]
-
-* SPKS
-** xref:redis.adoc[Redis]
-*** xref:app-catalog:ROOT:explanations/redis.adoc[Redis Service Details]
-*** xref:app-catalog:ROOT:explanations/redis_sentinel_lb_with_haproxy.adoc[Redis Sentinel with HAProxy]
-*** xref:app-catalog:ROOT:explanations/redis_fake_sentinel.adoc[Redis Fake Sentinel]
-*** xref:app-catalog:ROOT:how-tos/redis/debug_sentinel.adoc[Debug Redis Sentinel]
-*** xref:app-catalog:ROOT:how-tos/redis/manual_failover.adoc[Manually Perform a Redis Failover]
-*** xref:app-catalog:ROOT:how-tos/redis/no_active_leader.adoc[Fix wrong/invalide leader after rollout/update]
-*** Runbooks
-**** xref:app-catalog:ROOT:runbooks/redis/RedisClusterFlapping.adoc[RedisClusterFlapping]
-**** xref:app-catalog:ROOT:runbooks/redis/RedisDisconnectedSlaves.adoc[RedisDisconnectedSlaves]
-**** xref:app-catalog:ROOT:runbooks/redis/RedisDown.adoc[RedisDown]
-**** xref:app-catalog:ROOT:runbooks/redis/RedisKeyEviction.adoc[RedisKeyEviction]
-**** xref:app-catalog:ROOT:runbooks/redis/RedisMasterMissing.adoc[RedisMasterMissing]
-**** xref:app-catalog:ROOT:runbooks/redis/RedisMemoryHigh.adoc[RedisMemoryHigh]
-**** xref:app-catalog:ROOT:runbooks/redis/RedisOutOfMemory.adoc[RedisOutOfMemory]
-**** xref:app-catalog:ROOT:runbooks/redis/RedisReplicationBroken.adoc[RedisReplicationBroken]
-**** xref:app-catalog:ROOT:runbooks/redis/RedisTooManyMasters.adoc[RedisTooManyMasters]
-
-** xref:mariadb_galera.adoc[MariaDB Galera]
-*** xref:app-catalog:ROOT:explanations/decisions/mariadb.adoc[]
-*** xref:app-catalog:ROOT:explanations/mariadb_galera_lb_with_haproxy.adoc[MariaDB Galera with HAProxy]
-*** xref:app-catalog:ROOT:how-tos/mariadbgalera/debug.adoc[Debug MariaDB Galera]
-*** xref:app-catalog:ROOT:how-tos/mariadbgalera/find_cluster_for_instance.adoc[Find the Service Cluster]
-*** xref:app-catalog:ROOT:how-tos/mariadbgalera/bootstrap_cluster.adoc[Bootstrap Cluster]
-*** Runbooks
-**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraClusterDown.adoc[MySQLGaleraClusterDown]
-**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraClusterEvenNodes.adoc[MySQLGaleraClusterEvenNodes]
-**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraClusterSmall.adoc[MySQLGaleraClusterSmall]
-**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraDonorFallingBehind.adoc[MySQLGaleraDonorFallingBehind]
-**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraNotConnected.adoc[MySQLGaleraNotConnected]
-**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraNotOperational.adoc[MySQLGaleraNotOperational]
-**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraNotReady.adoc[MySQLGaleraNotReady]
-**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraOutOfSync.adoc[MySQLGaleraOutOfSync]
-**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLInnoDBLogWaits.adoc[MySQLInnoDBLogWaits]
-
-** xref:vault.adoc[Vault]
-*** xref:app-catalog:ROOT:explanations/vault_auto_unseal.adoc[Auto Unseal]
-*** xref:app-catalog:ROOT:explanations/vault_backup_restore.adoc[Backup and Restore]
-
-** Crossplane
-*** xref:app-catalog:ROOT:how-tos/crossplane/investigate_service_instances.adoc[Investigate a Service]
-*** xref:app-catalog:ROOT:how-tos/crossplane/enable_plan_upgrade.adoc[Enable Plan Upgrade]
-
-** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/overview.adoc[Crossplane Service Broker]
-*** xref:app-catalog:ROOT:explanations/crossplane_service_broker.adoc[Service Broker]
-*** xref:app-catalog:ROOT:explanations/crossplane_provider_mechanics.adoc[Provider Mechanics]
-*** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/setup_crossplane_service_broker.adoc[Setup a _Crossplane Service Broker_]
-*** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/setup_service_catalog.adoc[Setup a _Service Catalog_]
-*** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/bearer_token_authentication.adoc[HTTP _Bearer Token_ authentication]
-*** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/connect_service_catalog_to_service_broker.adoc[Connect the _Service Catalog_ to the _Service Broker_]
-*** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/kube_token_refresher.adoc[Setup Kube Token Refresher]
-*** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/basic_authentication.adoc[HTTP _Basic_ authentication]
-*** xref:app-catalog:ROOT:how-tos/crossplane/implement_new_service_offering.adoc[Implement a New Service]
-*** xref:app-catalog:ROOT:tutorials/crossplane_service_broker/setting_up_crossplane_service_broker.adoc[Crossplane Complete Setup Tutorial]
-
-** xref:app-catalog:ROOT:how-tos/haproxy/stats.adoc[HAProxy]
-
-* HowTos
-** xref:app-catalog:ROOT:how-tos/appcat/backfill_billing.adoc[]
-
-* Runbooks
-** PostgreSQL By VSHN
 *** xref:app-catalog:ROOT:how-tos/appcat/vshn/postgres/PostgreSQLConnectionsCritical.adoc[]
-** xref:app-catalog:ROOT:how-tos/appcat/appuio-quotas.adoc[]
-** xref:app-catalog:ROOT:how-tos/appcat/vshn/postgres/manual-restore.adoc[]
-** xref:app-catalog:ROOT:how-tos/appcat/AppCatBackupJobError.adoc[]
-** xref:app-catalog:ROOT:how-tos/appcat/GuaranteedUptimeTarget.adoc[]
-** High Available Alerts
-*** xref:app-catalog:ROOT:how-tos/appcat/vshn/AppCatHighAvailableStatefulsetWarning.adoc[]
-*** xref:app-catalog:ROOT:how-tos/appcat/vshn/AppCatHighAvailableDeploymentWarning.adoc[]
+*** xref:app-catalog:ROOT:how-tos/appcat/vshn/postgres/manual-restore.adoc[]
+* Service: SPKS
+* Service: Exoscale DBaaS
+* Control Plane
+* Framework
+** CI/CD
+** Billing
+* Service Providers
+** Exoscale
+** Cloudscale
+
+* xref:adr/index.adoc[]
+** xref:adr/working-with.adoc[]
+include::partial$nav-adrs.adoc[]
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		** xref:adr/0001-architecture-decision-records.adoc[]
		** xref:adr/0002-service-documentation.adoc[]