vshn · tobru · Jan 17, 2025 · Dec 31, 2024 · Jan 3, 2025 · Jan 3, 2025
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,22 @@
+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/
+      - id: navigation
+        name: Validate Navigation
+        entry: hack/check-nav.py
+        language: python
+        files: ^docs/modules/ROOT/pages/
diff --git a/docs/modules/ROOT/pages/.vale.ini b/docs/modules/ROOT/pages/.vale.ini
@@ -10,3 +10,4 @@ Microsoft.GenderBias = warning
 Microsoft.Contractions = warning
 Microsoft.Quotes = warning
 Microsoft.Avoid = warning
+Microsoft.RangeFormat = ignore
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,75 @@
+= 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.
+
+Further usage documentation is in xref:adr/working-with.adoc[].
+
+== 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/...es/explanations/decisions/postgresql.adoc → ...03-stackgres-operator-for-postgresql.adoc b/...es/explanations/decisions/postgresql.adoc → ...03-stackgres-operator-for-postgresql.adoc
@@ -1,4 +1,21 @@
-= VSHN Managed PostgreSQL
+= ADR 0003 - StackGres Operator for PostgreSQL
+:adr_author:    Simon Beck
+:adr_owner:     Schedar
+:adr_reviewers: Schedar
+:adr_date:      2022-11-15
+:adr_upd_date:  2023-11-01
+:adr_status:    implemented
+:adr_tags:      postgresql,service
+:page-aliases:  explanations/decisions/postgresql.adoc
+
+
+include::partial$adr-meta.adoc[]
+
+[NOTE]
+.Summary
+====
+We use StackGres as the underlying operator to provide the product PostgreSQL by VSHN.
+====
 
 == Problem
 

diff --git a/...ations/decisions/postgres-monitoring.adoc → ...adr/0004-postgresql-metrics-exporter.adoc b/...ations/decisions/postgres-monitoring.adoc → ...adr/0004-postgresql-metrics-exporter.adoc
@@ -1,4 +1,20 @@
-= PostgreSQL by VSHN Availability check
+= ADR 0004 - PostgreSQL Metrics Exporter
+:adr_author:    Łukasz Widera
+:adr_owner:     Schedar
+:adr_reviewers: Schedar
+:adr_date:      2023-02-21
+:adr_upd_date:  2023-03-07
+:adr_status:    implemented
+:adr_tags:      postgresql,service,monitoring,metrics
+:page-aliases:  explanations/decisions/postgres-monitoring.adoc
+
+include::partial$adr-meta.adoc[]
+
+[NOTE]
+.Summary
+====
+We're using a custom exporter to export metrics about PostgreSQL.
+====
 
 == Problem
 

diff --git a/...anations/decisions/postgres-upgrades.adoc → ...utomated-postgresql-service-upgrades.adoc b/...anations/decisions/postgres-upgrades.adoc → ...utomated-postgresql-service-upgrades.adoc
@@ -1,4 +1,20 @@
-= VSHN Managed PostgreSQL
+= ADR 0005 - Automated PostgreSQL Service Upgrades
+:adr_author:    Simon Beck
+:adr_owner:     Schedar
+:adr_reviewers: Schedar
+:adr_date:      2023-05-23
+:adr_upd_date:  2023-05-04
+:adr_status:    implemented
+:adr_tags:      postgresql,service,maintenance
+:page-aliases:  explanations/decisions/postgres-upgrades.adoc
+
+include::partial$adr-meta.adoc[]
+
+[NOTE]
+.Summary
+====
+We will do automatic minor upgrade and manual major upgrades and inform 3 months after EOL and then force upgrade the instance.
+====
 
 == Problem
 

