diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000..9341d224 --- /dev/null +++ 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 index 2c9a3e31..dbaa37c1 100644 --- 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 new file mode 100644 index 00000000..43034a96 --- /dev/null +++ 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 new file mode 100644 index 00000000..b779a97a --- /dev/null +++ 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/explanations/decisions/postgresql.adoc b/docs/modules/ROOT/pages/adr/0003-stackgres-operator-for-postgresql.adoc similarity index 96% rename from docs/modules/ROOT/pages/explanations/decisions/postgresql.adoc rename to docs/modules/ROOT/pages/adr/0003-stackgres-operator-for-postgresql.adoc index fbecfec1..872c5dbc 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/postgresql.adoc +++ b/docs/modules/ROOT/pages/adr/0003-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/docs/modules/ROOT/pages/explanations/decisions/postgres-monitoring.adoc b/docs/modules/ROOT/pages/adr/0004-postgresql-metrics-exporter.adoc similarity index 89% rename from docs/modules/ROOT/pages/explanations/decisions/postgres-monitoring.adoc rename to docs/modules/ROOT/pages/adr/0004-postgresql-metrics-exporter.adoc index c03f5849..bf561f75 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/postgres-monitoring.adoc +++ b/docs/modules/ROOT/pages/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/docs/modules/ROOT/pages/explanations/decisions/postgres-upgrades.adoc b/docs/modules/ROOT/pages/adr/0005-automated-postgresql-service-upgrades.adoc similarity index 84% rename from docs/modules/ROOT/pages/explanations/decisions/postgres-upgrades.adoc rename to docs/modules/ROOT/pages/adr/0005-automated-postgresql-service-upgrades.adoc index 5d21d402..b9dad698 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/postgres-upgrades.adoc +++ b/docs/modules/ROOT/pages/adr/0005-automated-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/docs/modules/ROOT/pages/explanations/decisions/redis.adoc b/docs/modules/ROOT/pages/adr/0006-bitnami-helm-chart-for-redis.adoc similarity index 85% rename from docs/modules/ROOT/pages/explanations/decisions/redis.adoc rename to docs/modules/ROOT/pages/adr/0006-bitnami-helm-chart-for-redis.adoc index 02d6e32f..7096edba 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/redis.adoc +++ b/docs/modules/ROOT/pages/adr/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/docs/modules/ROOT/pages/explanations/decisions/redis-upgrades.adoc b/docs/modules/ROOT/pages/adr/0007-automated-redis-service-upgrades.adoc similarity index 94% rename from docs/modules/ROOT/pages/explanations/decisions/redis-upgrades.adoc rename to docs/modules/ROOT/pages/adr/0007-automated-redis-service-upgrades.adoc index 6c5be841..ad3b1ee7 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/redis-upgrades.adoc +++ b/docs/modules/ROOT/pages/adr/0007-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/docs/modules/ROOT/pages/explanations/decisions/mariadb.adoc b/docs/modules/ROOT/pages/adr/0008-bitnami-helm-chart-for-mariadb.adoc similarity index 92% rename from docs/modules/ROOT/pages/explanations/decisions/mariadb.adoc rename to docs/modules/ROOT/pages/adr/0008-bitnami-helm-chart-for-mariadb.adoc index 9d8dc0b5..59e71c5f 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/mariadb.adoc +++ b/docs/modules/ROOT/pages/adr/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. \ No newline at end of file +* Operators may be very much prone to sudden bugs which may be difficult to fix on our own. diff --git a/docs/modules/ROOT/pages/explanations/decisions/mariadb-proxy.adoc b/docs/modules/ROOT/pages/adr/0009-proxysql-for-mariadb-clustering.adoc similarity index 92% rename from docs/modules/ROOT/pages/explanations/decisions/mariadb-proxy.adoc rename to docs/modules/ROOT/pages/adr/0009-proxysql-for-mariadb-clustering.adoc index feee18f5..5b212ddf 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/mariadb-proxy.adoc +++ b/docs/modules/ROOT/pages/adr/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/docs/modules/ROOT/pages/explanations/decisions/local-objectstorage-provider.adoc b/docs/modules/ROOT/pages/adr/0010-minio-for-local-object-storage.adoc similarity index 94% rename from docs/modules/ROOT/pages/explanations/decisions/local-objectstorage-provider.adoc rename to docs/modules/ROOT/pages/adr/0010-minio-for-local-object-storage.adoc index 0daf7300..0a9da6bd 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/local-objectstorage-provider.adoc +++ b/docs/modules/ROOT/pages/adr/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/docs/modules/ROOT/pages/explanations/decisions/local-objectstorage-sli.adoc b/docs/modules/ROOT/pages/adr/0011-monitor-object-bucket-with-probe.adoc similarity index 91% rename from docs/modules/ROOT/pages/explanations/decisions/local-objectstorage-sli.adoc rename to docs/modules/ROOT/pages/adr/0011-monitor-object-bucket-with-probe.adoc index ff03a762..babe7b2d 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/local-objectstorage-sli.adoc +++ b/docs/modules/ROOT/pages/adr/0011-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/docs/modules/ROOT/pages/explanations/decisions/converged-service-loc.adoc b/docs/modules/ROOT/pages/adr/0012-converged-service-in-managed-namespace.adoc similarity index 81% rename from docs/modules/ROOT/pages/explanations/decisions/converged-service-loc.adoc rename to docs/modules/ROOT/pages/adr/0012-converged-service-in-managed-namespace.adoc index 716914b5..a9ef9aa6 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/converged-service-loc.adoc +++ b/docs/modules/ROOT/pages/adr/0012-converged-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/docs/modules/ROOT/pages/explanations/decisions/logging.adoc b/docs/modules/ROOT/pages/adr/0013-use-logging-facilities-of-platform.adoc similarity index 84% rename from docs/modules/ROOT/pages/explanations/decisions/logging.adoc rename to docs/modules/ROOT/pages/adr/0013-use-logging-facilities-of-platform.adoc index 39a84564..0f66bb9f 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/logging.adoc +++ b/docs/modules/ROOT/pages/adr/0013-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/docs/modules/ROOT/pages/explanations/decisions/composition-deployments.adoc b/docs/modules/ROOT/pages/adr/0014-commodore-component-to-deploy-compositions-and-xrds.adoc similarity index 91% rename from docs/modules/ROOT/pages/explanations/decisions/composition-deployments.adoc rename to docs/modules/ROOT/pages/adr/0014-commodore-component-to-deploy-compositions-and-xrds.adoc index 1b10efe6..74b2c356 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/composition-deployments.adoc +++ b/docs/modules/ROOT/pages/adr/0014-commodore-component-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 diff --git a/docs/modules/ROOT/pages/explanations/decisions/generic-metrics.adoc b/docs/modules/ROOT/pages/adr/0015-metrics-and-monitoring-of-services.adoc similarity index 73% rename from docs/modules/ROOT/pages/explanations/decisions/generic-metrics.adoc rename to docs/modules/ROOT/pages/adr/0015-metrics-and-monitoring-of-services.adoc index 6fa250c5..9596ce0a 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/generic-metrics.adoc +++ b/docs/modules/ROOT/pages/adr/0015-metrics-and-monitoring-of-services.adoc @@ -1,6 +1,22 @@ -= Monitoring and Metrics for Converged VSHN Services - -Based on our decision for link:/app-catalog/explanations/decisions/postgres-monitoring.html[PostgreSQL] we will be using the https://github.com/vshn/appcat/tree/master/pkg/sliexporter[same SLI exporter] to monitor for the SLIs. += ADR 0015 - Metrics and Monitoring of Services +:adr_author: Simon Beck +:adr_owner: Schedar +:adr_reviewers: Schedar +:adr_date: 2023-07-06 +:adr_upd_date: 2023-09-26 +:adr_status: implemented +:adr_tags: framework,monitoring,metrics +:page-aliases: explanations/decisions/generic-metrics.adoc + +include::partial$adr-meta.adoc[] + +[NOTE] +.Summary +==== +This page describes how we collect metrics. +==== + +Based on our decision for xref:explanations/decisions/postgres-monitoring.adoc[PostgreSQL] we will be using the https://github.com/vshn/appcat/tree/master/pkg/sliexporter[same SLI exporter^] to monitor for the SLIs. The exporter will be extended with all necessary logic to check for SLIs of other services as well. To check databases the SLI exporter will perform a trivial query. diff --git a/docs/modules/ROOT/pages/explanations/decisions/api-design.adoc b/docs/modules/ROOT/pages/adr/0016-service-api-design.adoc similarity index 96% rename from docs/modules/ROOT/pages/explanations/decisions/api-design.adoc rename to docs/modules/ROOT/pages/adr/0016-service-api-design.adoc index 9d3deb02..df949fa8 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/api-design.adoc +++ b/docs/modules/ROOT/pages/adr/0016-service-api-design.adoc @@ -1,4 +1,20 @@ -= Decision on API Design += ADR 0016 - Service API Design +:adr_author: Simon Beck +:adr_owner: Schedar +:adr_reviewers: Schedar +:adr_date: 2022-08-23 +:adr_upd_date: 2022-12-05 +:adr_status: draft +:adr_tags: framework,api,service +:page-aliases: explanations/decisions/api-design.adoc + +include::partial$adr-meta.adoc[] + +[NOTE] +.Summary +==== +We use separate XRDs with convention to design a service API. +==== [NOTE] This decision page is currently still a WIP. diff --git a/docs/modules/ROOT/pages/explanations/decisions/capacity-alerting.adoc b/docs/modules/ROOT/pages/adr/0017-handling-of-capacity-alerts-for-incident-prevention.adoc similarity index 91% rename from docs/modules/ROOT/pages/explanations/decisions/capacity-alerting.adoc rename to docs/modules/ROOT/pages/adr/0017-handling-of-capacity-alerts-for-incident-prevention.adoc index 25c2bc9d..7c7a5373 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/capacity-alerting.adoc +++ b/docs/modules/ROOT/pages/adr/0017-handling-of-capacity-alerts-for-incident-prevention.adoc @@ -1,4 +1,20 @@ -= Handling of Capacity Alerts for Incident Prevention += ADR 0017 - Handling of Capacity Alerts for Incident Prevention +:adr_author: Fabian Fischer +:adr_owner: Schedar +:adr_reviewers: Schedar +:adr_date: 2023-02-24 +:adr_upd_date: 2023-03-02 +:adr_status: implemented +:adr_tags: framework,service,alerting +:page-aliases: explanations/decisions/capacity-alerting.adoc + +include::partial$adr-meta.adoc[] + +[NOTE] +.Summary +==== +We implement both exposing the user-workload monitoring and automated e-mail alerts through Mailgun. +==== == Problem diff --git a/docs/modules/ROOT/pages/explanations/decisions/sla-reports.adoc b/docs/modules/ROOT/pages/adr/0018-sla-reports-handling.adoc similarity index 93% rename from docs/modules/ROOT/pages/explanations/decisions/sla-reports.adoc rename to docs/modules/ROOT/pages/adr/0018-sla-reports-handling.adoc index bb44cabf..1a3672db 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/sla-reports.adoc +++ b/docs/modules/ROOT/pages/adr/0018-sla-reports-handling.adoc @@ -1,4 +1,20 @@ -= Decision on SLA Reports += ADR 0018 - SLA Reports Handling +:adr_author: Gabriel Saratura +:adr_owner: Schedar +:adr_reviewers: Schedar +:adr_date: 2023-05-08 +:adr_upd_date: 2023-05-09 +:adr_status: implemented +:adr_tags: framework,sla,reports +:page-aliases: explanations/decisions/sla-reports.adoc + +include::partial$adr-meta.adoc[] + +[NOTE] +.Summary +==== +We use a custom tool to create SLA reports. +==== == Problem diff --git a/docs/modules/ROOT/pages/explanations/decisions/deletion-protection.adoc b/docs/modules/ROOT/pages/adr/0019-deletion-protection-with-validating-webhook.adoc similarity index 93% rename from docs/modules/ROOT/pages/explanations/decisions/deletion-protection.adoc rename to docs/modules/ROOT/pages/adr/0019-deletion-protection-with-validating-webhook.adoc index 47e597f0..4b2084be 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/deletion-protection.adoc +++ b/docs/modules/ROOT/pages/adr/0019-deletion-protection-with-validating-webhook.adoc @@ -1,4 +1,20 @@ -= Deletion Protection += ADR 0019 - Deletion Protection with Validating Webhook +:adr_author: Simon Beck +:adr_owner: Schedar +:adr_reviewers: Schedar +:adr_date: 2024-03-14 +:adr_upd_date: 2024-03-18 +:adr_status: implemented +:adr_tags: framework,service +:page-aliases: explanations/decisions/deletion-protection.adoc + +include::partial$adr-meta.adoc[] + +[NOTE] +.Summary +==== +We use a custom validation webhook to implement deletion protection for service instances. +==== == Problem diff --git a/docs/modules/ROOT/pages/explanations/decisions/user-management.adoc b/docs/modules/ROOT/pages/adr/0020-user-management-in-service-instances.adoc similarity index 94% rename from docs/modules/ROOT/pages/explanations/decisions/user-management.adoc rename to docs/modules/ROOT/pages/adr/0020-user-management-in-service-instances.adoc index de1a3cef..ccbf0d80 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/user-management.adoc +++ b/docs/modules/ROOT/pages/adr/0020-user-management-in-service-instances.adoc @@ -1,4 +1,20 @@ -= Simple User management for single tenant services += ADR 0020 - User Management in Service Instances +:adr_author: Simon Beck +:adr_owner: Schedar +:adr_reviewers: Schedar +:adr_date: 2024--05-16 +:adr_upd_date: 2024--05-17 +:adr_status: implemented +:adr_tags: framework,service +:page-aliases: explanations/decisions/user-management.adoc + +include::partial$adr-meta.adoc[] + +[NOTE] +.Summary +==== +We enhance claims to manage users of a service instance. +==== == Problem diff --git a/docs/modules/ROOT/pages/explanations/decisions/comp-function-error-handling.adoc b/docs/modules/ROOT/pages/adr/0021-composition-function-error-handling.adoc similarity index 92% rename from docs/modules/ROOT/pages/explanations/decisions/comp-function-error-handling.adoc rename to docs/modules/ROOT/pages/adr/0021-composition-function-error-handling.adoc index c6d92771..8be65eef 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/comp-function-error-handling.adoc +++ b/docs/modules/ROOT/pages/adr/0021-composition-function-error-handling.adoc @@ -1,4 +1,20 @@ -= Composition Function Error Handling += ADR 0021 - Composition Function Error Handling +:adr_author: Gabriel Saratura +:adr_owner: Schedar +:adr_reviewers: Schedar +:adr_date: 2024-06-10 +:adr_upd_date: 2024-06-14 +:adr_status: implemented +:adr_tags: framework,crossplane +:page-aliases: explanations/decisions/comp-function-error-handling.adoc + +include::partial$adr-meta.adoc[] + +[NOTE] +.Summary +==== +We manage errors in Composition Functions. +==== In March 2024 we had a severe outage of VSHN PostgreSQL instances. This was due to several unfortunate events including our poor handling of errors in composition functions. @@ -69,4 +85,4 @@ We need to figure out in runtime functions such as `SetDesired()` or `GetObserve This can be decided at Team level during review. Moreover, a guideline to error handling would be welcomed any time. That being said, the proposal 1 is not enough to resolve problems of this document long term, therefore we need a POC to make bigger changes. The proposal 3 seems to be safer and with fewer difficulties along the way then Proposal 2. -Also, a POC which combines the Proposal 2 and 3 should not be dismissed. \ No newline at end of file +Also, a POC which combines the Proposal 2 and 3 should not be dismissed. diff --git a/docs/modules/ROOT/pages/explanations/decisions/apiserver.adoc b/docs/modules/ROOT/pages/adr/0022-replace-api-server-by-custom-resources.adoc similarity index 85% rename from docs/modules/ROOT/pages/explanations/decisions/apiserver.adoc rename to docs/modules/ROOT/pages/adr/0022-replace-api-server-by-custom-resources.adoc index 900dbd40..fab8ab16 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/apiserver.adoc +++ b/docs/modules/ROOT/pages/adr/0022-replace-api-server-by-custom-resources.adoc @@ -1,4 +1,20 @@ -= API Server Replacement += ADR 0022 - Replace API Server by Custom Resources +:adr_author: Simon Beck +:adr_owner: Schedar +:adr_reviewers: Schedar +:adr_date: 2023-11-02 +:adr_upd_date: 2023-11-02 +:adr_status: accepted +:adr_tags: framework,apiserver +:page-aliases: explanations/decisions/apiserver.adoc + +include::partial$adr-meta.adoc[] + +[NOTE] +.Summary +==== +Over time we strive to replace the API server with custom resources and a reconcile loop (controller). +==== == Problems diff --git a/docs/modules/ROOT/pages/explanations/decisions/release_process.adoc b/docs/modules/ROOT/pages/adr/0023-releasee-process-for-appcat-components.adoc similarity index 93% rename from docs/modules/ROOT/pages/explanations/decisions/release_process.adoc rename to docs/modules/ROOT/pages/adr/0023-releasee-process-for-appcat-components.adoc index b67bb015..5bea2cf6 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/release_process.adoc +++ b/docs/modules/ROOT/pages/adr/0023-releasee-process-for-appcat-components.adoc @@ -1,4 +1,20 @@ -= Decision on AppCat release process += ADR 0023 - Releasee Process for AppCat Components +:adr_author: Gabriel Saratura +:adr_owner: Schedar +:adr_reviewers: Schedar +:adr_date: 2024-07-25 +:adr_upd_date: 2024-07-25 +:adr_status: implemented +:adr_tags: framework,process,cicd +:page-aliases: explanations/decisions/release_process.adoc + +include::partial$adr-meta.adoc[] + +[NOTE] +.Summary +==== +We use Commodore Component releases to release AppCat components. +==== This page will describe the current AppCat release process, the problem we face and possible solutions. diff --git a/docs/modules/ROOT/pages/explanations/decisions/secret-pki-mgmt.adoc b/docs/modules/ROOT/pages/adr/0024-product-choice-for-secret-management.adoc similarity index 87% rename from docs/modules/ROOT/pages/explanations/decisions/secret-pki-mgmt.adoc rename to docs/modules/ROOT/pages/adr/0024-product-choice-for-secret-management.adoc index 1eb01ac7..1e967a0f 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/secret-pki-mgmt.adoc +++ b/docs/modules/ROOT/pages/adr/0024-product-choice-for-secret-management.adoc @@ -1,4 +1,20 @@ -= VSHN Managed Secret and PKI Management += ADR 0024 - Product Choice for Secret Management +:adr_author: Nicolas Bigler +:adr_owner: Schedar +:adr_reviewers: Schedar +:adr_date: 2024-05-27 +:adr_upd_date: 2024-05-27 +:adr_status: draft +:adr_tags: service,product +:page-aliases: explanations/decisions/secret-pki-mgmt.adoc + +include::partial$adr-meta.adoc[] + +[NOTE] +.Summary +==== +No decision is taken yet. +==== == Problem diff --git a/docs/modules/ROOT/pages/explanations/decisions/nextcloud.adoc b/docs/modules/ROOT/pages/adr/0025-nextcloud-deployment-with-helm-chart.adoc similarity index 83% rename from docs/modules/ROOT/pages/explanations/decisions/nextcloud.adoc rename to docs/modules/ROOT/pages/adr/0025-nextcloud-deployment-with-helm-chart.adoc index 35023228..70e66805 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/nextcloud.adoc +++ b/docs/modules/ROOT/pages/adr/0025-nextcloud-deployment-with-helm-chart.adoc @@ -1,4 +1,20 @@ -= VSHN Managed Nextcloud on Kubernetes += ADR 0025 - Nextcloud Deployment with Helm Chart +:adr_author: Łukasz Widera +:adr_owner: Schedar +:adr_reviewers: Schedar +:adr_date: 2024-06-12 +:adr_upd_date: 2024-07-02 +:adr_status: implemented +:adr_tags: service,nextcloud,helm +:page-aliases: explanations/decisions/nextcloud.adoc + +include::partial$adr-meta.adoc[] + +[NOTE] +.Summary +==== +We use the official Helm Chart of the Nextcloud project to deploy Nextcloud. +==== == Problem diff --git a/docs/modules/ROOT/pages/explanations/decisions/mongodb.adoc b/docs/modules/ROOT/pages/adr/0026-mongodb-product.adoc similarity index 84% rename from docs/modules/ROOT/pages/explanations/decisions/mongodb.adoc rename to docs/modules/ROOT/pages/adr/0026-mongodb-product.adoc index 25c355d0..408dce31 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/mongodb.adoc +++ b/docs/modules/ROOT/pages/adr/0026-mongodb-product.adoc @@ -1,4 +1,20 @@ -= MongoDB += ADR 0026 - Deploy MongoDB with Operator +:adr_author: Simon Beck +:adr_owner: Schedar +:adr_reviewers: Schedar +:adr_date: 2024-08-06 +:adr_upd_date: 2024-09-05 +:adr_status: draft +:adr_tags: service,mongodb,product +:page-aliases: explanations/decisions/mongodb.adoc + +include::partial$adr-meta.adoc[] + +[NOTE] +.Summary +==== +We use the MongoDB Enterprise Operator to deploy MongoDB. +==== == Problem diff --git a/docs/modules/ROOT/pages/explanations/decisions/keycloak.adoc b/docs/modules/ROOT/pages/adr/0027-keycloak-deployment-with-helm-chart.adoc similarity index 89% rename from docs/modules/ROOT/pages/explanations/decisions/keycloak.adoc rename to docs/modules/ROOT/pages/adr/0027-keycloak-deployment-with-helm-chart.adoc index d71d4962..40d80e33 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/keycloak.adoc +++ b/docs/modules/ROOT/pages/adr/0027-keycloak-deployment-with-helm-chart.adoc @@ -1,4 +1,20 @@ -= VSHN Managed Keycloak += ADR 0027 - Keycloak Deployment with Helm Chart +:adr_author: Nicolas Bigler +:adr_owner: Schedar +:adr_reviewers: Schedar +:adr_date: 2023-10-19 +:adr_upd_date: 2023-10-19 +:adr_status: implemented +:adr_tags: service,keycloak,helm +:page-aliases: explanations/decisions/keycloak.adoc + +include::partial$adr-meta.adoc[] + +[NOTE] +.Summary +==== +We use the Codecentric Helm Chart to deploy Keycloak. +==== == Problem @@ -83,3 +99,4 @@ We lack the expertise to contribute to this projects. As we already have experience deploying services with Helm Charts and we have been using the Codecentric Helm Chart for years, we are confident that this is the best solution for us. Furthermore we don't need to write a custom provider as we can use the `+provider-helm+` provider to instantiate the Helm Chart. + diff --git a/docs/modules/ROOT/pages/adr/0028-sli-prober-for-object-storage.adoc b/docs/modules/ROOT/pages/adr/0028-sli-prober-for-object-storage.adoc new file mode 100644 index 00000000..232d4e44 --- /dev/null +++ b/docs/modules/ROOT/pages/adr/0028-sli-prober-for-object-storage.adoc @@ -0,0 +1,90 @@ += ADR 0028 - SLI Prober for 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: service,monitoring,sli +:page-aliases: explanations/decisions/local-objectstorage-sli.adoc + +include::partial$adr-meta.adoc[] + +[NOTE] +.Summary +==== +We use a Probe to monitor Object Buckets. +==== + +== Problem + +Every AppCat service instance is being probed by our AppCat SLI Prober. +Currently, we use our Prober for database instances which we need to make sure that these are accessible all the time. +Object storage service is not a database service thus it might require a different approach as to how we check on service availability. +For instance object buckets usually are not highly used like databases and sometimes a customer has hundreds if not thousands instances of S3 buckets with their object storage service. +So how do we make sure that we expose the SLI metrics efficiently and reliably? + +=== Goals + +* Expose ObjectStorage SLI metrics efficiently and reliably + +=== Non-Goals + +* How to implement any solution + +== Proposals + +=== Check MinioIO Service + +We can leverage https://min.io/docs/minio/linux/operations/monitoring/healthcheck-probe.html[prometheus metrics or http check exposed] by MinIO to figure if the service is available thus calculating the SLI. +This approach does not require the help of our SLI Prober but just a prometheus recording rule. +It is very efficient as we don't have to probe S3 buckets whatsoever. + +==== Concerns +There is a concern with this approach, while we check if the service is up and running via prometheus we cannot be 100% sure +whether the S3 buckets customer created are accessible or not. +This concern is also brought up in the https://min.io/docs/minio/linux/operations/monitoring/healthcheck-probe.html[documentation] itself +therefore our SLI cannot be reliable. + +=== Probe all ObjectBucket + +The most straight forward and reliable way to make sure buckets are available is to connect to each ObjectBucket and list its content. +This can be done in the SLI Prober by using a reconcile on the Custom Resource. +This approach is the most reliable of all solutions. + +==== Concerns + +Main concern with this solution is the overhead that we might put on the SLI Prober. +It's not uncommon to have thousands ObjectBuckets thus potentially halting the SLI Prober to a stop. +Unfortunately, this event may also affect other services in the SLI Prober itself. + +=== Probe one ObjectBucket + +The idea behind this solution is to have a SLI bucket per each instance of MinIO. +The SLI Prober would then probe on this single instance to figure out if all other instances are running or not. +This solution seems to be a trade-off between the above 2 solutions though it's not perfect. +It will help us reliably check whether MinIO is running successfully and will put a low strain on the SLI Prober itself. + +==== Concerns + +One of the main concern with this approach is whether we can guarantee that checking one bucket is equal to checking all buckets. +In most case this should be the case as MinIO implements https://min.io/docs/minio/linux/operations/concepts/erasure-coding.html#minio-ec-erasure-set[Erasure Coding]. +MinIO guarantees that even if half of the nodes are down the data is still available. +However, if the are less than 50% nodes available then our test on single bucket is not relevant anymore. + +== Decision + +Use Probe one ObjectBucket + +== Rationale + +Checking only MinIO service is not enough to ensure that buckets themselves are available. +This is clearly https://min.io/docs/minio/linux/operations/monitoring/healthcheck-probe.html[stated] in the MinIO docs. +There can also be network issues to the buckets which we do not take in consideration with this particular check. + +On the other hand, checking all the buckets is very much cumbersome for the SLI Prober. +As stated earlier it can have a negative impact on other services as well. + +The middle ground here is to go with a single object bucket health check. +MinIO will ensure that all the buckets are available when there are at least more than 50% of the nodes. +To mitigate this issue we can set simple MinIO alert on the number of nodes available in order to ensure >50% capacity all the time. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/explanations/decisions/archive/converged-service-impl.adoc b/docs/modules/ROOT/pages/adr/0029-converged-service-provisioning-implementation.adoc similarity index 97% rename from docs/modules/ROOT/pages/explanations/decisions/archive/converged-service-impl.adoc rename to docs/modules/ROOT/pages/adr/0029-converged-service-provisioning-implementation.adoc index e5f26c3f..9ac3ce6c 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/archive/converged-service-impl.adoc +++ b/docs/modules/ROOT/pages/adr/0029-converged-service-provisioning-implementation.adoc @@ -1,6 +1,17 @@ -= Converged Service Provisioning Implementation += ADR 0029 - Converged Service Provisioning Implementation +:adr_author: Christian Cremer +:adr_owner: Schedar +:adr_reviewers: Schedar +:adr_date: 2022-03-24 +:adr_upd_date: 2022-11-25 +:adr_status: obsolete +:adr_tags: framework +:page-aliases: explanations/decisions/archive/converged-service-impl.adoc + +include::partial$adr-meta.adoc[] [NOTE] +.Summary ==== This page is obsolete. The discussions about the approach have been moved to xref:explanations/decisions/postgresql.adoc[the VSHN Managed PostgreSQL] page. diff --git a/docs/modules/ROOT/pages/adr/index.adoc b/docs/modules/ROOT/pages/adr/index.adoc new file mode 100644 index 00000000..826ea824 --- /dev/null +++ b/docs/modules/ROOT/pages/adr/index.adoc @@ -0,0 +1,124 @@ += ADR Index +:navtitle: ADRs + +[cols="3,1,1,1"] +|=== +|Title |Status |Date |Updated + +|xref:adr/0001-architecture-decision-records.adoc[] + +`processes` +|draft |2025-01-01 |2025-01-06 +|xref:adr/0002-service-documentation.adoc[] + +`processes` +|draft |2025-01-06 |2025-01-06 +|xref:adr/0003-stackgres-operator-for-postgresql.adoc[] + +`postgresql,service` +|implemented |2022-11-15 |2023-11-01 +|xref:adr/0004-postgresql-metrics-exporter.adoc[] + +`postgresql,service,monitoring,metrics` +|implemented |2023-02-21 |2023-03-07 +|xref:adr/0005-automated-postgresql-service-upgrades.adoc[] + +`postgresql,service,maintenance` +|implemented |2023-05-23 |2023-05-04 +|xref:adr/0006-bitnami-helm-chart-for-redis.adoc[] + +`redis,service` +|implemented |2022-12-27 |2023-01-04 +|xref:adr/0007-automated-redis-service-upgrades.adoc[] + +`redis,upgrades,maintenance` +|implemented |2023-07-11 |2023-07-11 +|xref:adr/0008-bitnami-helm-chart-for-mariadb.adoc[] + +`service,mariadb,helm` +|implemented |2022-12-27 |2023-10-31 +|xref:adr/0009-proxysql-for-mariadb-clustering.adoc[] + +`mariadb,ha,cluster` +|implemented |2024-10-17 |2024-10-17 +|xref:adr/0010-minio-for-local-object-storage.adoc[] + +`minio,service,objectstorage` +|implemented |2023-10-23 |2023-10-23 +|xref:adr/0011-monitor-object-bucket-with-probe.adoc[] + +`minio,monitoring,sli` +|implemented |2023-10-23 |2023-10-23 +|xref:adr/0012-converged-service-in-managed-namespace.adoc[] + +`framework,service` +|implemented |2022-03-24 |2022-12-05 +|xref:adr/0013-use-logging-facilities-of-platform.adoc[] + +`framework,service,logging` +|implemented |2023-03-14 |2023-03-14 +|xref:adr/0014-commodore-component-to-deploy-compositions-and-xrds.adoc[] + +`framework,commodore,crossplane` +|implemented |2022-08-05 |2022-12-09 +|xref:adr/0015-metrics-and-monitoring-of-services.adoc[] + +`framework,monitoring,metrics` +|implemented |2023-07-06 |2023-09-26 +|xref:adr/0016-service-api-design.adoc[] + +`framework,api,service` +|draft |2022-08-23 |2022-12-05 +|xref:adr/0017-handling-of-capacity-alerts-for-incident-prevention.adoc[] + +`framework,service,alerting` +|implemented |2023-02-24 |2023-03-02 +|xref:adr/0018-sla-reports-handling.adoc[] + +`framework,sla,reports` +|implemented |2023-05-08 |2023-05-09 +|xref:adr/0019-deletion-protection-with-validating-webhook.adoc[] + +`framework,service` +|implemented |2024-03-14 |2024-03-18 +|xref:adr/0020-user-management-in-service-instances.adoc[] + +`framework,service` +|implemented |2024--05-16 |2024--05-17 +|xref:adr/0021-composition-function-error-handling.adoc[] + +`framework,crossplane` +|implemented |2024-06-10 |2024-06-14 +|xref:adr/0022-replace-api-server-by-custom-resources.adoc[] + +`framework,apiserver` +|accepted |2023-11-02 |2023-11-02 +|xref:adr/0023-releasee-process-for-appcat-components.adoc[] + +`framework,process,cicd` +|implemented |2024-07-25 |2024-07-25 +|xref:adr/0024-product-choice-for-secret-management.adoc[] + +`service,product` +|draft |2024-05-27 |2024-05-27 +|xref:adr/0025-nextcloud-deployment-with-helm-chart.adoc[] + +`service,nextcloud,helm` +|implemented |2024-06-12 |2024-07-02 +|xref:adr/0026-mongodb-product.adoc[] + +`service,mongodb,product` +|draft |2024-08-06 |2024-09-05 +|xref:adr/0027-keycloak-deployment-with-helm-chart.adoc[] + +`service,keycloak,helm` +|implemented |2023-10-19 |2023-10-19 +|xref:adr/0028-sli-prober-for-object-storage.adoc[] + +`service,monitoring,sli` +|implemented |2023-10-23 |2023-10-23 +|xref:adr/0029-converged-service-provisioning-implementation.adoc[] + +`framework` +|obsolete |2022-03-24 |2022-11-25 +|=== diff --git a/docs/modules/ROOT/pages/adr/working-with.adoc b/docs/modules/ROOT/pages/adr/working-with.adoc new file mode 100644 index 00000000..f3f7ef35 --- /dev/null +++ b/docs/modules/ROOT/pages/adr/working-with.adoc @@ -0,0 +1,28 @@ += Working with ADRs + +As decided in xref:adr/0001-architecture-decision-records.adoc[], we use ADRs. +This page helps to work with ADRs. + +== Creating a new ADR + +TIP: You need https://cookiecutter.readthedocs.io/[Cookiecutter^] to use the provided templates and it's highly recommended to have https://pre-commit.com/[pre-commit^] ready and the Git hooks installed with `pre-commit install`. + +. Run `cookiecutter templates` in the root directory of the cloned https://github.com/vshn/application-catalog-docs[documentation repository^] +. Fill in the missing pieces (ADR number should automatically be the next free) +. Edit the ADR in the created file + +== ADR Index + +The ADR index at `docs/modules/ROOT/pages/adr/index.adoc` is automatically generated in a Git https://pre-commit.com/[pre-commit^] hook, which calls `hack/adr-tool.py generate`. + +== Related Links + +We're not the only ones using ADRs, here's a collection of interesting readings: + +* 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^] [DE] +* 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 Record^] [DE] +* https://rfd.shared.oxide.computer/rfd/0001[Oxide Computer - RFD 1 Requests for Discussion] diff --git a/docs/modules/ROOT/pages/explanations/app_catalog.adoc b/docs/modules/ROOT/pages/concept.adoc similarity index 98% rename from docs/modules/ROOT/pages/explanations/app_catalog.adoc rename to docs/modules/ROOT/pages/concept.adoc index 2f79b267..6d28901c 100644 --- a/docs/modules/ROOT/pages/explanations/app_catalog.adoc +++ b/docs/modules/ROOT/pages/concept.adoc @@ -1,4 +1,6 @@ = Application Catalog Concept +:page-aliases: explanations/app_catalog.adoc +:navtitle: Concept TIP: For an introduction what the application catalog is, please see https://products.docs.vshn.ch/products/appcat/index.html[our product documentation]. diff --git a/docs/modules/ROOT/pages/reference/arch-control-plane.adoc b/docs/modules/ROOT/pages/control-plane/central-control-plane-arch.adoc similarity index 99% rename from docs/modules/ROOT/pages/reference/arch-control-plane.adoc rename to docs/modules/ROOT/pages/control-plane/central-control-plane-arch.adoc index fb140312..f570b677 100644 --- a/docs/modules/ROOT/pages/reference/arch-control-plane.adoc +++ b/docs/modules/ROOT/pages/control-plane/central-control-plane-arch.adoc @@ -1,4 +1,5 @@ = Central Control Plane (CCP) +:page-aliases: reference/arch-control-plane.adoc image::universal-control-plane.drawio.svg[] diff --git a/docs/modules/ROOT/pages/reference/control-plane-pitfalls.adoc b/docs/modules/ROOT/pages/control-plane/split-architecture.adoc similarity index 95% rename from docs/modules/ROOT/pages/reference/control-plane-pitfalls.adoc rename to docs/modules/ROOT/pages/control-plane/split-architecture.adoc index ecbbdf3c..136ff3ef 100644 --- a/docs/modules/ROOT/pages/reference/control-plane-pitfalls.adoc +++ b/docs/modules/ROOT/pages/control-plane/split-architecture.adoc @@ -1,4 +1,5 @@ -= Pitfalls += Crossplane Split Architecture +:page-aliases: reference/control-plane-pitfalls.adoc This page shows the pitfalls and gotchas that we need to keep in mind if we develop for a split architecture. diff --git a/docs/modules/ROOT/pages/reference/sli-prober-architecture.adoc b/docs/modules/ROOT/pages/control-plane/split-sli-prober.adoc similarity index 96% rename from docs/modules/ROOT/pages/reference/sli-prober-architecture.adoc rename to docs/modules/ROOT/pages/control-plane/split-sli-prober.adoc index 8226c7eb..913c98fb 100644 --- a/docs/modules/ROOT/pages/reference/sli-prober-architecture.adoc +++ b/docs/modules/ROOT/pages/control-plane/split-sli-prober.adoc @@ -1,4 +1,5 @@ = SLI Prober +:page-aliases: reference/sli-prober-architecture.adoc The SLI-Prober connects to each instance and will report on its SLI. For that it needs to reconcile the composites of each instance, to get the connection details. diff --git a/docs/modules/ROOT/pages/how-tos/appcat/appuio-quotas.adoc b/docs/modules/ROOT/pages/csp/appuio/runbooks/appuio-quotas.adoc similarity index 94% rename from docs/modules/ROOT/pages/how-tos/appcat/appuio-quotas.adoc rename to docs/modules/ROOT/pages/csp/appuio/runbooks/appuio-quotas.adoc index 70b5e4ed..d0d71385 100644 --- a/docs/modules/ROOT/pages/how-tos/appcat/appuio-quotas.adoc +++ b/docs/modules/ROOT/pages/csp/appuio/runbooks/appuio-quotas.adoc @@ -1,4 +1,5 @@ -= Change AppCat service quota on APPUiO Cloud += Change AppCat service quota on APPUiO +:page-aliases: how-tos/appcat/appuio-quotas.adoc It's important, that the service instance has been created with resources lower than the quota. This is due to the fact, that the quotas are bound to the namespace and in order to change them, we need the namespace itself. diff --git a/docs/modules/ROOT/pages/reference/exoscale-osbapi.adoc b/docs/modules/ROOT/pages/csp/exoscale/osbapi.adoc similarity index 99% rename from docs/modules/ROOT/pages/reference/exoscale-osbapi.adoc rename to docs/modules/ROOT/pages/csp/exoscale/osbapi.adoc index 18a8ed5d..941c1c6a 100644 --- a/docs/modules/ROOT/pages/reference/exoscale-osbapi.adoc +++ b/docs/modules/ROOT/pages/csp/exoscale/osbapi.adoc @@ -1,4 +1,5 @@ = Exoscale Marketplace Integration +:page-aliases: reference/exoscale-osbapi.adoc To integrate services from the https://products.vshn.ch/appcat/services_index.html[VSHN Application Catalog^] into the https://www.exoscale.com/marketplace/[Exoscale Marketplace^], we provide an Exoscale-specific https://github.com/openservicebrokerapi/servicebroker/blob/master/spec.md[Open Service Broker (OSB) API^] endpoint to provision Organizations and enable access to the service offering. A web portal is provided by VSHN to the end-user of Exoscale to provision and manage services. diff --git a/docs/modules/ROOT/pages/how-tos/crossplane_service_broker/basic_authentication.adoc b/docs/modules/ROOT/pages/csp/spks/crossplane/basic_authentication.adoc similarity index 96% rename from docs/modules/ROOT/pages/how-tos/crossplane_service_broker/basic_authentication.adoc rename to docs/modules/ROOT/pages/csp/spks/crossplane/basic_authentication.adoc index 3a7277f2..3c394b90 100644 --- a/docs/modules/ROOT/pages/how-tos/crossplane_service_broker/basic_authentication.adoc +++ b/docs/modules/ROOT/pages/csp/spks/crossplane/basic_authentication.adoc @@ -1,4 +1,5 @@ = Setup HTTP _Basic_ authentication +:page-aliases: how-tos/crossplane_service_broker/basic_authentication.adoc WARNING: This tutorial is deprecated. Some links may not work. diff --git a/docs/modules/ROOT/pages/how-tos/crossplane_service_broker/bearer_token_authentication.adoc b/docs/modules/ROOT/pages/csp/spks/crossplane/bearer_token_authentication.adoc similarity index 98% rename from docs/modules/ROOT/pages/how-tos/crossplane_service_broker/bearer_token_authentication.adoc rename to docs/modules/ROOT/pages/csp/spks/crossplane/bearer_token_authentication.adoc index b057d687..3b5ca63a 100644 --- a/docs/modules/ROOT/pages/how-tos/crossplane_service_broker/bearer_token_authentication.adoc +++ b/docs/modules/ROOT/pages/csp/spks/crossplane/bearer_token_authentication.adoc @@ -1,4 +1,5 @@ = Prepare HTTP _Bearer Token_ Authentication +:page-aliases: how-tos/crossplane_service_broker/bearer_token_authentication.adoc This how-to will explain how a _Bearer Token_ can be requested from an authentication server. This will be required xref:app-catalog:ROOT:how-tos/crossplane_service_broker/connect_service_catalog_to_service_broker.adoc[to connect the _Service Catalog_ to the _Service Broker_]. diff --git a/docs/modules/ROOT/pages/how-tos/crossplane_service_broker/connect_service_catalog_to_service_broker.adoc b/docs/modules/ROOT/pages/csp/spks/crossplane/connect_service_catalog_to_service_broker.adoc similarity index 97% rename from docs/modules/ROOT/pages/how-tos/crossplane_service_broker/connect_service_catalog_to_service_broker.adoc rename to docs/modules/ROOT/pages/csp/spks/crossplane/connect_service_catalog_to_service_broker.adoc index 9900ce13..dc9a7af6 100644 --- a/docs/modules/ROOT/pages/how-tos/crossplane_service_broker/connect_service_catalog_to_service_broker.adoc +++ b/docs/modules/ROOT/pages/csp/spks/crossplane/connect_service_catalog_to_service_broker.adoc @@ -1,4 +1,5 @@ = Connect the _Service Catalog_ to a _Service Broker_ +:page-aliases: how-tos/crossplane_service_broker/connect_service_catalog_to_service_broker.adoc WARNING: This tutorial is deprecated. Some links may not work. diff --git a/docs/modules/ROOT/pages/explanations/crossplane_provider_mechanics.adoc b/docs/modules/ROOT/pages/csp/spks/crossplane/crossplane_provider_mechanics.adoc similarity index 98% rename from docs/modules/ROOT/pages/explanations/crossplane_provider_mechanics.adoc rename to docs/modules/ROOT/pages/csp/spks/crossplane/crossplane_provider_mechanics.adoc index 3c2563eb..5d4439f8 100644 --- a/docs/modules/ROOT/pages/explanations/crossplane_provider_mechanics.adoc +++ b/docs/modules/ROOT/pages/csp/spks/crossplane/crossplane_provider_mechanics.adoc @@ -1,4 +1,5 @@ = Crossplane Provider Mechanics +:page-aliases: explanations/crossplane_provider_mechanics.adoc The way a provider has to be implemented is still (as of Crossplane v1.19) rather not obvious. diff --git a/docs/modules/ROOT/pages/explanations/crossplane_service_broker.adoc b/docs/modules/ROOT/pages/csp/spks/crossplane/crossplane_service_broker.adoc similarity index 99% rename from docs/modules/ROOT/pages/explanations/crossplane_service_broker.adoc rename to docs/modules/ROOT/pages/csp/spks/crossplane/crossplane_service_broker.adoc index ddafcb80..3b873e76 100644 --- a/docs/modules/ROOT/pages/explanations/crossplane_service_broker.adoc +++ b/docs/modules/ROOT/pages/csp/spks/crossplane/crossplane_service_broker.adoc @@ -1,4 +1,5 @@ = Crossplane Service Broker +:page-aliases: explanations/crossplane_service_broker.adoc The Crossplane Service Broker is an https://github.com/openservicebrokerapi/servicebroker/blob/master/spec.md[Open Service Broker API] implementation based on Crossplane. diff --git a/docs/modules/ROOT/pages/how-tos/crossplane/implement_new_service_offering.adoc b/docs/modules/ROOT/pages/csp/spks/crossplane/implement_new_service_offering.adoc similarity index 99% rename from docs/modules/ROOT/pages/how-tos/crossplane/implement_new_service_offering.adoc rename to docs/modules/ROOT/pages/csp/spks/crossplane/implement_new_service_offering.adoc index da5cded6..89a376b7 100644 --- a/docs/modules/ROOT/pages/how-tos/crossplane/implement_new_service_offering.adoc +++ b/docs/modules/ROOT/pages/csp/spks/crossplane/implement_new_service_offering.adoc @@ -1,4 +1,5 @@ = How to Implement a new Service Offering +:page-aliases: how-tos/crossplane/implement_new_service_offering.adoc This page describes the steps which are necessary to implement a new service offering based on Crossplane and the https://github.com/vshn/crossplane-service-broker[crossplane-service-broker]. diff --git a/docs/modules/ROOT/pages/how-tos/crossplane_service_broker/kube_token_refresher.adoc b/docs/modules/ROOT/pages/csp/spks/crossplane/kube_token_refresher.adoc similarity index 98% rename from docs/modules/ROOT/pages/how-tos/crossplane_service_broker/kube_token_refresher.adoc rename to docs/modules/ROOT/pages/csp/spks/crossplane/kube_token_refresher.adoc index a349299b..3e7e8773 100644 --- a/docs/modules/ROOT/pages/how-tos/crossplane_service_broker/kube_token_refresher.adoc +++ b/docs/modules/ROOT/pages/csp/spks/crossplane/kube_token_refresher.adoc @@ -1,4 +1,5 @@ = Install Kube Token Refresher +:page-aliases: how-tos/crossplane_service_broker/kube_token_refresher.adoc As discussed in xref:app-catalog:ROOT:how-tos/crossplane_service_broker/connect_service_catalog_to_service_broker.adoc[Connecting the Service Catalog to a Service Broker], issued tokens might only be valid for a short period of time. For this purpose we developed the https://github.com/vshn/kube-token-refresher[kube-token-refresher], which periodically fetches a new bearer token and writes it to a secret for the Service Catalog. diff --git a/docs/modules/ROOT/pages/how-tos/crossplane_service_broker/overview.adoc b/docs/modules/ROOT/pages/csp/spks/crossplane/overview.adoc similarity index 94% rename from docs/modules/ROOT/pages/how-tos/crossplane_service_broker/overview.adoc rename to docs/modules/ROOT/pages/csp/spks/crossplane/overview.adoc index db5cc943..7dc1f885 100644 --- a/docs/modules/ROOT/pages/how-tos/crossplane_service_broker/overview.adoc +++ b/docs/modules/ROOT/pages/csp/spks/crossplane/overview.adoc @@ -1,4 +1,6 @@ -= Overview += Crossplane Service Broker Overview +:page-aliases: how-tos/crossplane_service_broker/overview.adoc + // tag::main[] The setup around a _Crossplane Service Broker_ consists of three main components: diff --git a/docs/modules/ROOT/pages/tutorials/crossplane_service_broker/setting_up_crossplane_service_broker.adoc b/docs/modules/ROOT/pages/csp/spks/crossplane/setting_up_crossplane_service_broker.adoc similarity index 97% rename from docs/modules/ROOT/pages/tutorials/crossplane_service_broker/setting_up_crossplane_service_broker.adoc rename to docs/modules/ROOT/pages/csp/spks/crossplane/setting_up_crossplane_service_broker.adoc index ea00afd1..0490ed2c 100644 --- a/docs/modules/ROOT/pages/tutorials/crossplane_service_broker/setting_up_crossplane_service_broker.adoc +++ b/docs/modules/ROOT/pages/csp/spks/crossplane/setting_up_crossplane_service_broker.adoc @@ -1,6 +1,6 @@ -:includedir: ../../how-tos/crossplane_service_broker - = Setting up the Crossplane Service Broker +:includedir: . +:page-aliases: tutorials/crossplane_service_broker/setting_up_crossplane_service_broker.adoc WARNING: This tutorial is deprecated. Some links may not work. diff --git a/docs/modules/ROOT/pages/how-tos/crossplane_service_broker/setup_crossplane_service_broker.adoc b/docs/modules/ROOT/pages/csp/spks/crossplane/setup_crossplane_service_broker.adoc similarity index 98% rename from docs/modules/ROOT/pages/how-tos/crossplane_service_broker/setup_crossplane_service_broker.adoc rename to docs/modules/ROOT/pages/csp/spks/crossplane/setup_crossplane_service_broker.adoc index 39c2881a..75e6c5fd 100644 --- a/docs/modules/ROOT/pages/how-tos/crossplane_service_broker/setup_crossplane_service_broker.adoc +++ b/docs/modules/ROOT/pages/csp/spks/crossplane/setup_crossplane_service_broker.adoc @@ -1,4 +1,5 @@ = Install the Crossplane Service Broker +:page-aliases: how-tos/crossplane_service_broker/setup_crossplane_service_broker.adoc The https://github.com/vshn/crossplane-service-broker[_Crossplane Service Broker_] will manage _Crossplane custom resources_ in the same cluster as it runs itself. It must be provided with a least one _service id_ to handle. diff --git a/docs/modules/ROOT/pages/how-tos/crossplane_service_broker/setup_service_catalog.adoc b/docs/modules/ROOT/pages/csp/spks/crossplane/setup_service_catalog.adoc similarity index 96% rename from docs/modules/ROOT/pages/how-tos/crossplane_service_broker/setup_service_catalog.adoc rename to docs/modules/ROOT/pages/csp/spks/crossplane/setup_service_catalog.adoc index 06248478..dee4b19f 100644 --- a/docs/modules/ROOT/pages/how-tos/crossplane_service_broker/setup_service_catalog.adoc +++ b/docs/modules/ROOT/pages/csp/spks/crossplane/setup_service_catalog.adoc @@ -1,4 +1,5 @@ = Install a Service Catalog +:page-aliases: how-tos/crossplane_service_broker/setup_service_catalog.adoc WARNING: This tutorial is deprecated. Some links may not work. diff --git a/docs/modules/ROOT/pages/how-tos/crossplane/enable_plan_upgrade.adoc b/docs/modules/ROOT/pages/csp/spks/enable_plan_upgrade.adoc similarity index 90% rename from docs/modules/ROOT/pages/how-tos/crossplane/enable_plan_upgrade.adoc rename to docs/modules/ROOT/pages/csp/spks/enable_plan_upgrade.adoc index d0cf54b5..dfa90f8b 100644 --- a/docs/modules/ROOT/pages/how-tos/crossplane/enable_plan_upgrade.adoc +++ b/docs/modules/ROOT/pages/csp/spks/enable_plan_upgrade.adoc @@ -1,4 +1,5 @@ = Enable Plan Upgrades +:page-aliases: how-tos/crossplane/enable_plan_upgrade.adoc This page describes the steps which are necessary to enable plan upgrades for both MariaDB and Redis. @@ -18,7 +19,7 @@ We currently support five different plan sizes: * `large` * `xlarge` -You can look at the corresponding xref:app-catalog:ROOT:redis.adoc[Redis] or xref:app-catalog:ROOT:mariadb_galera.adoc[MariaDB] pages to see what these translate to. +You can look at the corresponding xref:csp/spks/redis.adoc[Redis] or xref:csp/spks/mariadb_galera.adoc[MariaDB] pages to see what these translate to. Plan size changes are only supported if the following setup has been done. Updates are only valid from smaller to bigger plan sizes. Shrinking a service instance isn't supported. @@ -64,4 +65,4 @@ This should only ever be enabled if both the StatefulSets Resize Controller depl Enabling plan upgrades at the broker, without these updates can lead to unexpected issues when trying to upgrade plan. ==== -include::../crossplane_service_broker/setup_crossplane_service_broker.adoc[tag=note_update_rule,leveloffset=+1] +include::crossplane/setup_crossplane_service_broker.adoc[tag=note_update_rule,leveloffset=+1] diff --git a/docs/modules/ROOT/pages/how-tos/crossplane/investigate_service_instances.adoc b/docs/modules/ROOT/pages/csp/spks/investigate_service_instances.adoc similarity index 98% rename from docs/modules/ROOT/pages/how-tos/crossplane/investigate_service_instances.adoc rename to docs/modules/ROOT/pages/csp/spks/investigate_service_instances.adoc index 1483c0bc..650ee8f1 100644 --- a/docs/modules/ROOT/pages/how-tos/crossplane/investigate_service_instances.adoc +++ b/docs/modules/ROOT/pages/csp/spks/investigate_service_instances.adoc @@ -1,4 +1,5 @@ = How to Investigate a Service +:page-aliases: how-tos/crossplane/investigate_service_instances.adoc This page shows how a service instance can be investigated. It provides several steps and inputs how to analyze issues, it's generic for all services. diff --git a/docs/modules/ROOT/pages/mariadb_galera.adoc b/docs/modules/ROOT/pages/csp/spks/mariadb_galera.adoc similarity index 76% rename from docs/modules/ROOT/pages/mariadb_galera.adoc rename to docs/modules/ROOT/pages/csp/spks/mariadb_galera.adoc index e9356a16..f708182a 100644 --- a/docs/modules/ROOT/pages/mariadb_galera.adoc +++ b/docs/modules/ROOT/pages/csp/spks/mariadb_galera.adoc @@ -1,9 +1,8 @@ = MariaDB Galera +:page-aliases: mariadb_galera.adoc > tbd -See xref:explanations/mariadb_galera.adoc[Explanation -> MariaDB Galera] for a more detailed technical description of the service. - == Plans Available plans by default: diff --git a/docs/modules/ROOT/pages/explanations/mariadb_galera_lb_with_haproxy.adoc b/docs/modules/ROOT/pages/csp/spks/mariadb_galera_lb_with_haproxy.adoc similarity index 90% rename from docs/modules/ROOT/pages/explanations/mariadb_galera_lb_with_haproxy.adoc rename to docs/modules/ROOT/pages/csp/spks/mariadb_galera_lb_with_haproxy.adoc index b1c0a869..b50dd042 100644 --- a/docs/modules/ROOT/pages/explanations/mariadb_galera_lb_with_haproxy.adoc +++ b/docs/modules/ROOT/pages/csp/spks/mariadb_galera_lb_with_haproxy.adoc @@ -1,4 +1,5 @@ -= HAProxy for MariaDB Galera Load Balancing += HAProxy for MariaDB Galera Load Balancing +:page-aliases: explanations/mariadb_galera_lb_with_haproxy.adoc The HAProxy forwards requests to the available MariaDB Galera cluster nodes. We use DNS discovery based on https://www.haproxy.com/de/blog/dns-service-discovery-haproxy/ to configure HAProxy backends. diff --git a/docs/modules/ROOT/pages/how-tos/haproxy/stats.adoc b/docs/modules/ROOT/pages/csp/spks/mariadb_haproxy_stats.adoc similarity index 92% rename from docs/modules/ROOT/pages/how-tos/haproxy/stats.adoc rename to docs/modules/ROOT/pages/csp/spks/mariadb_haproxy_stats.adoc index 29f5ab0f..a5801120 100644 --- a/docs/modules/ROOT/pages/how-tos/haproxy/stats.adoc +++ b/docs/modules/ROOT/pages/csp/spks/mariadb_haproxy_stats.adoc @@ -1,4 +1,5 @@ = How to Access the HAPRoxy Stats Page +:page-aliases: how-tos/haproxy/stats.adoc HAProxy comes with a https://www.haproxy.com/blog/exploring-the-haproxy-stats-page[stats page] which shows the current state of all front- and backends. It can be very helpful to have an overview of the state of HAProxy. diff --git a/docs/modules/ROOT/pages/explanations/redis.adoc b/docs/modules/ROOT/pages/csp/spks/redis-details.adoc similarity index 97% rename from docs/modules/ROOT/pages/explanations/redis.adoc rename to docs/modules/ROOT/pages/csp/spks/redis-details.adoc index 76e7ae0c..aa19f56f 100644 --- a/docs/modules/ROOT/pages/explanations/redis.adoc +++ b/docs/modules/ROOT/pages/csp/spks/redis-details.adoc @@ -1,4 +1,5 @@ = Redis Service Details +:page-aliases: explanations/redis.adoc == Deployment diff --git a/docs/modules/ROOT/pages/redis.adoc b/docs/modules/ROOT/pages/csp/spks/redis.adoc similarity index 97% rename from docs/modules/ROOT/pages/redis.adoc rename to docs/modules/ROOT/pages/csp/spks/redis.adoc index 07d576c8..074acb79 100644 --- a/docs/modules/ROOT/pages/redis.adoc +++ b/docs/modules/ROOT/pages/csp/spks/redis.adoc @@ -1,4 +1,5 @@ = Redis +:page-aliases: redis.adoc > https://redis.io/[Redis] is an open source (BSD licensed), in-memory data structure store, used as a database, cache, and message broker. Redis provides data structures such as strings, hashes, lists, sets, sorted sets with range queries, bitmaps, hyperloglogs, geospatial indexes, and streams. Redis has built-in replication, Lua scripting, LRU eviction, transactions, and different levels of on-disk persistence, and provides high availability via Redis Sentinel and automatic partitioning with Redis Cluster. diff --git a/docs/modules/ROOT/pages/explanations/redis_fake_sentinel.adoc b/docs/modules/ROOT/pages/csp/spks/redis_fake_sentinel.adoc similarity index 98% rename from docs/modules/ROOT/pages/explanations/redis_fake_sentinel.adoc rename to docs/modules/ROOT/pages/csp/spks/redis_fake_sentinel.adoc index f402c2b3..0c3b1b59 100644 --- a/docs/modules/ROOT/pages/explanations/redis_fake_sentinel.adoc +++ b/docs/modules/ROOT/pages/csp/spks/redis_fake_sentinel.adoc @@ -1,4 +1,5 @@ = Redis Fake Sentinel with HAProxy +:page-aliases: explanations/redis_fake_sentinel.adoc We combine the xref:explanations/redis_sentinel_lb_with_haproxy.adoc[HAProxy for Redis Sentinel load-balancing approach] with the fake Sentinel. This is used so that existing applications which require a Sentinel to connect to and query for the master instance are supported without any changes on client side. diff --git a/docs/modules/ROOT/pages/explanations/redis_sentinel_lb_with_haproxy.adoc b/docs/modules/ROOT/pages/csp/spks/redis_sentinel_lb_with_haproxy.adoc similarity index 94% rename from docs/modules/ROOT/pages/explanations/redis_sentinel_lb_with_haproxy.adoc rename to docs/modules/ROOT/pages/csp/spks/redis_sentinel_lb_with_haproxy.adoc index 063649bc..97be3152 100644 --- a/docs/modules/ROOT/pages/explanations/redis_sentinel_lb_with_haproxy.adoc +++ b/docs/modules/ROOT/pages/csp/spks/redis_sentinel_lb_with_haproxy.adoc @@ -1,4 +1,5 @@ = Redis Sentinel Load Balancing with HAProxy +:page-aliases: explanations/redis_sentinel_lb_with_haproxy.adoc == Installation and Configuration diff --git a/docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraClusterDown.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraClusterDown.adoc similarity index 98% rename from docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraClusterDown.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraClusterDown.adoc index 227f9dd6..3fd69b97 100644 --- a/docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraClusterDown.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraClusterDown.adoc @@ -1,4 +1,5 @@ = Alert rule: MySQLGaleraClusterDown +:page-aliases: runbooks/mariadbgalera/MySQLGaleraClusterDown.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraClusterEvenNodes.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraClusterEvenNodes.adoc similarity index 82% rename from docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraClusterEvenNodes.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraClusterEvenNodes.adoc index e2d722c3..2b5e9522 100644 --- a/docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraClusterEvenNodes.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraClusterEvenNodes.adoc @@ -1,4 +1,5 @@ = Alert rule: MySQLGaleraClusterEvenNodes +:page-aliases: runbooks/mariadbgalera/MySQLGaleraClusterEvenNodes.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraClusterSmall.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraClusterSmall.adoc similarity index 93% rename from docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraClusterSmall.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraClusterSmall.adoc index d333b9d6..5e6e05fa 100644 --- a/docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraClusterSmall.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraClusterSmall.adoc @@ -1,4 +1,5 @@ = Alert rule: MySQLGaleraClusterSmall +:page-aliases: runbooks/mariadbgalera/MySQLGaleraClusterSmall.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraDonorFallingBehind.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraDonorFallingBehind.adoc similarity index 75% rename from docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraDonorFallingBehind.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraDonorFallingBehind.adoc index bf9a5dcd..7b4cfd72 100644 --- a/docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraDonorFallingBehind.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraDonorFallingBehind.adoc @@ -1,4 +1,5 @@ = Alert rule: MySQLGaleraDonorFallingBehind +:page-aliases: runbooks/mariadbgalera/MySQLGaleraDonorFallingBehind.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraNotConnected.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraNotConnected.adoc similarity index 82% rename from docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraNotConnected.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraNotConnected.adoc index 2b3d9db0..6c133b19 100644 --- a/docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraNotConnected.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraNotConnected.adoc @@ -1,4 +1,5 @@ = Alert rule: MySQLGaleraNotConnected +:page-aliases: runbooks/mariadbgalera/MySQLGaleraNotConnected.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraNotOperational.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraNotOperational.adoc similarity index 83% rename from docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraNotOperational.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraNotOperational.adoc index 94ecc9fd..00ea5d16 100644 --- a/docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraNotOperational.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraNotOperational.adoc @@ -1,4 +1,5 @@ = Alert rule: MySQLGaleraNotOperational +:page-aliases: runbooks/mariadbgalera/MySQLGaleraNotOperational.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraNotReady.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraNotReady.adoc similarity index 90% rename from docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraNotReady.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraNotReady.adoc index 418e6441..75e41fbb 100644 --- a/docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraNotReady.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraNotReady.adoc @@ -1,4 +1,5 @@ = Alert rule: MySQLGaleraNotReady +:page-aliases: runbooks/mariadbgalera/MySQLGaleraNotReady.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraOutOfSync.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraOutOfSync.adoc similarity index 92% rename from docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraOutOfSync.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraOutOfSync.adoc index a2f1d8a4..b1430dfa 100644 --- a/docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLGaleraOutOfSync.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLGaleraOutOfSync.adoc @@ -1,4 +1,5 @@ = Alert rule: MySQLGaleraOutOfSync +:page-aliases: runbooks/mariadbgalera/MySQLGaleraOutOfSync.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLInnoDBLogWaits.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLInnoDBLogWaits.adoc similarity index 63% rename from docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLInnoDBLogWaits.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLInnoDBLogWaits.adoc index 7f5016ba..e92ff7e8 100644 --- a/docs/modules/ROOT/pages/runbooks/mariadbgalera/MySQLInnoDBLogWaits.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/MySQLInnoDBLogWaits.adoc @@ -1,4 +1,5 @@ = Alert rule: MySQLInnoDBLogWaits +:page-aliases: runbooks/mariadbgalera/MySQLInnoDBLogWaits.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/how-tos/mariadbgalera/bootstrap_cluster.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/bootstrap_cluster.adoc similarity index 98% rename from docs/modules/ROOT/pages/how-tos/mariadbgalera/bootstrap_cluster.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/bootstrap_cluster.adoc index 7019e5e4..229555c2 100644 --- a/docs/modules/ROOT/pages/how-tos/mariadbgalera/bootstrap_cluster.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/bootstrap_cluster.adoc @@ -1,4 +1,5 @@ = How to Bootstrap a Cluster +:page-aliases: how-tos/mariadbgalera/bootstrap_cluster.adoc [WARNING] ==== diff --git a/docs/modules/ROOT/pages/how-tos/mariadbgalera/debug.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/debug.adoc similarity index 99% rename from docs/modules/ROOT/pages/how-tos/mariadbgalera/debug.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/debug.adoc index 79cf8a09..766c3f11 100644 --- a/docs/modules/ROOT/pages/how-tos/mariadbgalera/debug.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/debug.adoc @@ -1,5 +1,5 @@ = How to Debug MariaDB Galera - +:page-aliases: how-tos/mariadbgalera/debug == Connect to the DB diff --git a/docs/modules/ROOT/pages/how-tos/mariadbgalera/find_cluster_for_instance.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/find_cluster_for_instance.adoc similarity index 85% rename from docs/modules/ROOT/pages/how-tos/mariadbgalera/find_cluster_for_instance.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/find_cluster_for_instance.adoc index 0ccdedb5..37111a6e 100644 --- a/docs/modules/ROOT/pages/how-tos/mariadbgalera/find_cluster_for_instance.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/mariadb_galera/find_cluster_for_instance.adoc @@ -1,4 +1,5 @@ = How to Find the Cluster for a Database Instance +:page-aliases: how-tos/mariadbgalera/find_cluster_for_instance.adoc To find the service cluster on which a database instance was created: diff --git a/docs/modules/ROOT/pages/runbooks/redis/RedisClusterDown.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisClusterDown.adoc similarity index 100% rename from docs/modules/ROOT/pages/runbooks/redis/RedisClusterDown.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisClusterDown.adoc diff --git a/docs/modules/ROOT/pages/runbooks/redis/RedisClusterFlapping.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisClusterFlapping.adoc similarity index 88% rename from docs/modules/ROOT/pages/runbooks/redis/RedisClusterFlapping.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisClusterFlapping.adoc index b53a72d6..c3c82d27 100644 --- a/docs/modules/ROOT/pages/runbooks/redis/RedisClusterFlapping.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisClusterFlapping.adoc @@ -1,4 +1,5 @@ = Alert rule: RedisClusterFlapping +:page-aliases: runbooks/redis/RedisClusterFlapping.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/runbooks/redis/RedisDisconnectedSlaves.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisDisconnectedSlaves.adoc similarity index 88% rename from docs/modules/ROOT/pages/runbooks/redis/RedisDisconnectedSlaves.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisDisconnectedSlaves.adoc index 5a8f5608..aeb1ec29 100644 --- a/docs/modules/ROOT/pages/runbooks/redis/RedisDisconnectedSlaves.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisDisconnectedSlaves.adoc @@ -1,4 +1,5 @@ = Alert rule: RedisDisconnectedSlaves +:page-aliases: runbooks/redis/RedisDisconnectedSlaves.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/runbooks/redis/RedisDown.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisDown.adoc similarity index 90% rename from docs/modules/ROOT/pages/runbooks/redis/RedisDown.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisDown.adoc index 2d6a837f..c1a091a2 100644 --- a/docs/modules/ROOT/pages/runbooks/redis/RedisDown.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisDown.adoc @@ -1,4 +1,5 @@ = Alert rule: RedisDown +:page-aliases: runbooks/redis/RedisDown.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/runbooks/redis/RedisKeyEviction.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisKeyEviction.adoc similarity index 93% rename from docs/modules/ROOT/pages/runbooks/redis/RedisKeyEviction.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisKeyEviction.adoc index bafa1af2..28cbcbca 100644 --- a/docs/modules/ROOT/pages/runbooks/redis/RedisKeyEviction.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisKeyEviction.adoc @@ -1,4 +1,5 @@ = Alert rule: RedisKeyEviction +:page-aliases: runbooks/redis/RedisKeyEviction.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/runbooks/redis/RedisMasterMissing.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisMasterMissing.adoc similarity index 97% rename from docs/modules/ROOT/pages/runbooks/redis/RedisMasterMissing.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisMasterMissing.adoc index a2802976..2cd817ed 100644 --- a/docs/modules/ROOT/pages/runbooks/redis/RedisMasterMissing.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisMasterMissing.adoc @@ -1,4 +1,5 @@ = Alert rule: RedisMasterMissing +:page-aliases: runbooks/redis/RedisMasterMissing.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/runbooks/redis/RedisMemoryHigh.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisMemoryHigh.adoc similarity index 84% rename from docs/modules/ROOT/pages/runbooks/redis/RedisMemoryHigh.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisMemoryHigh.adoc index 194606c4..f1135dab 100644 --- a/docs/modules/ROOT/pages/runbooks/redis/RedisMemoryHigh.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisMemoryHigh.adoc @@ -1,4 +1,5 @@ = Alert rule: RedisMemoryHigh +:page-aliases: runbooks/redis/RedisMemoryHigh.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/runbooks/redis/RedisOutOfMemory.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisOutOfMemory.adoc similarity index 84% rename from docs/modules/ROOT/pages/runbooks/redis/RedisOutOfMemory.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisOutOfMemory.adoc index 73f5f30c..511d8b5f 100644 --- a/docs/modules/ROOT/pages/runbooks/redis/RedisOutOfMemory.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisOutOfMemory.adoc @@ -1,4 +1,5 @@ = Alert rule: RedisOutOfMemory +:page-aliases: runbooks/redis/RedisOutOfMemory.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/runbooks/redis/RedisReplicationBroken.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisReplicationBroken.adoc similarity index 98% rename from docs/modules/ROOT/pages/runbooks/redis/RedisReplicationBroken.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisReplicationBroken.adoc index c3032659..381d3ae8 100644 --- a/docs/modules/ROOT/pages/runbooks/redis/RedisReplicationBroken.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisReplicationBroken.adoc @@ -1,4 +1,5 @@ = Alert rule: RedisReplicationBroken +:page-aliases: runbooks/redis/RedisReplicationBroken.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/runbooks/redis/RedisTooManyMasters.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisTooManyMasters.adoc similarity index 85% rename from docs/modules/ROOT/pages/runbooks/redis/RedisTooManyMasters.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisTooManyMasters.adoc index b79efb2d..95e4d272 100644 --- a/docs/modules/ROOT/pages/runbooks/redis/RedisTooManyMasters.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/RedisTooManyMasters.adoc @@ -1,4 +1,5 @@ = Alert rule: RedisTooManyMasters +:page-aliases: runbooks/redis/RedisTooManyMasters.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/how-tos/redis/debug_sentinel.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/debug_sentinel.adoc similarity index 91% rename from docs/modules/ROOT/pages/how-tos/redis/debug_sentinel.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/redis/debug_sentinel.adoc index 71fad708..87bcf35e 100644 --- a/docs/modules/ROOT/pages/how-tos/redis/debug_sentinel.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/debug_sentinel.adoc @@ -1,4 +1,5 @@ = How to Debug Redis Sentinel +:page-aliases: how-tos/redis/debug_sentinel.adoc Connect to a Redis Sentinel Pod and start a `redis-cli`. diff --git a/docs/modules/ROOT/pages/how-tos/redis/manual_failover.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/manual_failover.adoc similarity index 93% rename from docs/modules/ROOT/pages/how-tos/redis/manual_failover.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/redis/manual_failover.adoc index 8bd8313a..bf8528a6 100644 --- a/docs/modules/ROOT/pages/how-tos/redis/manual_failover.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/manual_failover.adoc @@ -1,4 +1,5 @@ = How to Manually Perform a Redis Failover +:page-aliases: how-tos/redis/manual_failover.adoc In certain situations two of the three Redis nodes end up in `CrashLoopBackOff` because they receive a wrong (old) leader IP address from the running Sentinel. diff --git a/docs/modules/ROOT/pages/how-tos/redis/no_active_leader.adoc b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/no_active_leader.adoc similarity index 91% rename from docs/modules/ROOT/pages/how-tos/redis/no_active_leader.adoc rename to docs/modules/ROOT/pages/csp/spks/runbooks/redis/no_active_leader.adoc index d6b50ff5..150da3f5 100644 --- a/docs/modules/ROOT/pages/how-tos/redis/no_active_leader.adoc +++ b/docs/modules/ROOT/pages/csp/spks/runbooks/redis/no_active_leader.adoc @@ -1,4 +1,5 @@ -= Fix wrong/invalide leader after rollout/update += Fix wrong/invalid leader after rollout/update +:page-aliases: how-tos/redis/no_active_leader.adoc In certain situations it might happen, that the sentinels have the master set to an ip address that doesn't exist anymore (if all pods have been restarted and the IPs changed). The most common thing that happens in this scenario is, that two of the pods are crash looping and one pod is running as a `slave` and has the master set to an IP address that doesn't exist anymore. diff --git a/docs/modules/ROOT/pages/vault.adoc b/docs/modules/ROOT/pages/csp/spks/vault.adoc similarity index 97% rename from docs/modules/ROOT/pages/vault.adoc rename to docs/modules/ROOT/pages/csp/spks/vault.adoc index 22e2cf25..b6906bc0 100644 --- a/docs/modules/ROOT/pages/vault.adoc +++ b/docs/modules/ROOT/pages/csp/spks/vault.adoc @@ -1,4 +1,5 @@ = Vault +:page-aliases: vault.adoc > Manage Secrets and Protect Sensitive Data diff --git a/docs/modules/ROOT/pages/explanations/vault_auto_unseal.adoc b/docs/modules/ROOT/pages/csp/spks/vault_auto_unseal.adoc similarity index 96% rename from docs/modules/ROOT/pages/explanations/vault_auto_unseal.adoc rename to docs/modules/ROOT/pages/csp/spks/vault_auto_unseal.adoc index 782fa7ba..340796dd 100644 --- a/docs/modules/ROOT/pages/explanations/vault_auto_unseal.adoc +++ b/docs/modules/ROOT/pages/csp/spks/vault_auto_unseal.adoc @@ -1,4 +1,5 @@ = Vault: Auto Unseal +:page-aliases: explanations/vault_auto_unseal.adoc A Vault instance needs to be unsealed in order to provide any functionality. See the https://www.vaultproject.io/docs/concepts/seal[docs] for more details. diff --git a/docs/modules/ROOT/pages/explanations/vault_backup_restore.adoc b/docs/modules/ROOT/pages/csp/spks/vault_backup_restore.adoc similarity index 95% rename from docs/modules/ROOT/pages/explanations/vault_backup_restore.adoc rename to docs/modules/ROOT/pages/csp/spks/vault_backup_restore.adoc index 21c66272..c55add76 100644 --- a/docs/modules/ROOT/pages/explanations/vault_backup_restore.adoc +++ b/docs/modules/ROOT/pages/csp/spks/vault_backup_restore.adoc @@ -1,4 +1,5 @@ = Vault: Backup and Restore +:page-aliases: explanations/vault_backup_restore.adoc This page describes how backups and restores of Vault can be done when using the https://www.vaultproject.io/docs/configuration/storage/raft[integrated Raft storage]. See the https://learn.hashicorp.com/tutorials/vault/raft-storage[Raft storage tutorial] for a thorough example. diff --git a/docs/modules/ROOT/pages/explanations/decisions/crossplane.adoc b/docs/modules/ROOT/pages/explanations/decisions/crossplane.adoc deleted file mode 100644 index a61411e4..00000000 --- a/docs/modules/ROOT/pages/explanations/decisions/crossplane.adoc +++ /dev/null @@ -1,24 +0,0 @@ -= Crossplane as Control Plane - -== Problem - -We need a way to deploy services the Kubernetes way, fully automated and reconciled. - -== Proposals - -Crossplane:: -https://crossplane.io/[Crossplane] describes itself: -+ -> Compose cloud infrastructure and services into custom platform APIs. + -> Crossplane is an open source Kubernetes add-on that enables platform teams to assemble infrastructure from multiple vendors, and expose higher level self-service APIs for application teams to consume, without having to write any code. - -Helm Charts:: -Plain Helm Charts, applied with a Helm controller. - -== Decision - -Crossplane - -== Rationale - -We're already using Crossplane and it proves to be working. diff --git a/docs/modules/ROOT/pages/explanations/mariadb_galera.adoc b/docs/modules/ROOT/pages/explanations/mariadb_galera.adoc deleted file mode 100644 index bf196882..00000000 --- a/docs/modules/ROOT/pages/explanations/mariadb_galera.adoc +++ /dev/null @@ -1,5 +0,0 @@ -= MariaDB Galera Service Details - -== Service Access - -See xref:explanations/mariadb_galera_lb_with_haproxy.adoc[HAProxy for MariaDB Galera Load Balancing] for more details. diff --git a/docs/modules/ROOT/pages/how-tos/appcat/backfill_billing.adoc b/docs/modules/ROOT/pages/framework/backfill_billing.adoc similarity index 93% rename from docs/modules/ROOT/pages/how-tos/appcat/backfill_billing.adoc rename to docs/modules/ROOT/pages/framework/backfill_billing.adoc index de392db5..b956d92c 100644 --- a/docs/modules/ROOT/pages/how-tos/appcat/backfill_billing.adoc +++ b/docs/modules/ROOT/pages/framework/backfill_billing.adoc @@ -1,4 +1,5 @@ -= Backfil Billing Data += Backfill Billing Data +:page-aliases: how-tos/appcat/backfill_billing.adoc It might happen that Odoo is down for more than 3 hours. In that case we need to backfill the billing data for VSHN services. diff --git a/docs/modules/ROOT/pages/reference/ci-cd.adoc b/docs/modules/ROOT/pages/framework/ci-cd.adoc similarity index 97% rename from docs/modules/ROOT/pages/reference/ci-cd.adoc rename to docs/modules/ROOT/pages/framework/ci-cd.adoc index d30d5689..e5e33e14 100644 --- a/docs/modules/ROOT/pages/reference/ci-cd.adoc +++ b/docs/modules/ROOT/pages/framework/ci-cd.adoc @@ -1,4 +1,5 @@ -= AppCat CI/CD Processes += CI/CD Processes +:page-aliases: reference/ci-cd.adoc AppCat contains many repositories. They all converge in the `component-appcat`, which is responsible for deploying everything. diff --git a/docs/modules/ROOT/pages/reference/cloud-usage-reporting.adoc b/docs/modules/ROOT/pages/framework/cloud-usage-reporting.adoc similarity index 98% rename from docs/modules/ROOT/pages/reference/cloud-usage-reporting.adoc rename to docs/modules/ROOT/pages/framework/cloud-usage-reporting.adoc index 736353d8..ab5ff169 100644 --- a/docs/modules/ROOT/pages/reference/cloud-usage-reporting.adoc +++ b/docs/modules/ROOT/pages/framework/cloud-usage-reporting.adoc @@ -1,4 +1,5 @@ = Cloud Based AppCat Services +:page-aliases: reference/cloud-usage-reporting.adoc This page explains how cloud based services handle usage reporting. diff --git a/docs/modules/ROOT/pages/reference/framework-requirements.adoc b/docs/modules/ROOT/pages/framework/framework-requirements.adoc similarity index 97% rename from docs/modules/ROOT/pages/reference/framework-requirements.adoc rename to docs/modules/ROOT/pages/framework/framework-requirements.adoc index 6e7afe84..2e3c3c42 100644 --- a/docs/modules/ROOT/pages/reference/framework-requirements.adoc +++ b/docs/modules/ROOT/pages/framework/framework-requirements.adoc @@ -1,4 +1,5 @@ = Framework Requirements +:page-aliases: reference/framework-requirements.adoc As discussed on xref:explanations/what_is.adoc["What is it?"], a *framework* for self-service provisioning of services out of a Kubernetes cluster is a core part of the application catalog. diff --git a/docs/modules/ROOT/pages/reference/quality-requirements.adoc b/docs/modules/ROOT/pages/framework/quality-requirements.adoc similarity index 92% rename from docs/modules/ROOT/pages/reference/quality-requirements.adoc rename to docs/modules/ROOT/pages/framework/quality-requirements.adoc index ca97ae84..0f04af78 100644 --- a/docs/modules/ROOT/pages/reference/quality-requirements.adoc +++ b/docs/modules/ROOT/pages/framework/quality-requirements.adoc @@ -1,4 +1,5 @@ = {product} Quality Requirements +:page-aliases: reference/quality-requirements.adoc These pages contain the formal quality requirements that apply to the {product} framework. They are general descriptions, for specific services please see the service specification. diff --git a/docs/modules/ROOT/pages/reference/quality-requirements/maintainability/readiness-standards.adoc b/docs/modules/ROOT/pages/framework/quality-requirements/maintainability/readiness-standards.adoc similarity index 90% rename from docs/modules/ROOT/pages/reference/quality-requirements/maintainability/readiness-standards.adoc rename to docs/modules/ROOT/pages/framework/quality-requirements/maintainability/readiness-standards.adoc index a4da933f..d0ab86ff 100644 --- a/docs/modules/ROOT/pages/reference/quality-requirements/maintainability/readiness-standards.adoc +++ b/docs/modules/ROOT/pages/framework/quality-requirements/maintainability/readiness-standards.adoc @@ -1,4 +1,5 @@ = Service Production Readiness Standards +:page-aliases: reference/quality-requirements/maintainability/readiness-standards.adoc Source:: {product} Product Owner diff --git a/docs/modules/ROOT/pages/reference/quality-requirements/portability/backup-exports.adoc b/docs/modules/ROOT/pages/framework/quality-requirements/portability/backup-exports.adoc similarity index 90% rename from docs/modules/ROOT/pages/reference/quality-requirements/portability/backup-exports.adoc rename to docs/modules/ROOT/pages/framework/quality-requirements/portability/backup-exports.adoc index c40cb2df..c331097c 100644 --- a/docs/modules/ROOT/pages/reference/quality-requirements/portability/backup-exports.adoc +++ b/docs/modules/ROOT/pages/framework/quality-requirements/portability/backup-exports.adoc @@ -1,4 +1,5 @@ = Backups Can Be Exported +:page-aliases: reference/quality-requirements/portability/backup-exports.adoc Source:: xref:reference/glossary.adoc#service-engineer[Service Engineer] diff --git a/docs/modules/ROOT/pages/reference/quality-requirements/reliability/automatic-updates.adoc b/docs/modules/ROOT/pages/framework/quality-requirements/reliability/automatic-updates.adoc similarity index 91% rename from docs/modules/ROOT/pages/reference/quality-requirements/reliability/automatic-updates.adoc rename to docs/modules/ROOT/pages/framework/quality-requirements/reliability/automatic-updates.adoc index 6c9ad37b..8e9a241e 100644 --- a/docs/modules/ROOT/pages/reference/quality-requirements/reliability/automatic-updates.adoc +++ b/docs/modules/ROOT/pages/framework/quality-requirements/reliability/automatic-updates.adoc @@ -1,4 +1,5 @@ = Automatic Updates +:page-aliases: reference/quality-requirements/reliability/automatic-updates.adoc Source:: {product} Framework diff --git a/docs/modules/ROOT/pages/reference/quality-requirements/reliability/backup-interval.adoc b/docs/modules/ROOT/pages/framework/quality-requirements/reliability/backup-interval.adoc similarity index 84% rename from docs/modules/ROOT/pages/reference/quality-requirements/reliability/backup-interval.adoc rename to docs/modules/ROOT/pages/framework/quality-requirements/reliability/backup-interval.adoc index 38363fba..8a788e80 100644 --- a/docs/modules/ROOT/pages/reference/quality-requirements/reliability/backup-interval.adoc +++ b/docs/modules/ROOT/pages/framework/quality-requirements/reliability/backup-interval.adoc @@ -1,4 +1,5 @@ = Minimum Backup Interval +:page-aliases: reference/quality-requirements/reliability/backup-interval.adoc Source:: xref:reference/glossary.adoc#service-engineer[Service Engineer] diff --git a/docs/modules/ROOT/pages/reference/quality-requirements/reliability/mandatory-updates.adoc b/docs/modules/ROOT/pages/framework/quality-requirements/reliability/mandatory-updates.adoc similarity index 90% rename from docs/modules/ROOT/pages/reference/quality-requirements/reliability/mandatory-updates.adoc rename to docs/modules/ROOT/pages/framework/quality-requirements/reliability/mandatory-updates.adoc index 91a53407..8ee02206 100644 --- a/docs/modules/ROOT/pages/reference/quality-requirements/reliability/mandatory-updates.adoc +++ b/docs/modules/ROOT/pages/framework/quality-requirements/reliability/mandatory-updates.adoc @@ -1,4 +1,5 @@ = Mandatory Updates +:page-aliases: reference/quality-requirements/reliability/mandatory-updates.adoc Source:: xref:reference/glossary.adoc#service-engineer[Service Engineer] diff --git a/docs/modules/ROOT/pages/reference/quality-requirements/usability/actionable-alerts.adoc b/docs/modules/ROOT/pages/framework/quality-requirements/usability/actionable-alerts.adoc similarity index 86% rename from docs/modules/ROOT/pages/reference/quality-requirements/usability/actionable-alerts.adoc rename to docs/modules/ROOT/pages/framework/quality-requirements/usability/actionable-alerts.adoc index e96e99df..ebca8967 100644 --- a/docs/modules/ROOT/pages/reference/quality-requirements/usability/actionable-alerts.adoc +++ b/docs/modules/ROOT/pages/framework/quality-requirements/usability/actionable-alerts.adoc @@ -1,4 +1,5 @@ = Actionable Alerts +:page-aliases: reference/quality-requirements/usability/actionable-alerts.adoc Source:: xref:reference/glossary.adoc#service-engineer[Service Engineer] diff --git a/docs/modules/ROOT/pages/reference/quality-requirements/usability/api-declarative.adoc b/docs/modules/ROOT/pages/framework/quality-requirements/usability/api-declarative.adoc similarity index 90% rename from docs/modules/ROOT/pages/reference/quality-requirements/usability/api-declarative.adoc rename to docs/modules/ROOT/pages/framework/quality-requirements/usability/api-declarative.adoc index cc721029..073d80d1 100644 --- a/docs/modules/ROOT/pages/reference/quality-requirements/usability/api-declarative.adoc +++ b/docs/modules/ROOT/pages/framework/quality-requirements/usability/api-declarative.adoc @@ -1,4 +1,5 @@ = Declarative Configuration of Instances +:page-aliases: reference/quality-requirements/usability/api-declarative.adoc Source:: xref:reference/glossary.adoc#service-user[Service User] diff --git a/docs/modules/ROOT/pages/reference/quality-requirements/usability/api-validation.adoc b/docs/modules/ROOT/pages/framework/quality-requirements/usability/api-validation.adoc similarity index 90% rename from docs/modules/ROOT/pages/reference/quality-requirements/usability/api-validation.adoc rename to docs/modules/ROOT/pages/framework/quality-requirements/usability/api-validation.adoc index 14932ebf..85bd12a1 100644 --- a/docs/modules/ROOT/pages/reference/quality-requirements/usability/api-validation.adoc +++ b/docs/modules/ROOT/pages/framework/quality-requirements/usability/api-validation.adoc @@ -1,4 +1,5 @@ = Service Instance API Validation +:page-aliases: reference/quality-requirements/usability/api-validation.adoc Source:: xref:reference/glossary.adoc#service-user[Service User] diff --git a/docs/modules/ROOT/pages/reference/quality-requirements/usability/logs.adoc b/docs/modules/ROOT/pages/framework/quality-requirements/usability/logs.adoc similarity index 90% rename from docs/modules/ROOT/pages/reference/quality-requirements/usability/logs.adoc rename to docs/modules/ROOT/pages/framework/quality-requirements/usability/logs.adoc index ac0f37b5..2cca8a6b 100644 --- a/docs/modules/ROOT/pages/reference/quality-requirements/usability/logs.adoc +++ b/docs/modules/ROOT/pages/framework/quality-requirements/usability/logs.adoc @@ -1,4 +1,5 @@ = Service Instance Logs +:page-aliases: reference/quality-requirements/usability/logs.adoc Source:: xref:reference/glossary.adoc#service-user[Service User] diff --git a/docs/modules/ROOT/pages/reference/quality-requirements/usability/provisioning-time.adoc b/docs/modules/ROOT/pages/framework/quality-requirements/usability/provisioning-time.adoc similarity index 92% rename from docs/modules/ROOT/pages/reference/quality-requirements/usability/provisioning-time.adoc rename to docs/modules/ROOT/pages/framework/quality-requirements/usability/provisioning-time.adoc index 14be1720..1fbf35ce 100644 --- a/docs/modules/ROOT/pages/reference/quality-requirements/usability/provisioning-time.adoc +++ b/docs/modules/ROOT/pages/framework/quality-requirements/usability/provisioning-time.adoc @@ -1,4 +1,5 @@ = Provisioning Time +:page-aliases: reference/quality-requirements/usability/provisioning-time.adoc Source:: xref:reference/glossary.adoc#service-user[Service User] diff --git a/docs/modules/ROOT/pages/how-tos/appcat/AppCatBackupJobError.adoc b/docs/modules/ROOT/pages/framework/runbooks/AppCatBackupJobError.adoc similarity index 91% rename from docs/modules/ROOT/pages/how-tos/appcat/AppCatBackupJobError.adoc rename to docs/modules/ROOT/pages/framework/runbooks/AppCatBackupJobError.adoc index afb5b6d9..3aeec0c6 100644 --- a/docs/modules/ROOT/pages/how-tos/appcat/AppCatBackupJobError.adoc +++ b/docs/modules/ROOT/pages/framework/runbooks/AppCatBackupJobError.adoc @@ -1,4 +1,5 @@ = Alert rule: AppCatBackupJobError +:page-aliases: how-tos/appcat/AppCatBackupJobError.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/how-tos/appcat/vshn/AppCatHighAvailableDeploymentWarning.adoc b/docs/modules/ROOT/pages/framework/runbooks/AppCatHighAvailableDeploymentWarning.adoc similarity index 87% rename from docs/modules/ROOT/pages/how-tos/appcat/vshn/AppCatHighAvailableDeploymentWarning.adoc rename to docs/modules/ROOT/pages/framework/runbooks/AppCatHighAvailableDeploymentWarning.adoc index f65dad7e..bca414d5 100644 --- a/docs/modules/ROOT/pages/how-tos/appcat/vshn/AppCatHighAvailableDeploymentWarning.adoc +++ b/docs/modules/ROOT/pages/framework/runbooks/AppCatHighAvailableDeploymentWarning.adoc @@ -1,4 +1,5 @@ = Alert rule: AppCatHighAvailableDeploymentWarning +:page-aliases: how-tos/appcat/vshn/AppCatHighAvailableDeploymentWarning.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/how-tos/appcat/vshn/AppCatHighAvailableStatefulsetWarning.adoc b/docs/modules/ROOT/pages/framework/runbooks/AppCatHighAvailableStatefulsetWarning.adoc similarity index 87% rename from docs/modules/ROOT/pages/how-tos/appcat/vshn/AppCatHighAvailableStatefulsetWarning.adoc rename to docs/modules/ROOT/pages/framework/runbooks/AppCatHighAvailableStatefulsetWarning.adoc index a5c63b27..a92a8c31 100644 --- a/docs/modules/ROOT/pages/how-tos/appcat/vshn/AppCatHighAvailableStatefulsetWarning.adoc +++ b/docs/modules/ROOT/pages/framework/runbooks/AppCatHighAvailableStatefulsetWarning.adoc @@ -1,4 +1,5 @@ = Alert rule: AppCatHighAvailableStatefulsetWarning +:page-aliases: how-tos/appcat/vshn/AppCatHighAvailableStatefulsetWarning.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/how-tos/appcat/GuaranteedUptimeTarget.adoc b/docs/modules/ROOT/pages/framework/runbooks/GuaranteedUptimeTarget.adoc similarity index 98% rename from docs/modules/ROOT/pages/how-tos/appcat/GuaranteedUptimeTarget.adoc rename to docs/modules/ROOT/pages/framework/runbooks/GuaranteedUptimeTarget.adoc index 162a8445..8a846a20 100644 --- a/docs/modules/ROOT/pages/how-tos/appcat/GuaranteedUptimeTarget.adoc +++ b/docs/modules/ROOT/pages/framework/runbooks/GuaranteedUptimeTarget.adoc @@ -1,4 +1,5 @@ = Alert rule: GuaranteedUptimeTarget +:page-aliases: how-tos/appcat/GuaranteedUptimeTarget.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/reference/service-maturity.adoc b/docs/modules/ROOT/pages/framework/service-maturity.adoc similarity index 98% rename from docs/modules/ROOT/pages/reference/service-maturity.adoc rename to docs/modules/ROOT/pages/framework/service-maturity.adoc index 682f259e..7ee0daab 100644 --- a/docs/modules/ROOT/pages/reference/service-maturity.adoc +++ b/docs/modules/ROOT/pages/framework/service-maturity.adoc @@ -1,5 +1,5 @@ = Service Maturity -:page-aliases: service-requirements.adoc +:page-aliases: service-requirements.adoc, reference/service-maturity.adoc Implementing and maintaining a service is iterative work. The idea is to release early and release often, without having the urge to have all features available right from the beginning. diff --git a/docs/modules/ROOT/pages/reference/slareports.adoc b/docs/modules/ROOT/pages/framework/slareports.adoc similarity index 90% rename from docs/modules/ROOT/pages/reference/slareports.adoc rename to docs/modules/ROOT/pages/framework/slareports.adoc index c0b37b13..2b97a5ff 100644 --- a/docs/modules/ROOT/pages/reference/slareports.adoc +++ b/docs/modules/ROOT/pages/framework/slareports.adoc @@ -1,4 +1,5 @@ -= AppCat SLA Reports += SLA Reports +:page-aliases: reference/slareports.adoc Currently, the SLA reports for AppCat are generated on the first day of each month and are stored in an S3 bucket. The bucket is provisioned by an AppCat `objectBucket` in the `syn-appcat-slos` namespace on APPUiO Cloud lpg-2. diff --git a/docs/modules/ROOT/pages/reference/vshn-usage-reporting.adoc b/docs/modules/ROOT/pages/framework/vshn-usage-reporting.adoc similarity index 98% rename from docs/modules/ROOT/pages/reference/vshn-usage-reporting.adoc rename to docs/modules/ROOT/pages/framework/vshn-usage-reporting.adoc index a05d7b38..4bde5031 100644 --- a/docs/modules/ROOT/pages/reference/vshn-usage-reporting.adoc +++ b/docs/modules/ROOT/pages/framework/vshn-usage-reporting.adoc @@ -1,4 +1,5 @@ = VSHN Based AppCat Services +:page-aliases: reference/vshn-usage-reporting.adoc This page explains how VSHN based services handle usage reporting. diff --git a/docs/modules/ROOT/pages/how-tos/crossplane/working_with_functions.adoc b/docs/modules/ROOT/pages/framework/working_with_functions.adoc similarity index 99% rename from docs/modules/ROOT/pages/how-tos/crossplane/working_with_functions.adoc rename to docs/modules/ROOT/pages/framework/working_with_functions.adoc index 66d625bd..3aa506aa 100644 --- a/docs/modules/ROOT/pages/how-tos/crossplane/working_with_functions.adoc +++ b/docs/modules/ROOT/pages/framework/working_with_functions.adoc @@ -1,4 +1,4 @@ -= How to work with Crossplane Functions += Working with Crossplane Functions Crossplane introduced `Functions` in version v1.11 as an Alpha feature: https://docs.crossplane.io/knowledge-base/guides/composition-functions. diff --git a/docs/modules/ROOT/pages/reference/glossary.adoc b/docs/modules/ROOT/pages/glossary.adoc similarity index 99% rename from docs/modules/ROOT/pages/reference/glossary.adoc rename to docs/modules/ROOT/pages/glossary.adoc index df40dab6..b6729772 100644 --- a/docs/modules/ROOT/pages/reference/glossary.adoc +++ b/docs/modules/ROOT/pages/glossary.adoc @@ -1,4 +1,5 @@ = Glossary +:page-aliases: reference/glossary.adoc //// You can link these terms using xrefs and their IDs, for example: diff --git a/docs/modules/ROOT/pages/reference/billing-appuio.adoc b/docs/modules/ROOT/pages/reference/billing-appuio.adoc deleted file mode 100644 index 2c52e618..00000000 --- a/docs/modules/ROOT/pages/reference/billing-appuio.adoc +++ /dev/null @@ -1,49 +0,0 @@ -= Billing AppCat services on APPUiO Cloud - -To bill AppCat services on APPUiO Cloud we reuse the APPUiO Cloud billing system. -We make sure that the relevant facts are added to the billing database and the existing system handles the invoice generation. - -This means we need to collect the service resources we want to bill and insert it in the billing database together with the tenant name and in which zone and namespace it runs in. - -To get a deeper understanding of the APPUiO Cloud Billing system, please look at https://kb.vshn.ch/appuio-cloud/references/architecture/metering-data-flow.html[the architecture reference.] - -== Billing Cloud Services - -The collection of billing metrics from cloud providers is handled by the `billing-collector-cloudservices`. -The collector runs periodically as a cronjob and fetches the resource usage from the cloud provider and syncs it to the billing database. - -For objectstorage on cloudscale.ch and Exoscale this means it will collect the reported storage usage for the last day and write it to the database. - -For DBaaS on Exoscale the collector is executed every 15 minutes, fetches the currently running number of databases and will add the number to the billing database. - - -=== References -* https://github.com/vshn/billing-collector-cloudservices[Cloud Service Billing Collector]. -* https://github.com/vshn/billing-collector-cloudservices/tree/master/component[Component to install the cronjobs to fill the billing database] - - -== Billing VSHN managed Services - -VSHN managed services run in a dedicated service namespace on APPUiO Cloud itself. -So we use the metrics collected in Mimir to bill them to our customers. - - -The resource usage of these services are billed directly through the normal APPUiO Cloud billing system, by adding the organization label of the customer to the dedicated namespace. - -We also bill a fixed cost per instance hour. -For this we add all billing relevant information as a label to the service namespace. -This means we add up to three labels: - -* `appcat.vshn.io/servicename`: The name of the service that runs in the namespace. -For example `postgresql-standalone`. -* `appcat.vshn.io/claim-namespace`: The namespace of the claim that resulted in the creation of the service. -* `appcat.vshn.io/sla`: The SLA for the service. -This is usually either `besteffort` or `guaranteed` and can usually be left empty. - -Based on this we get all necessary information by looking at the Prometheus metric `kube_namespace_labels`. -Each hour we run a cronjob that collects the billing metrics from Mimir and writes it to the billing database. - -=== References -* https://github.com/appuio/component-appuio-cloud-reporting[Component to install the cronjobs to fill the billing database] -* https://github.com/appuio/appuio-cloud-reporting/blob/master/pkg/db/seeds/appcat_postgresql_vshn_standalone.promql[Query to collect the number of running PostgreSQL instance] - diff --git a/docs/modules/ROOT/pages/reference/billing-naming.adoc b/docs/modules/ROOT/pages/reference/billing-naming.adoc deleted file mode 100644 index 64832943..00000000 --- a/docs/modules/ROOT/pages/reference/billing-naming.adoc +++ /dev/null @@ -1,73 +0,0 @@ -= Naming Scheme for Billing - -This page specifies various aspects of the AppCatalog billing. - -== Product Naming in the Database - -In order to support all future AppCatalog services and its subproducts, we need to define a naming scheme to differentiate between them. -Each AppCatalog service will have multiple variations. - -.PostgreSQL variation possibilities -[example] -==== -* PostgreSQL standalone without SLA -* PostgreSQL standalone with SLA -* PostgreSQL replicated without SLA -* PostgreSQL replicated with SLA -* PostgreSQL CloudSQL -* PostgreSQL RDS -* PostgreSQL Exoscale -==== - -Every permutation will need an identifier, as it will be associated with a product in the https://kb.vshn.ch/appuio-cloud/references/architecture/metering-data-flow.html#_data_model[product dimension] of the billing database. -Also, depending on the cluster where a given service is running, there could be different prices and discounts. - -To accommodate for all these variations, the default identifier of each product in the database should be as follows: - -$servicename:$provider:$tenant:$namespace:$architecture-$sla - -* `servicename`: The name of the AppCatalog service, in this example PostgreSQL -* `provider`: The provider type of the service, for example `exoscale` or `vshn`. -* `sla`: The name of the applied SLA. There are two values `BestEffort` and `Guaranteed`. The SLA might be omitted for cloud provider instances if they do not apply. -* `architecture`: The architecture of the service. For cloud providers this can be plans (for example Exoscale startup-4). For VSHN Managed Services it's the architecture (for example standalone, cluster, replicated). -* `tenant`: The customer who's invoiced. Usually maps to the `organization` label. -* `namespace`: The namespace where the resource is running. - -More specific product identifiers for special cases are added as needed. -See the "examples" section of the https://kb.vshn.ch/appuio-cloud/references/architecture/metering-data-flow.html#_system_idea[system idea] for more information about how the matching works. - -== Query Names for Reporting - -The query names in the reporting tool should match the naming for the product. - -.Reporting query names: -[example] -==== -* appcat_postgresql_vshn_standalone_besteffort -* appcat_postgresql_vshn_standalone_guaranteed -==== - -== Trivial Prometheus Query Example - -The following is a trivial query that contains all information that is needed to bill a service: - -[source,] ----- -label_replace( - label_replace( - label_replace( - vector(42), <1> - "category", "my-provider:my-namespace", "", "" <2> - ), - "product", "my-product:my-provider:my-tenant:my-namespce:my-architecture-my-sla", "", "" <3> - ), - "tenant", "my-tenant", "", "" <4> -) ----- -<1> Actual query that creates the billable values, for most AppCatalog services, this will be "instance hours" -<2> Category, this value is used for grouping on the invoice -<3> Product source string, this string will be used to do various matching operations during further reporting and enrichment operations -<4> Tenant ID, for matching the tenant - -This example should not be used as a query template, it's only to illustrate what information is required by the billing framework. -Depending on the exporter, the available labels could already contain all necessary information, thus simplifying the query. diff --git a/docs/modules/ROOT/pages/runbooks/_runbooktpl.adoc b/docs/modules/ROOT/pages/runbooks/_runbooktpl.adoc deleted file mode 100644 index da33575c..00000000 --- a/docs/modules/ROOT/pages/runbooks/_runbooktpl.adoc +++ /dev/null @@ -1,9 +0,0 @@ -= Alert rule: ALERTRULENAME - -== icon:glasses[] Overview - -INTRO - -== icon:bug[] Steps for Debugging - -DETAILEDSTEPS diff --git a/docs/modules/ROOT/pages/service/exoscale-dbaas/index.adoc b/docs/modules/ROOT/pages/service/exoscale-dbaas/index.adoc new file mode 100644 index 00000000..434bbe33 --- /dev/null +++ b/docs/modules/ROOT/pages/service/exoscale-dbaas/index.adoc @@ -0,0 +1,18 @@ += Service: Exoscale DBaaS +:svc_name: Exoscale DBaaS +:svc_owner: Schedar +:svc_deploytech: Operator +:svc_doc_enduser: https://docs.appcat.ch/ +:svc_doc_enduser_src: https://github.com/vshn/appcat-user-docs/tree/master/docs/modules/ROOT/pages/exoscale-dbaas +:svc_doc_product: https://products.vshn.ch/appcat/exoscale_dbaas.html +:svc_doc_product_src: https://git.vshn.net/vshn/docs/products/edit/master/docs/modules/ROOT/pages/appcat/exoscale_dbaas.adoc +:svc_code: https://github.com/vshn/appcat/ + +include::partial$service-meta.adoc[] + +== Architecture + +TODO: Brief introduction on the architecture of the service, to get an understanding how it is working. + +== Related adrs + diff --git a/docs/modules/ROOT/pages/how-tos/exoscale_dbaas/price-api.adoc b/docs/modules/ROOT/pages/service/exoscale-dbaas/price-api.adoc similarity index 96% rename from docs/modules/ROOT/pages/how-tos/exoscale_dbaas/price-api.adoc rename to docs/modules/ROOT/pages/service/exoscale-dbaas/price-api.adoc index 27c9a7e2..593abcf2 100644 --- a/docs/modules/ROOT/pages/how-tos/exoscale_dbaas/price-api.adoc +++ b/docs/modules/ROOT/pages/service/exoscale-dbaas/price-api.adoc @@ -1,4 +1,5 @@ = Exoscale Price API +:page-aliases: how-tos/exoscale_dbaas/price-api.adoc Getting and generating prices for the Exoscale DBaaS offering is currently a very hand-knitted process, not much automation in place. Therefore, the documentation here is just some keyword style explanation. diff --git a/docs/modules/ROOT/pages/runbooks/exoscale/restore_dbaas.adoc b/docs/modules/ROOT/pages/service/exoscale-dbaas/runbooks/restore_dbaas.adoc similarity index 99% rename from docs/modules/ROOT/pages/runbooks/exoscale/restore_dbaas.adoc rename to docs/modules/ROOT/pages/service/exoscale-dbaas/runbooks/restore_dbaas.adoc index 52f5e849..87467770 100644 --- a/docs/modules/ROOT/pages/runbooks/exoscale/restore_dbaas.adoc +++ b/docs/modules/ROOT/pages/service/exoscale-dbaas/runbooks/restore_dbaas.adoc @@ -1,4 +1,5 @@ = Manually Restore DBaaS Backup +:page-aliases: runbooks/exoscale/restore_dbaas.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/explanations/decisions/forgejo.adoc b/docs/modules/ROOT/pages/service/forgejo-codey/architecture.adoc similarity index 99% rename from docs/modules/ROOT/pages/explanations/decisions/forgejo.adoc rename to docs/modules/ROOT/pages/service/forgejo-codey/architecture.adoc index ad314330..3e81eada 100644 --- a/docs/modules/ROOT/pages/explanations/decisions/forgejo.adoc +++ b/docs/modules/ROOT/pages/service/forgejo-codey/architecture.adoc @@ -1,4 +1,6 @@ -= Forgejo / Codey += Forgejo / Codey Architecture +:page-aliases: explanations/decisions/forgejo.adoc +:navtitle: Architecture This page discusses the technical details for our two products https://products.vshn.ch/appcat/forgejo.html[Forgejo by VSHN^] and https://products.vshn.ch/codey.html[Codey^]: Fully managed, dedicated https://forgejo.org/[Forgejo^] instances. diff --git a/docs/modules/ROOT/pages/service/forgejo-codey/index.adoc b/docs/modules/ROOT/pages/service/forgejo-codey/index.adoc new file mode 100644 index 00000000..bb0058fb --- /dev/null +++ b/docs/modules/ROOT/pages/service/forgejo-codey/index.adoc @@ -0,0 +1,18 @@ += Service: Forgejo / Codey +:svc_name: Forgejo / Codey +:svc_owner: Schedar +:svc_deploytech: Helm +:svc_doc_enduser: https://docs.appcat.ch/ +:svc_doc_enduser_src: https://github.com/vshn/appcat-user-docs/ +:svc_doc_product: https://products.vshn.ch/appcat/forgejo.html +:svc_doc_product_src: https://git.vshn.net/vshn/docs/products/-/edit/master/docs/modules/ROOT/pages/appcat/forgejo.adoc +:svc_code: https://github.com/vshn/appcat/tree/master/pkg/comp-functions/functions/FUNCTIONNAME + +include::partial$service-meta.adoc[] + +== Architecture + +TODO: Brief introduction on the architecture of the service, to get an understanding how it is working. + +== Related ADRs + diff --git a/docs/modules/ROOT/pages/service/mariadb/index.adoc b/docs/modules/ROOT/pages/service/mariadb/index.adoc new file mode 100644 index 00000000..a73e97b5 --- /dev/null +++ b/docs/modules/ROOT/pages/service/mariadb/index.adoc @@ -0,0 +1,20 @@ += Service: MariaDB +:svc_name: MariaDB +:svc_owner: Schedar +:svc_deploytech: Helm +:svc_doc_enduser: https://docs.appcat.ch/vshn-managed/mariadb/index.html +:svc_doc_enduser_src: https://github.com/vshn/appcat-user-docs/tree/master/docs/modules/ROOT/pages/vshn-managed/mariadb +:svc_doc_product: https://products.vshn.ch/appcat/mariadb.html +:svc_doc_product_src: https://git.vshn.net/vshn/docs/products/-/blob/master/docs/modules/ROOT/pages/appcat/mariadb.adoc +:svc_code: https://github.com/vshn/appcat/tree/master/pkg/comp-functions/functions/vshnmariadb + +include::partial$service-meta.adoc[] + +== Architecture + +TODO: Brief introduction on the architecture of the service, to get an understanding how it is working. + +== Related adrs + +* xref:adr/0008-bitnami-helm-chart-for-mariadb.adoc[] +* xref:adr/0009-proxysql-for-mariadb-clustering.adoc[] diff --git a/docs/modules/ROOT/pages/service/minio/index.adoc b/docs/modules/ROOT/pages/service/minio/index.adoc new file mode 100644 index 00000000..f3f4bf50 --- /dev/null +++ b/docs/modules/ROOT/pages/service/minio/index.adoc @@ -0,0 +1,20 @@ += Service: MinIO +:svc_name: MinIO +:svc_owner: Schedar +:svc_deploytech: Helm +:svc_doc_enduser: https://docs.appcat.ch/ +:svc_doc_enduser_src: https://github.com/vshn/appcat-user-docs/ +:svc_doc_product: https://products.vshn.ch/appcat/minio.html +:svc_doc_product_src: https://git.vshn.net/vshn/docs/products/-/blob/master/docs/modules/ROOT/pages/appcat/minio.adoc +:svc_code: https://github.com/vshn/appcat/tree/master/pkg/comp-functions/functions/vshnminio + +include::partial$service-meta.adoc[] + +== Architecture + +TODO: Brief introduction on the architecture of the service, to get an understanding how it is working. + +== Related adrs + +* xref:adr/0010-minio-for-local-object-storage.adoc[] +* xref:adr/0011-monitor-object-bucket-with-probe.adoc[] diff --git a/docs/modules/ROOT/pages/service/postgresql/index.adoc b/docs/modules/ROOT/pages/service/postgresql/index.adoc new file mode 100644 index 00000000..587bd276 --- /dev/null +++ b/docs/modules/ROOT/pages/service/postgresql/index.adoc @@ -0,0 +1,21 @@ += Service: PostgreSQL +:svc_name: PostgreSQL by VSHN +:svc_owner: Schedar +:svc_deploytech: Operator (Stackgres) +:svc_doc_enduser: https://docs.appcat.ch/vshn-managed/postgresql/index.html +:svc_doc_enduser_src: https://github.com/vshn/appcat-user-docs/tree/master/docs/modules/ROOT/pages/vshn-managed/postgresql +:svc_doc_product: https://products.vshn.ch/appcat/postgresql.html +:svc_doc_product_src: https://git.vshn.net/vshn/docs/products/-/blob/master/docs/modules/ROOT/pages/appcat/postgresql.adoc +:svc_code: https://github.com/vshn/appcat/tree/master/pkg/comp-functions/functions/vshnpostgres + +include::partial$service-meta.adoc[] + +== Architecture + +TODO: Brief introduction on the architecture of the service, to get an understanding how it is working. + +== Related ADRs + +** xref:adr/0003-stackgres-operator-for-postgresql.adoc[] +** xref:adr/0004-postgresql-metrics-exporter.adoc[] +** xref:adr/0005-automated-postgresql-service-upgrades.adoc[] diff --git a/docs/modules/ROOT/pages/how-tos/appcat/vshn/postgres/PostgreSQLConnectionsCritical.adoc b/docs/modules/ROOT/pages/service/postgresql/runbooks/alert-postgresqlconnectionscritical.adoc similarity index 86% rename from docs/modules/ROOT/pages/how-tos/appcat/vshn/postgres/PostgreSQLConnectionsCritical.adoc rename to docs/modules/ROOT/pages/service/postgresql/runbooks/alert-postgresqlconnectionscritical.adoc index 20797636..d22ecc5d 100644 --- a/docs/modules/ROOT/pages/how-tos/appcat/vshn/postgres/PostgreSQLConnectionsCritical.adoc +++ b/docs/modules/ROOT/pages/service/postgresql/runbooks/alert-postgresqlconnectionscritical.adoc @@ -1,4 +1,6 @@ = Alert rule: PostgreSQLConnectionsCritical +:navtitle: PostgreSQLConnectionsCritical +:page-aliases: how-tos/appcat/vshn/postgres/PostgreSQLConnectionsCritical.adoc == icon:glasses[] Overview diff --git a/docs/modules/ROOT/pages/how-tos/appcat/vshn/postgres/manual-restore.adoc b/docs/modules/ROOT/pages/service/postgresql/runbooks/howto-manual-restore.adoc similarity index 98% rename from docs/modules/ROOT/pages/how-tos/appcat/vshn/postgres/manual-restore.adoc rename to docs/modules/ROOT/pages/service/postgresql/runbooks/howto-manual-restore.adoc index 66103177..da17caaa 100644 --- a/docs/modules/ROOT/pages/how-tos/appcat/vshn/postgres/manual-restore.adoc +++ b/docs/modules/ROOT/pages/service/postgresql/runbooks/howto-manual-restore.adoc @@ -1,4 +1,5 @@ -= Restore VSHN PostgreSQL Database in APPUiO Cloud += Restore PostgreSQL by VSHN Database +:page-aliases: how-tos/appcat/vshn/postgres/manual-restore.adoc During emergencies, we need a reliable and a precise solution to restore PostgreSQL databases with Stackgres. This will help reduce significantly the downtime of databases thus resulting in short outage for the customer. diff --git a/docs/modules/ROOT/pages/service/redis/index.adoc b/docs/modules/ROOT/pages/service/redis/index.adoc new file mode 100644 index 00000000..589bb1c1 --- /dev/null +++ b/docs/modules/ROOT/pages/service/redis/index.adoc @@ -0,0 +1,20 @@ += Service: Redis +:svc_name: Redis +:svc_owner: Schedar +:svc_deploytech: Helm +:svc_doc_enduser: https://docs.appcat.ch/vshn-managed/redis/index.html +:svc_doc_enduser_src: https://github.com/vshn/appcat-user-docs/tree/master/docs/modules/ROOT/pages/vshn-managed/redis +:svc_doc_product: https://products.vshn.ch/appcat/redis.html +:svc_doc_product_src: https://git.vshn.net/vshn/docs/products/-/blob/master/docs/modules/ROOT/pages/appcat/redis.adoc +:svc_code: https://github.com/vshn/appcat/tree/master/pkg/comp-functions/functions/vshnredis + +include::partial$service-meta.adoc[] + +== Architecture + +TODO: Brief introduction on the architecture of the service, to get an understanding how it is working. + +== Related adrs + +* xref:adr/0006-bitnami-helm-chart-for-redis.adoc[] +* xref:adr/0007-automated-redis-service-upgrades.adoc[] diff --git a/docs/modules/ROOT/pages/explanations/what_is.adoc b/docs/modules/ROOT/pages/what_is.adoc similarity index 97% rename from docs/modules/ROOT/pages/explanations/what_is.adoc rename to docs/modules/ROOT/pages/what_is.adoc index 3db182c3..d6c13cad 100644 --- a/docs/modules/ROOT/pages/explanations/what_is.adoc +++ b/docs/modules/ROOT/pages/what_is.adoc @@ -1,4 +1,6 @@ = What is the Application Catalog +:page-aliases: explanations/what_is.adoc +:navtitle: What is it? TL;DR:: * A *catalog of services* which can be self-service ordered directly from a Kubernetes cluster (via an well-defined API) diff --git a/docs/modules/ROOT/pages/explanations/why_exists.adoc b/docs/modules/ROOT/pages/why_exists.adoc similarity index 97% rename from docs/modules/ROOT/pages/explanations/why_exists.adoc rename to docs/modules/ROOT/pages/why_exists.adoc index 75479b2b..8389ef49 100644 --- a/docs/modules/ROOT/pages/explanations/why_exists.adoc +++ b/docs/modules/ROOT/pages/why_exists.adoc @@ -1,4 +1,6 @@ = Why does Application Catalog exist? +:page-aliases: explanations/why_exists.adoc +:navtitle: Why does it exist? The application catalog is the successor to the classic VSHN Managed Services on virtual machines, managed by Puppet. It's a very similar concept, applied to Kubernetes, but extended with Cloud services integration, which wasn't available with Puppet. diff --git a/docs/modules/ROOT/partials/adr-meta.adoc b/docs/modules/ROOT/partials/adr-meta.adoc new file mode 100644 index 00000000..5493da04 --- /dev/null +++ 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 new file mode 100644 index 00000000..57f3d6f0 --- /dev/null +++ b/docs/modules/ROOT/partials/nav-adrs.adoc @@ -0,0 +1,29 @@ +** xref:adr/0001-architecture-decision-records.adoc[] +** xref:adr/0002-service-documentation.adoc[] +** xref:adr/0003-stackgres-operator-for-postgresql.adoc[] +** xref:adr/0004-postgresql-metrics-exporter.adoc[] +** xref:adr/0005-automated-postgresql-service-upgrades.adoc[] +** xref:adr/0006-bitnami-helm-chart-for-redis.adoc[] +** xref:adr/0007-automated-redis-service-upgrades.adoc[] +** xref:adr/0008-bitnami-helm-chart-for-mariadb.adoc[] +** xref:adr/0009-proxysql-for-mariadb-clustering.adoc[] +** xref:adr/0010-minio-for-local-object-storage.adoc[] +** xref:adr/0011-monitor-object-bucket-with-probe.adoc[] +** xref:adr/0012-converged-service-in-managed-namespace.adoc[] +** xref:adr/0013-use-logging-facilities-of-platform.adoc[] +** xref:adr/0014-commodore-component-to-deploy-compositions-and-xrds.adoc[] +** xref:adr/0015-metrics-and-monitoring-of-services.adoc[] +** xref:adr/0016-service-api-design.adoc[] +** xref:adr/0017-handling-of-capacity-alerts-for-incident-prevention.adoc[] +** xref:adr/0018-sla-reports-handling.adoc[] +** xref:adr/0019-deletion-protection-with-validating-webhook.adoc[] +** xref:adr/0020-user-management-in-service-instances.adoc[] +** xref:adr/0021-composition-function-error-handling.adoc[] +** xref:adr/0022-replace-api-server-by-custom-resources.adoc[] +** xref:adr/0023-releasee-process-for-appcat-components.adoc[] +** xref:adr/0024-product-choice-for-secret-management.adoc[] +** xref:adr/0025-nextcloud-deployment-with-helm-chart.adoc[] +** xref:adr/0026-mongodb-product.adoc[] +** xref:adr/0027-keycloak-deployment-with-helm-chart.adoc[] +** xref:adr/0028-sli-prober-for-object-storage.adoc[] +** xref:adr/0029-converged-service-provisioning-implementation.adoc[] \ No newline at end of file diff --git a/docs/modules/ROOT/partials/nav.adoc b/docs/modules/ROOT/partials/nav.adoc index daa4a76f..e380df11 100644 --- a/docs/modules/ROOT/partials/nav.adoc +++ b/docs/modules/ROOT/partials/nav.adoc @@ -1,148 +1,121 @@ * xref:index.adoc[Home] -** xref:app-catalog:ROOT:explanations/what_is.adoc[What is it?] -** 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] +** xref:what_is.adoc[] +** xref:why_exists.adoc[] +** xref:concept.adoc[] +** xref:glossary.adoc[] +* xref:service/postgresql/index.adoc[] +** Runbooks +*** xref:service/postgresql/runbooks/alert-postgresqlconnectionscritical.adoc[] +*** xref:service/postgresql/runbooks/howto-manual-restore.adoc[] -*** 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] +* xref:service/redis/index.adoc[] -** Archive -*** xref:app-catalog:ROOT:reference/billing-appuio.adoc[Billing on APPUiO Cloud] -*** xref:app-catalog:ROOT:reference/billing-naming.adoc[] +* xref:service/mariadb/index.adoc[] -* Exoscale -** xref:app-catalog:ROOT:how-tos/exoscale_dbaas/price-api.adoc[Exoscale Price API] -** xref:app-catalog:ROOT:reference/exoscale-osbapi.adoc[] -** Runbooks -*** xref:app-catalog:ROOT:runbooks/exoscale/restore_dbaas.adoc[] +* xref:service/minio/index.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[] -** xref:app-catalog:ROOT:explanations/decisions/forgejo.adoc[Forgejo] -** Archive -*** xref:app-catalog:ROOT:explanations/decisions/archive/converged-service-impl.adoc[Converged Service Provisioning Implementation] +* xref:service/forgejo-codey/index.adoc[] +** xref:service/forgejo-codey/architecture.adoc[] -* 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:service/exoscale-dbaas/index.adoc[] +** xref:service/exoscale-dbaas/price-api.adoc[] +** Runbooks +*** xref:service/exoscale-dbaas/runbooks/restore_dbaas.adoc[] -** 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] +* CSP: Exoscale +** xref:csp/exoscale/osbapi.adoc[] -** 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] +* CSP: APPUiO +** Runbooks +*** xref:csp/appuio/runbooks/appuio-quotas.adoc[] -** 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] +* CSP: SPKS +** xref:csp/spks/investigate_service_instances.adoc[] +** xref:csp/spks/redis.adoc[] +*** xref:csp/spks/redis-details.adoc[] +*** xref:csp/spks/redis_sentinel_lb_with_haproxy.adoc[] +*** xref:csp/spks/redis_fake_sentinel.adoc[] +*** Runbooks +**** xref:csp/spks/runbooks/redis/debug_sentinel.adoc[] +**** xref:csp/spks/runbooks/redis/manual_failover.adoc[] +**** xref:csp/spks/runbooks/redis/no_active_leader.adoc[] +**** xref:csp/spks/runbooks/redis/RedisClusterFlapping.adoc[] +**** xref:csp/spks/runbooks/redis/RedisClusterDown.adoc[] +**** xref:csp/spks/runbooks/redis/RedisDisconnectedSlaves.adoc[] +**** xref:csp/spks/runbooks/redis/RedisDown.adoc[] +**** xref:csp/spks/runbooks/redis/RedisKeyEviction.adoc[] +**** xref:csp/spks/runbooks/redis/RedisMasterMissing.adoc[] +**** xref:csp/spks/runbooks/redis/RedisMemoryHigh.adoc[] +**** xref:csp/spks/runbooks/redis/RedisOutOfMemory.adoc[] +**** xref:csp/spks/runbooks/redis/RedisReplicationBroken.adoc[] +**** xref:csp/spks/runbooks/redis/RedisTooManyMasters.adoc[] +** xref:csp/spks/mariadb_galera.adoc[] +*** xref:csp/spks/mariadb_galera_lb_with_haproxy.adoc[] +*** xref:csp/spks/mariadb_haproxy_stats.adoc[] +*** Runbooks +**** xref:csp/spks/runbooks/mariadb_galera/debug.adoc[] +**** xref:csp/spks/runbooks/mariadb_galera/find_cluster_for_instance.adoc[] +**** xref:csp/spks/runbooks/mariadb_galera/bootstrap_cluster.adoc[] +**** xref:csp/spks/runbooks/mariadb_galera/MySQLGaleraClusterDown.adoc[] +**** xref:csp/spks/runbooks/mariadb_galera/MySQLGaleraClusterEvenNodes.adoc[] +**** xref:csp/spks/runbooks/mariadb_galera/MySQLGaleraClusterSmall.adoc[] +**** xref:csp/spks/runbooks/mariadb_galera/MySQLGaleraDonorFallingBehind.adoc[] +**** xref:csp/spks/runbooks/mariadb_galera/MySQLGaleraNotConnected.adoc[] +**** xref:csp/spks/runbooks/mariadb_galera/MySQLGaleraNotOperational.adoc[] +**** xref:csp/spks/runbooks/mariadb_galera/MySQLGaleraNotReady.adoc[] +**** xref:csp/spks/runbooks/mariadb_galera/MySQLGaleraOutOfSync.adoc[] +**** xref:csp/spks/runbooks/mariadb_galera/MySQLInnoDBLogWaits.adoc[] +** xref:csp/spks/crossplane/overview.adoc[] +*** xref:csp/spks/crossplane/crossplane_service_broker.adoc[] +*** xref:csp/spks/crossplane/crossplane_provider_mechanics.adoc[] +*** xref:csp/spks/crossplane/setup_crossplane_service_broker.adoc[] +*** xref:csp/spks/crossplane/setup_service_catalog.adoc[] +*** xref:csp/spks/crossplane/bearer_token_authentication.adoc[] +*** xref:csp/spks/crossplane/connect_service_catalog_to_service_broker.adoc[] +*** xref:csp/spks/crossplane/kube_token_refresher.adoc[] +*** xref:csp/spks/crossplane/basic_authentication.adoc[] +*** xref:csp/spks/crossplane/implement_new_service_offering.adoc[] +*** xref:csp/spks/crossplane/setting_up_crossplane_service_broker.adoc[] +** xref:csp/spks/vault.adoc[] +*** xref:csp/spks/vault_auto_unseal.adoc[] +*** xref:csp/spks/vault_backup_restore.adoc[] +** xref:csp/spks/enable_plan_upgrade.adoc[] -** xref:app-catalog:ROOT:how-tos/haproxy/stats.adoc[HAProxy] +* Framework +** xref:framework/framework-requirements.adoc[] +** xref:framework/service-maturity.adoc[] +** xref:framework/ci-cd.adoc[] +** xref:framework/working_with_functions.adoc[] +** xref:framework/slareports.adoc[] +** Billing +*** xref:framework/cloud-usage-reporting.adoc[] +*** xref:framework/vshn-usage-reporting.adoc[] +*** xref:framework/backfill_billing.adoc[] +** xref:framework/quality-requirements.adoc[] +*** xref:framework/quality-requirements/maintainability/readiness-standards.adoc[] +*** xref:framework/quality-requirements/portability/backup-exports.adoc[] +*** Reliability +**** xref:framework/quality-requirements/reliability/automatic-updates.adoc[] +**** xref:framework/quality-requirements/reliability/mandatory-updates.adoc[] +**** xref:framework/quality-requirements/reliability/backup-interval.adoc[] +*** Usability +**** xref:framework/quality-requirements/usability/actionable-alerts.adoc[] +**** xref:framework/quality-requirements/usability/api-declarative.adoc[] +**** xref:framework/quality-requirements/usability/api-validation.adoc[] +**** xref:framework/quality-requirements/usability/provisioning-time.adoc[] +**** xref:framework/quality-requirements/usability/logs.adoc[] +** Runbooks +*** xref:framework/runbooks/AppCatBackupJobError.adoc[] +*** xref:framework/runbooks/GuaranteedUptimeTarget.adoc[] +*** xref:framework/runbooks/AppCatHighAvailableStatefulsetWarning.adoc[] +*** xref:framework/runbooks/AppCatHighAvailableDeploymentWarning.adoc[] -* HowTos -** xref:app-catalog:ROOT:how-tos/appcat/backfill_billing.adoc[] +* Control Plane +** xref:control-plane/central-control-plane-arch.adoc[] +** xref:control-plane/split-architecture.adoc[] +** xref:control-plane/split-sli-prober.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:adr/index.adoc[] +** xref:adr/working-with.adoc[] +include::partial$nav-adrs.adoc[] diff --git a/docs/modules/ROOT/partials/service-meta.adoc b/docs/modules/ROOT/partials/service-meta.adoc new file mode 100644 index 00000000..af9e9a8c --- /dev/null +++ b/docs/modules/ROOT/partials/service-meta.adoc @@ -0,0 +1,20 @@ +[.meta-info-table,cols="1h,2"] +|=== +|Service Name +|{svc_name} + +|Owner +|{svc_owner} + +|Deployment Tech +|{svc_deploytech} + +|End-User Documentation +|{svc_doc_enduser}[docs^] - {svc_doc_enduser_src}[source^] + +|Product Documentation +|{svc_doc_product}[docs^] - {svc_doc_product_src}[source^] + +|Code +|{svc_code}[git repo^] +|=== diff --git a/hack/adr-tool.py b/hack/adr-tool.py new file mode 100755 index 00000000..633029b4 --- /dev/null +++ b/hack/adr-tool.py @@ -0,0 +1,120 @@ +#!/usr/bin/env python3 +import re +import sys +import argparse +from pathlib import Path + +EXCLUDED_FILES = ("index.adoc", "working-with.adoc") + + +def validate_adr_status(status): + valid_statuses = [ + "speculative", + "draft", + "accepted", + "rejected", + "implemented", + "obsolete", + ] + + if not status or status.lower() not in valid_statuses: + return False + return True + + +def extract_variables(file_path): + variables = {} + try: + with open(file_path, "r") as f: + content = f.read() + pattern = r":(\w+):\s*(.*)" + matches = re.finditer(pattern, content) + for match in matches: + variables[match.group(1)] = match.group(2).strip() + + title_match = re.search(r"^=\s(.+)$", content, re.MULTILINE) + if title_match: + variables["title"] = title_match.group(1) + except Exception as e: + print(f"Error processing {file_path}: {e}") + return variables + + +def generate_index(adr_dir, output_file): + adr_files = sorted( + [f for f in Path(adr_dir).glob("*.adoc") if f.name not in EXCLUDED_FILES] + ) + + content = """= ADR Index +:navtitle: ADRs + +[cols="3,1,1,1"] +|=== +|Title |Status |Date |Updated + +""" + + for adr_file in adr_files: + vars = extract_variables(adr_file) + filename = Path(adr_file).stem + if vars: + status = vars.get("adr_status", "") + date = vars.get("adr_date", "") + updated = vars.get("adr_upd_date", "") + tags = vars.get("adr_tags", "") + + content += f"|xref:adr/{filename}.adoc[]\n\n`{tags}`\n|{status} |{date} |{updated}\n" + + content += "|===\n" + + with open(output_file, "w") as f: + f.write(content) + + +def validate_adrs(adr_dir): + adr_files = sorted( + [f for f in Path(adr_dir).glob("*.adoc") if f.name not in EXCLUDED_FILES] + ) + has_errors = False + + for adr_file in adr_files: + vars = extract_variables(adr_file) + status = vars.get("adr_status", "") + + if not validate_adr_status(status): + print(f"Error: Invalid status '{status}' in {adr_file}") + has_errors = True + + return has_errors + + +def main(): + parser = argparse.ArgumentParser(description="ADR Index Generator and Validator") + parser.add_argument( + "command", + choices=["generate", "validate"], + help="Command to execute (generate index or validate ADRs)", + ) + # Add optional files argument for pre-commit compatibility + parser.add_argument( + "files", + nargs="*", + help="Files to process (ignored, for pre-commit hook compatibility)", + ) + args = parser.parse_args() + + base_dir = "docs/modules/ROOT/pages/adr" + output_file = f"{base_dir}/index.adoc" + + if args.command == "generate": + generate_index(base_dir, output_file) + print(f"Generated index at {output_file}") + elif args.command == "validate": + has_errors = validate_adrs(base_dir) + if has_errors: + sys.exit(1) + print("All ADR statuses are valid") + + +if __name__ == "__main__": + main() diff --git a/hack/check-nav.py b/hack/check-nav.py new file mode 100755 index 00000000..96a7ce3b --- /dev/null +++ b/hack/check-nav.py @@ -0,0 +1,71 @@ +#!/usr/bin/env python3 +import os +import sys + +# Define the paths +pages_dir = "docs/modules/ROOT/pages" +nav_file = "docs/modules/ROOT/partials/nav.adoc" +additional_nav_file = "docs/modules/ROOT/partials/nav-adrs.adoc" + + +def extract_links(nav_path): + try: + with open(nav_path, "r") as f: + nav_content = f.read() + except FileNotFoundError: + print(f"Navigation file not found: {nav_path}") + sys.exit(1) + links = [] + for line in nav_content.splitlines(): + if "xref:" in line: + start = line.find("xref:") + len("xref:") + end = line.find("[") + if start != -1 and end != -1: + link = line[start:end].strip() + links.append(link) + return links + + +def main(): + # Get the list of all files in the pages directory + pages_files = [] + for root, dirs, files in os.walk(pages_dir): + for file in files: + if file.endswith(".adoc"): + relative_path = os.path.relpath(os.path.join(root, file), pages_dir) + pages_files.append(relative_path) + + # Extract links from both navigation files + nav_links = extract_links(nav_file) + nav_links += extract_links(additional_nav_file) + + error_found = False + + # Check for missing files in the navigation + missing_in_nav = set(pages_files) - set(nav_links) + if missing_in_nav: + print("Files missing in navigation:") + for file in missing_in_nav: + print(f" - {file}") + error_found = True + else: + print("All files are included in the navigation.") + + # Check for broken links in the navigation + broken_links = set(nav_links) - set(pages_files) + if broken_links: + print("Broken links in navigation:") + for link in broken_links: + print(f" - {link}") + error_found = True + else: + print("No broken links in the navigation.") + + if error_found: + sys.exit(1) + else: + sys.exit(0) + + +if __name__ == "__main__": + main() diff --git a/pages b/pages new file mode 120000 index 00000000..f6be4b4d --- /dev/null +++ b/pages @@ -0,0 +1 @@ +docs/modules/ROOT/pages \ No newline at end of file diff --git a/templates/adr/cookiecutter.json b/templates/adr/cookiecutter.json new file mode 100644 index 00000000..db5a496e --- /dev/null +++ b/templates/adr/cookiecutter.json @@ -0,0 +1,40 @@ +{ + "adr_number": "0030", + "full_name": "VSHNeer Name", + "adr_title": "Title", + "adr_reviewers": "", + "adr_owner": [ + "Schedar", + "Aldebaran", + "Nunki", + "Vega" + ], + "adr_date": "{% now 'utc', '%Y-%m-%d' %}", + "adr_upd_date": "{% now 'utc', '%Y-%m-%d' %}", + "adr_status": [ + "draft", + "accepted", + "rejected", + "implemented", + "obsolete" + ], + "adr_tags": "tag1,tag2", + "__prompts__": { + "adr_number": "Number of the ADR (choose the next free)", + "full_name": "Your Name", + "adr_title": "Title of the ADR", + "adr_reviewers": "Name of reviewers", + "adr_owner": "Team who owns the ADR", + "adr_date": "Start date when the ADR was written", + "adr_upd_date": "Date when the ADR was updated (on creation, same as creation date)", + "adr_status": { + "__prompt__": "State of the ADR", + "draft": "Draft - ADR still being worked on - no decision has been taken yet.", + "accepted": "Accepted - The decision is accepted.", + "rejected": "Rejected - ADRs which were accepted and are implemented.", + "implemented": "Implemented - The ADR has been rejected. It's still here for history reasons and to understand why it has been rejected.", + "obsolete": "Obsolete - ADRs kept for historical reasons, but don't reflect the current or impending state of the codebase or project." + }, + "adr_tags": "Comma separated list of tags - all lowercase" + } +} \ No newline at end of file diff --git a/templates/adr/hooks/post_gen_project.py b/templates/adr/hooks/post_gen_project.py new file mode 100644 index 00000000..b930eedd --- /dev/null +++ b/templates/adr/hooks/post_gen_project.py @@ -0,0 +1,62 @@ +import os +import shutil +import json +import glob + +destination_directory = "docs/modules/ROOT/pages/adr" +nav_file = "docs/modules/ROOT/partials/nav-adrs.adoc" +cookiecutter_json = "templates/adr/cookiecutter.json" + +# Current directory is a directory where a cookiecutter template was rendered +current_directory = os.getcwd() + +# Extract ADR number from the current directory name +adr_number = os.path.basename(current_directory) + + +# Find next free ADR number by scanning existing ADR files +def get_next_adr_number(): + adr_files = glob.glob( + f"{os.path.dirname(current_directory)}/{destination_directory}/[0-9]*.adoc" + ) + if not adr_files: + return "0001" + numbers = [int(os.path.basename(f).split("-")[0]) for f in adr_files] + return f"{max(numbers) + 1:04d}" + + +# copytree copies all the contents from current and all nested directories +# from source folder to a destination folder. +shutil.copytree( + current_directory, + f"{os.path.dirname(current_directory)}/{destination_directory}", + dirs_exist_ok=True, +) + +# Update cookiecutter.json with next ADR number +next_number = get_next_adr_number() +try: + json_path = f"{os.path.dirname(current_directory)}/{cookiecutter_json}" + with open(json_path, "r") as f: + config = json.load(f) + config["adr_number"] = next_number + with open(json_path, "w") as f: + json.dump(config, f, indent=4) +except IOError as e: + print(f"Error updating cookiecutter.json: {e}") + + +# Append xref to nav file +nav_path = f"{os.path.dirname(current_directory)}/{nav_file}" +try: + with open(nav_path, "a") as f: + f.write(f"\n** xref:adr/{adr_number}.adoc[]") +except IOError as e: + print(f"Error appending to nav file: {e}") + +# After copying the files we can remove the source directory +shutil.rmtree(current_directory) + +print( + f"====> New ADR document has been created: {destination_directory}/{adr_number}.adoc" +) diff --git a/templates/adr/{{ cookiecutter.adr_number }}-{{ cookiecutter.adr_title | slugify }}/{{ cookiecutter.adr_number }}-{{ cookiecutter.adr_title | slugify }}.adoc b/templates/adr/{{ cookiecutter.adr_number }}-{{ cookiecutter.adr_title | slugify }}/{{ cookiecutter.adr_number }}-{{ cookiecutter.adr_title | slugify }}.adoc new file mode 100644 index 00000000..069e56f2 --- /dev/null +++ b/templates/adr/{{ cookiecutter.adr_number }}-{{ cookiecutter.adr_title | slugify }}/{{ cookiecutter.adr_number }}-{{ cookiecutter.adr_title | slugify }}.adoc @@ -0,0 +1,26 @@ += ADR {{ cookiecutter.adr_number }} - {{ cookiecutter.adr_title }} +:adr_author: {{ cookiecutter.full_name }} +:adr_owner: {{ cookiecutter.adr_owner }} +:adr_reviewers: {{ cookiecutter.adr_reviewers }} +:adr_date: {{ cookiecutter.adr_date }} +:adr_upd_date: {{ cookiecutter.adr_upd_date }} +:adr_status: {{ cookiecutter.adr_status }} +:adr_tags: {{ cookiecutter.adr_tags }} + +include::partial$adr-meta.adoc[] + +[NOTE] +.Summary +==== +Short and concise summary of the decision in this ADR. +==== + +== Context + + + +== Decision + + + +== Consequences diff --git a/templates/cookiecutter.json b/templates/cookiecutter.json new file mode 100644 index 00000000..126e1821 --- /dev/null +++ b/templates/cookiecutter.json @@ -0,0 +1,14 @@ +{ + "templates": { + "adr": { + "path": "./adr", + "title": "ADRs", + "description": "Architecture Design or Decision Record" + }, + "service": { + "path": "./service", + "title": "Service", + "description": "Service Documentation" + } + } +} \ No newline at end of file diff --git a/templates/service/cookiecutter.json b/templates/service/cookiecutter.json new file mode 100644 index 00000000..c14a86e1 --- /dev/null +++ b/templates/service/cookiecutter.json @@ -0,0 +1,32 @@ +{ + "svc_name": "MyService", + "svc_name_lowercase": "{{ cookiecutter.svc_name.lower() }}", + "svc_name_full": "{{ cookiecutter.svc_name }} by VSHN", + "svc_owner": [ + "Schedar", + "Aldebaran", + "Nunki", + "Vega" + ], + "svc_deploytech": [ + "Helm", + "Operator" + ], + "svc_doc_enduser": "https://docs.appcat.ch/vshn-managed/{{ cookiecutter.svc_name.lower() }}/index.html", + "svc_doc_enduser_src": "https://github.com/vshn/appcat-user-docs/tree/master/docs/modules/ROOT/pages/vshn-managed/{{ cookiecutter.svc_name.lower() }}", + "svc_doc_product": "https://products.vshn.ch/appcat/{{ cookiecutter.svc_name.lower() }}.html", + "svc_doc_product_src": "https://git.vshn.net/vshn/docs/products/-/blob/master/docs/modules/ROOT/pages/appcat/{{ cookiecutter.svc_name.lower() }}.adoc", + "svc_code": "https://github.com/vshn/appcat/tree/master/pkg/comp-functions/functions/FUNCTIONNAME", + "__prompts__": { + "svc_name": "Name of the service (correct spelling!)", + "svc_name_lowercase": "Lowercase name of the service", + "svc_name_full": "Full name of the product", + "svc_owner": "Team who owns the service", + "svc_deploytech": "Main technology used for the service", + "svc_doc_enduser": "URL to the End User documentation", + "svc_doc_enduser_src": "URL to the End User documentation Git repository", + "svc_doc_product": "URL to the product documentation", + "svc_doc_product_src": "URL to the product documentation Git repository", + "svc_code": "URL to the Git repository which implements the service (e.g. Composition Function)" + } +} \ No newline at end of file diff --git a/templates/service/hooks/post_gen_project.py b/templates/service/hooks/post_gen_project.py new file mode 100644 index 00000000..1312be9f --- /dev/null +++ b/templates/service/hooks/post_gen_project.py @@ -0,0 +1,12 @@ +import os +import shutil + +destination_directory = "docs/modules/ROOT/pages/service" + +# Current directory is a directory where a cookiecutter template was rendered +current_directory = os.getcwd() + +# Move the entire current directory to the destination directory +shutil.move( + current_directory, f"{os.path.dirname(current_directory)}/{destination_directory}" +) diff --git a/templates/service/{{ cookiecutter.svc_name_lowercase }}/index.adoc b/templates/service/{{ cookiecutter.svc_name_lowercase }}/index.adoc new file mode 100644 index 00000000..71e8b3bd --- /dev/null +++ b/templates/service/{{ cookiecutter.svc_name_lowercase }}/index.adoc @@ -0,0 +1,19 @@ += Service: {{ cookiecutter.svc_name }} +:svc_name: {{ cookiecutter.svc_name }} +:svc_owner: {{ cookiecutter.svc_owner }} +:svc_deploytech: {{ cookiecutter.svc_deploytech }} +:svc_doc_enduser: {{ cookiecutter.svc_doc_enduser }} +:svc_doc_enduser_src: {{ cookiecutter.svc_doc_enduser_src }} +:svc_doc_product: {{ cookiecutter.svc_doc_product }} +:svc_doc_product_src: {{ cookiecutter.svc_doc_product_src }} +:svc_code: {{ cookiecutter.svc_code }} + +include::partial$service-meta.adoc[] + +== Architecture + +TODO: Brief introduction on the architecture of the service, to get an understanding how it is working. + +== Related adrs + +* xref:adr/000X.adoc[]