diff --git a/...T/pages/explanations/decisions/redis.adoc → ...dr/0006-bitnami-helm-chart-for-redis.adoc b/...T/pages/explanations/decisions/redis.adoc → ...dr/0006-bitnami-helm-chart-for-redis.adoc
@@ -1,4 +1,20 @@
-= VSHN Managed Redis
+= ADR 0006 - Bitnami Helm Chart for Redis
+:adr_author:    Simon Beck
+:adr_owner:     Schedar
+:adr_reviewers: Schedar
+:adr_date:      2022-12-27
+:adr_upd_date:  2023-01-04
+:adr_status:    implemented
+:adr_tags:      redis,service
+:page-aliases:  explanations/decisions/redis.adoc
+
+include::partial$adr-meta.adoc[]
+
+[NOTE]
+.Summary
+====
+We use the Redis Bitnami Helm Chart and deploy it with the Crossplane Provider Kubernetes.
+====
 
 == Problem
 

diff --git a/...xplanations/decisions/redis-upgrades.adoc → ...007-automated-redis-service-upgrades.adoc b/...xplanations/decisions/redis-upgrades.adoc → ...007-automated-redis-service-upgrades.adoc
@@ -1,4 +1,20 @@
-= VSHN Managed Redis Upgrade Policy
+= ADR 0007 - Automated Redis Service Upgrades
+:adr_author:    Fabian Fischer
+:adr_owner:     Schedar
+:adr_reviewers: Schedar
+:adr_date:      2023-07-11
+:adr_upd_date:  2023-07-11
+:adr_status:    implemented
+:adr_tags:      redis,upgrades,maintenance
+:page-aliases:  explanations/decisions/redis-upgrades.adoc
+
+include::partial$adr-meta.adoc[]
+
+[NOTE]
+.Summary
+====
+Both minor and major updates are done manually by the service user.
+====
 
 == Problem
 

diff --git a/...pages/explanations/decisions/mariadb.adoc → .../0008-bitnami-helm-chart-for-mariadb.adoc b/...pages/explanations/decisions/mariadb.adoc → .../0008-bitnami-helm-chart-for-mariadb.adoc
@@ -1,4 +1,19 @@
-= VSHN Managed MariaDB
+= ADR 0008 - Bitnami Helm Chart for MariaDB
+:adr_author:    Simon Beck
+:adr_owner:     Schedar
+:adr_reviewers: Schedar
+:adr_date:      2022-12-27
+:adr_upd_date:  2023-10-31
+:adr_status:    implemented
+:adr_tags:      service,mariadb,helm
+
+include::partial$adr-meta.adoc[]
+
+[NOTE]
+.Summary
+====
+We use the Redis Bitnami Helm Chart.
+====
 
 == Problem
 
@@ -137,4 +152,4 @@ We also agreed to the fact that we should prefer Helm Charts over operators for
 * Helm Chart are readily available for most of our services.
 * We have great experience with Helm Charts.
 * We should stick with one solution as much as possible to reduce complexity.
-* Operators may be very much prone to sudden bugs which may be difficult to fix on our own.
+* Operators may be very much prone to sudden bugs which may be difficult to fix on our own.
diff --git a/...explanations/decisions/mariadb-proxy.adoc → ...0009-proxysql-for-mariadb-clustering.adoc b/...explanations/decisions/mariadb-proxy.adoc → ...0009-proxysql-for-mariadb-clustering.adoc
@@ -1,4 +1,19 @@
-= VSHN Managed MariaDB HA Proxy solutions
+= ADR 0009 - ProxySQL for MariaDB Clustering
+:adr_author:    Nicolas Bigler
+:adr_owner:     Schedar
+:adr_reviewers: Schedar
+:adr_date:      2024-10-17
+:adr_upd_date:  2024-10-17
+:adr_status:    implemented
+:adr_tags:      mariadb,ha,cluster
+
+include::partial$adr-meta.adoc[]
+
+[NOTE]
+.Summary
+====
+We use ProxySQL for MariaDB Clustering.
+====
 
 == Problem
 

diff --git a/...cisions/local-objectstorage-provider.adoc → .../0010-minio-for-local-object-storage.adoc b/...cisions/local-objectstorage-provider.adoc → .../0010-minio-for-local-object-storage.adoc
@@ -1,4 +1,19 @@
-= VSHN Managed Object Storage
+= ADR 0010 - MinIO for Local Object Storage
+:adr_author:    Gabriel Saratura
+:adr_owner:     Schedar
+:adr_reviewers: Schedar
+:adr_date:      2023-10-23
+:adr_upd_date:  2023-10-23
+:adr_status:    implemented
+:adr_tags:      minio,service,objectstorage
+
+include::partial$adr-meta.adoc[]
+
+[NOTE]
+.Summary
+====
+We use MinIO to provide local object storage.
+====
 
 == Problem
 

diff --git a/...ns/decisions/local-objectstorage-sli.adoc → ...011-monitor-object-bucket-with-probe.adoc b/...ns/decisions/local-objectstorage-sli.adoc → ...011-monitor-object-bucket-with-probe.adoc
@@ -1,4 +1,19 @@
-= SLI for VSHN Managed Object Storage
+= ADR 0011 - Monitor Object Bucket with Probe
+:adr_author:    Gabriel Saratura
+:adr_owner:     Schedar
+:adr_reviewers: Schedar
+:adr_date:      2023-10-23
+:adr_upd_date:  2023-10-23
+:adr_status:    implemented
+:adr_tags:      minio,monitoring,sli
+
+include::partial$adr-meta.adoc[]
+
+[NOTE]
+.Summary
+====
+Use Probe one ObjectBucket to monitor the service availability.
+====
 
 == Problem
 

diff --git a/...ions/decisions/converged-service-loc.adoc → ...nverged-service-in-managed-namespace.adoc b/...ions/decisions/converged-service-loc.adoc → ...nverged-service-in-managed-namespace.adoc
@@ -1,4 +1,20 @@
-= Converged Service Provisioning Location
+= ADR 0012 - Converged Service in Managed Namespace
+:adr_author:    Christian Cremer
+:adr_owner:     Schedar
+:adr_reviewers: Schedar
+:adr_date:      2022-03-24
+:adr_upd_date:  2022-12-05
+:adr_status:    implemented
+:adr_tags:      framework,service
+:page-aliases:  explanations/decisions/converged-service-loc.adoc
+
+include::partial$adr-meta.adoc[]
+
+[NOTE]
+.Summary
+====
+Service instances are running in their own managed namespace.
+====
 
 == Problem
 

diff --git a/...pages/explanations/decisions/logging.adoc → ...3-use-logging-facilities-of-platform.adoc b/...pages/explanations/decisions/logging.adoc → ...3-use-logging-facilities-of-platform.adoc
@@ -1,4 +1,20 @@
-= Handling Logs for Converged Services
+= ADR 0013 - Use Logging Facilities of Platform
+:adr_author:    Fabian Fischer
+:adr_owner:     Schedar
+:adr_reviewers: Schedar
+:adr_date:      2023-03-14
+:adr_upd_date:  2023-03-14
+:adr_status:    implemented
+:adr_tags:      framework,service,logging
+:page-aliases:  explanations/decisions/logging.adoc
+
+include::partial$adr-meta.adoc[]
+
+[NOTE]
+.Summary
+====
+We use the logging solution of the platform to give users access to service logs.
+====
 
 == Problem
 

diff --git a/...ns/decisions/composition-deployments.adoc → ...nent-to-deploy-compositions-and-xrds.adoc b/...ns/decisions/composition-deployments.adoc → ...nent-to-deploy-compositions-and-xrds.adoc
@@ -1,4 +1,20 @@
-= Decision How to Deploy Compositions and XRDs
+= ADR 0014 - Commodore Component to Deploy Compositions and XRDs
+:adr_author:    Simon Beck
+:adr_owner:     Schedar
+:adr_reviewers: Schedar
+:adr_date:      2022-08-05
+:adr_upd_date:  2022-12-09
+:adr_status:    implemented
+:adr_tags:      framework,commodore,crossplane
+:page-aliases:  explanations/decisions/composition-deployments.adoc
+
+include::partial$adr-meta.adoc[]
+
+[NOTE]
+.Summary
+====
+We use Commodore Components without Packages to deploy Compositions and XRDs to clusters.
+====
 
 == Problem