From 69392454e83ea92a42b73c7d0cbf3e0cb3dcbad5 Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Tue, 31 Dec 2024 15:19:01 +0100 Subject: [PATCH 01/22] initial idea dump --- docs/modules/ROOT/pages/addr/0001.adoc | 18 ++ docs/modules/ROOT/pages/addr/0002.adoc | 18 ++ .../ROOT/pages/service/postgresql.adoc | 18 ++ docs/modules/ROOT/pages/test.adoc | 18 ++ docs/modules/ROOT/partials/addr-meta.adoc | 17 ++ docs/modules/ROOT/partials/nav.adoc | 154 ++---------------- docs/modules/ROOT/partials/nav_orig.adoc | 147 +++++++++++++++++ docs/modules/ROOT/partials/service-meta.adoc | 14 ++ 8 files changed, 266 insertions(+), 138 deletions(-) create mode 100644 docs/modules/ROOT/pages/addr/0001.adoc create mode 100644 docs/modules/ROOT/pages/addr/0002.adoc create mode 100644 docs/modules/ROOT/pages/service/postgresql.adoc create mode 100644 docs/modules/ROOT/pages/test.adoc create mode 100644 docs/modules/ROOT/partials/addr-meta.adoc create mode 100644 docs/modules/ROOT/partials/nav_orig.adoc create mode 100644 docs/modules/ROOT/partials/service-meta.adoc diff --git a/docs/modules/ROOT/pages/addr/0001.adoc b/docs/modules/ROOT/pages/addr/0001.adoc new file mode 100644 index 0000000..873d9b0 --- /dev/null +++ b/docs/modules/ROOT/pages/addr/0001.adoc @@ -0,0 +1,18 @@ += ADDR 0001 - Architecture Design and Decision Records +:addr_author: Tobias Brunner +:addr_owner: Schedar +:addr_reviewers: TBD +:addr_date: 2025-01-01 +:addr_status: draft + +include::partial$addr-meta.adoc[] + +[NOTE] +.Summary +==== +This page describes what ADDRs are ... +==== + +== Introduction + +blubb diff --git a/docs/modules/ROOT/pages/addr/0002.adoc b/docs/modules/ROOT/pages/addr/0002.adoc new file mode 100644 index 0000000..b03c9ec --- /dev/null +++ b/docs/modules/ROOT/pages/addr/0002.adoc @@ -0,0 +1,18 @@ += ADDR 0002 - PostgreSQL stuff +:addr_author: Tobias Brunner +:addr_owner: Schedar +:addr_reviewers: TBD +:addr_date: 2025-01-01 +:addr_status: draft + +include::partial$addr-meta.adoc[] + +[NOTE] +.Summary +==== +This page describes what ADDRs are ... +==== + +== Introduction + +blubb diff --git a/docs/modules/ROOT/pages/service/postgresql.adoc b/docs/modules/ROOT/pages/service/postgresql.adoc new file mode 100644 index 0000000..59ce888 --- /dev/null +++ b/docs/modules/ROOT/pages/service/postgresql.adoc @@ -0,0 +1,18 @@ += Service: PostgreSQL +:svc_name: PostgreSQL by VSHN +:svc_owner: Schedar +:svc_deploytech: Operator (Stackgres) +:svc_status: production + +include::partial$service-meta.adoc[] + +TODO: + +* Service Template - each service must have a page +* Link to product docs +* Link to end-user docs +* Link to service source + +== Related ADDRs + +* xref:addr/0002.adoc[] diff --git a/docs/modules/ROOT/pages/test.adoc b/docs/modules/ROOT/pages/test.adoc new file mode 100644 index 0000000..873d9b0 --- /dev/null +++ b/docs/modules/ROOT/pages/test.adoc @@ -0,0 +1,18 @@ += ADDR 0001 - Architecture Design and Decision Records +:addr_author: Tobias Brunner +:addr_owner: Schedar +:addr_reviewers: TBD +:addr_date: 2025-01-01 +:addr_status: draft + +include::partial$addr-meta.adoc[] + +[NOTE] +.Summary +==== +This page describes what ADDRs are ... +==== + +== Introduction + +blubb diff --git a/docs/modules/ROOT/partials/addr-meta.adoc b/docs/modules/ROOT/partials/addr-meta.adoc new file mode 100644 index 0000000..2793013 --- /dev/null +++ b/docs/modules/ROOT/partials/addr-meta.adoc @@ -0,0 +1,17 @@ +[.meta-info-table,cols="2*"] +|=== +|Author +|{addr_author} + +|Owner +|{addr_owner} + +|Reviewers +|{addr_reviewers} + +|Date +|{addr_date} + +|Status +|[.{addr_status} .status-macro]#{addr_status}# +|=== diff --git a/docs/modules/ROOT/partials/nav.adoc b/docs/modules/ROOT/partials/nav.adoc index ca33bda..37f3ed2 100644 --- a/docs/modules/ROOT/partials/nav.adoc +++ b/docs/modules/ROOT/partials/nav.adoc @@ -3,145 +3,23 @@ ** xref:app-catalog:ROOT:explanations/why_exists.adoc[Why does it exist?] ** xref:app-catalog:ROOT:explanations/app_catalog.adoc[Concept] ** xref:app-catalog:ROOT:reference/glossary.adoc[] -* Architecture -** xref:app-catalog:ROOT:reference/arch-control-plane.adoc[] -** AppCat Usage Reporting -*** xref:app-catalog:ROOT:reference/vshn-usage-reporting.adoc[] -*** xref:app-catalog:ROOT:reference/cloud-usage-reporting.adoc[] -** xref:app-catalog:ROOT:reference/service-maturity.adoc[] -** xref:app-catalog:ROOT:reference/framework-requirements.adoc[] -** xref:app-catalog:ROOT:reference/slareports.adoc[] -** Separate Control Plane from Service Clusters -*** xref:app-catalog:ROOT:reference/control-plane-pitfalls.adoc[] -*** xref:app-catalog:ROOT:reference/sli-prober-architecture.adoc[] -** xref:app-catalog:ROOT:reference/ci-cd.adoc[] -** xref:app-catalog:ROOT:reference/quality-requirements.adoc[Quality Requirements] -*** xref:app-catalog:ROOT:reference/quality-requirements/maintainability/readiness-standards.adoc[Maintainability] -*** xref:app-catalog:ROOT:reference/quality-requirements/portability/backup-exports.adoc[Portability] -*** Reliability -**** xref:app-catalog:ROOT:reference/quality-requirements/reliability/automatic-updates.adoc[Automatic Updates] -**** xref:app-catalog:ROOT:reference/quality-requirements/reliability/mandatory-updates.adoc[Mandatory Updates] -**** xref:app-catalog:ROOT:reference/quality-requirements/reliability/backup-interval.adoc[Minimum Backup Interval] - -*** Usability -**** xref:app-catalog:ROOT:reference/quality-requirements/usability/actionable-alerts.adoc[Actionable Alerts] -**** xref:app-catalog:ROOT:reference/quality-requirements/usability/api-declarative.adoc[Declarative Configuration of Instances] -**** xref:app-catalog:ROOT:reference/quality-requirements/usability/api-validation.adoc[Service Instance API Validation] -**** xref:app-catalog:ROOT:reference/quality-requirements/usability/provisioning-time.adoc[Automated Provisioning of a Service] -**** xref:app-catalog:ROOT:reference/quality-requirements/usability/logs.adoc[Service Instance Logs] - -** Archive -*** xref:app-catalog:ROOT:reference/billing-appuio.adoc[Billing on APPUiO Cloud] -*** xref:app-catalog:ROOT:reference/billing-naming.adoc[] - -* Exoscale -** xref:app-catalog:ROOT:how-tos/exoscale_dbaas/price-api.adoc[Exoscale Price API] -** xref:app-catalog:ROOT:reference/exoscale-osbapi.adoc[] +* xref:service/postgresql.adoc[Service: PostgreSQL] +** Architecture ** Runbooks -*** xref:app-catalog:ROOT:runbooks/exoscale/restore_dbaas.adoc[] +*** xref:app-catalog:ROOT:how-tos/appcat/vshn/postgres/PostgreSQLConnectionsCritical.adoc[] +* Service: SPKS +* Service: Exoscale DBaaS +* Control Plane +* Framework +** CI/CD +** Billing +* Service Providers +** Exoscale +** Cloudscale + +blubb * Decisions -** PostgreSQL by VSHN -*** xref:app-catalog:ROOT:explanations/decisions/postgresql.adoc[Operator evaluation] -*** xref:app-catalog:ROOT:explanations/decisions/postgres-monitoring.adoc[Availability Check] -*** xref:app-catalog:ROOT:explanations/decisions/postgres-upgrades.adoc[Upgrade Policy] -** Redis by VSHN -*** xref:app-catalog:ROOT:explanations/decisions/redis.adoc[Chart evaluation] -*** xref:app-catalog:ROOT:explanations/decisions/redis-upgrades.adoc[Upgrade Policy] -** MariaDB By VSHN -*** xref:app-catalog:ROOT:explanations/decisions/mariadb.adoc[Chart/Operator evaluation] -*** xref:app-catalog:ROOT:explanations/decisions/mariadb-proxy.adoc[Proxy for HA setups] -** ObjectStorage by VSHN -*** xref:app-catalog:ROOT:explanations/decisions/local-objectstorage-provider.adoc[Provider Evaluation] -*** xref:app-catalog:ROOT:explanations/decisions/local-objectstorage-sli.adoc[SLI] -** xref:app-catalog:ROOT:explanations/decisions/nextcloud.adoc[Nextcloud by VSHN] -** xref:app-catalog:ROOT:explanations/decisions/mongodb.adoc[MongoDB by VSHN] -** xref:app-catalog:ROOT:explanations/decisions/secret-pki-mgmt.adoc[Secret and PKI Management by VSHN] -** xref:app-catalog:ROOT:explanations/decisions/capacity-alerting.adoc[Converged Service Capacity Alerting] -** xref:app-catalog:ROOT:explanations/decisions/logging.adoc[Converged Service Logging] -** xref:app-catalog:ROOT:explanations/decisions/crossplane.adoc[Crossplane as Control Plane] -** xref:app-catalog:ROOT:explanations/decisions/composition-deployments.adoc[Composition Deployments] -** xref:app-catalog:ROOT:explanations/decisions/api-design.adoc[API Design] -** xref:app-catalog:ROOT:explanations/decisions/sla-reports.adoc[SLA Reports] -** xref:app-catalog:ROOT:explanations/decisions/converged-service-loc.adoc[Converged Service Provisioning Location] -** xref:app-catalog:ROOT:explanations/decisions/generic-metrics.adoc[] -** xref:app-catalog:ROOT:explanations/decisions/apiserver.adoc[API Server Replacement] -** xref:app-catalog:ROOT:explanations/decisions/deletion-protection.adoc[] -** xref:app-catalog:ROOT:explanations/decisions/user-management.adoc[] -** xref:app-catalog:ROOT:explanations/decisions/comp-function-error-handling.adoc[] -** xref:app-catalog:ROOT:explanations/decisions/release_process.adoc[] -** Archive -*** xref:app-catalog:ROOT:explanations/decisions/archive/converged-service-impl.adoc[Converged Service Provisioning Implementation] - -* SPKS -** xref:redis.adoc[Redis] -*** xref:app-catalog:ROOT:explanations/redis.adoc[Redis Service Details] -*** xref:app-catalog:ROOT:explanations/redis_sentinel_lb_with_haproxy.adoc[Redis Sentinel with HAProxy] -*** xref:app-catalog:ROOT:explanations/redis_fake_sentinel.adoc[Redis Fake Sentinel] -*** xref:app-catalog:ROOT:how-tos/redis/debug_sentinel.adoc[Debug Redis Sentinel] -*** xref:app-catalog:ROOT:how-tos/redis/manual_failover.adoc[Manually Perform a Redis Failover] -*** xref:app-catalog:ROOT:how-tos/redis/no_active_leader.adoc[Fix wrong/invalide leader after rollout/update] -*** Runbooks -**** xref:app-catalog:ROOT:runbooks/redis/RedisClusterFlapping.adoc[RedisClusterFlapping] -**** xref:app-catalog:ROOT:runbooks/redis/RedisDisconnectedSlaves.adoc[RedisDisconnectedSlaves] -**** xref:app-catalog:ROOT:runbooks/redis/RedisDown.adoc[RedisDown] -**** xref:app-catalog:ROOT:runbooks/redis/RedisKeyEviction.adoc[RedisKeyEviction] -**** xref:app-catalog:ROOT:runbooks/redis/RedisMasterMissing.adoc[RedisMasterMissing] -**** xref:app-catalog:ROOT:runbooks/redis/RedisMemoryHigh.adoc[RedisMemoryHigh] -**** xref:app-catalog:ROOT:runbooks/redis/RedisOutOfMemory.adoc[RedisOutOfMemory] -**** xref:app-catalog:ROOT:runbooks/redis/RedisReplicationBroken.adoc[RedisReplicationBroken] -**** xref:app-catalog:ROOT:runbooks/redis/RedisTooManyMasters.adoc[RedisTooManyMasters] - -** xref:mariadb_galera.adoc[MariaDB Galera] -*** xref:app-catalog:ROOT:explanations/decisions/mariadb.adoc[] -*** xref:app-catalog:ROOT:explanations/mariadb_galera_lb_with_haproxy.adoc[MariaDB Galera with HAProxy] -*** xref:app-catalog:ROOT:how-tos/mariadbgalera/debug.adoc[Debug MariaDB Galera] -*** xref:app-catalog:ROOT:how-tos/mariadbgalera/find_cluster_for_instance.adoc[Find the Service Cluster] -*** xref:app-catalog:ROOT:how-tos/mariadbgalera/bootstrap_cluster.adoc[Bootstrap Cluster] -*** Runbooks -**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraClusterDown.adoc[MySQLGaleraClusterDown] -**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraClusterEvenNodes.adoc[MySQLGaleraClusterEvenNodes] -**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraClusterSmall.adoc[MySQLGaleraClusterSmall] -**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraDonorFallingBehind.adoc[MySQLGaleraDonorFallingBehind] -**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraNotConnected.adoc[MySQLGaleraNotConnected] -**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraNotOperational.adoc[MySQLGaleraNotOperational] -**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraNotReady.adoc[MySQLGaleraNotReady] -**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraOutOfSync.adoc[MySQLGaleraOutOfSync] -**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLInnoDBLogWaits.adoc[MySQLInnoDBLogWaits] - -** xref:vault.adoc[Vault] -*** xref:app-catalog:ROOT:explanations/vault_auto_unseal.adoc[Auto Unseal] -*** xref:app-catalog:ROOT:explanations/vault_backup_restore.adoc[Backup and Restore] - -** Crossplane -*** xref:app-catalog:ROOT:how-tos/crossplane/investigate_service_instances.adoc[Investigate a Service] -*** xref:app-catalog:ROOT:how-tos/crossplane/enable_plan_upgrade.adoc[Enable Plan Upgrade] - -** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/overview.adoc[Crossplane Service Broker] -*** xref:app-catalog:ROOT:explanations/crossplane_service_broker.adoc[Service Broker] -*** xref:app-catalog:ROOT:explanations/crossplane_provider_mechanics.adoc[Provider Mechanics] -*** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/setup_crossplane_service_broker.adoc[Setup a _Crossplane Service Broker_] -*** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/setup_service_catalog.adoc[Setup a _Service Catalog_] -*** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/bearer_token_authentication.adoc[HTTP _Bearer Token_ authentication] -*** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/connect_service_catalog_to_service_broker.adoc[Connect the _Service Catalog_ to the _Service Broker_] -*** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/kube_token_refresher.adoc[Setup Kube Token Refresher] -*** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/basic_authentication.adoc[HTTP _Basic_ authentication] -*** xref:app-catalog:ROOT:how-tos/crossplane/implement_new_service_offering.adoc[Implement a New Service] -*** xref:app-catalog:ROOT:tutorials/crossplane_service_broker/setting_up_crossplane_service_broker.adoc[Crossplane Complete Setup Tutorial] - -** xref:app-catalog:ROOT:how-tos/haproxy/stats.adoc[HAProxy] - -* HowTos -** xref:app-catalog:ROOT:how-tos/appcat/backfill_billing.adoc[] - -* Runbooks -** PostgreSQL By VSHN -*** xref:app-catalog:ROOT:how-tos/appcat/vshn/postgres/PostgreSQLConnectionsCritical.adoc[] -** xref:app-catalog:ROOT:how-tos/appcat/appuio-quotas.adoc[] -** xref:app-catalog:ROOT:how-tos/appcat/vshn/postgres/manual-restore.adoc[] -** xref:app-catalog:ROOT:how-tos/appcat/AppCatBackupJobError.adoc[] -** xref:app-catalog:ROOT:how-tos/appcat/GuaranteedUptimeTarget.adoc[] -** High Available Alerts -*** xref:app-catalog:ROOT:how-tos/appcat/vshn/AppCatHighAvailableStatefulsetWarning.adoc[] -*** xref:app-catalog:ROOT:how-tos/appcat/vshn/AppCatHighAvailableDeploymentWarning.adoc[] +** xref:addr/0001.adoc[] +** xref:addr/0002.adoc[] \ No newline at end of file diff --git a/docs/modules/ROOT/partials/nav_orig.adoc b/docs/modules/ROOT/partials/nav_orig.adoc new file mode 100644 index 0000000..ca33bda --- /dev/null +++ b/docs/modules/ROOT/partials/nav_orig.adoc @@ -0,0 +1,147 @@ +* 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] + + +*** Usability +**** xref:app-catalog:ROOT:reference/quality-requirements/usability/actionable-alerts.adoc[Actionable Alerts] +**** xref:app-catalog:ROOT:reference/quality-requirements/usability/api-declarative.adoc[Declarative Configuration of Instances] +**** xref:app-catalog:ROOT:reference/quality-requirements/usability/api-validation.adoc[Service Instance API Validation] +**** xref:app-catalog:ROOT:reference/quality-requirements/usability/provisioning-time.adoc[Automated Provisioning of a Service] +**** xref:app-catalog:ROOT:reference/quality-requirements/usability/logs.adoc[Service Instance Logs] + +** Archive +*** xref:app-catalog:ROOT:reference/billing-appuio.adoc[Billing on APPUiO Cloud] +*** xref:app-catalog:ROOT:reference/billing-naming.adoc[] + +* Exoscale +** xref:app-catalog:ROOT:how-tos/exoscale_dbaas/price-api.adoc[Exoscale Price API] +** xref:app-catalog:ROOT:reference/exoscale-osbapi.adoc[] +** Runbooks +*** xref:app-catalog:ROOT:runbooks/exoscale/restore_dbaas.adoc[] + +* Decisions +** PostgreSQL by VSHN +*** xref:app-catalog:ROOT:explanations/decisions/postgresql.adoc[Operator evaluation] +*** xref:app-catalog:ROOT:explanations/decisions/postgres-monitoring.adoc[Availability Check] +*** xref:app-catalog:ROOT:explanations/decisions/postgres-upgrades.adoc[Upgrade Policy] +** Redis by VSHN +*** xref:app-catalog:ROOT:explanations/decisions/redis.adoc[Chart evaluation] +*** xref:app-catalog:ROOT:explanations/decisions/redis-upgrades.adoc[Upgrade Policy] +** MariaDB By VSHN +*** xref:app-catalog:ROOT:explanations/decisions/mariadb.adoc[Chart/Operator evaluation] +*** xref:app-catalog:ROOT:explanations/decisions/mariadb-proxy.adoc[Proxy for HA setups] +** ObjectStorage by VSHN +*** xref:app-catalog:ROOT:explanations/decisions/local-objectstorage-provider.adoc[Provider Evaluation] +*** xref:app-catalog:ROOT:explanations/decisions/local-objectstorage-sli.adoc[SLI] +** xref:app-catalog:ROOT:explanations/decisions/nextcloud.adoc[Nextcloud by VSHN] +** xref:app-catalog:ROOT:explanations/decisions/mongodb.adoc[MongoDB by VSHN] +** xref:app-catalog:ROOT:explanations/decisions/secret-pki-mgmt.adoc[Secret and PKI Management by VSHN] +** xref:app-catalog:ROOT:explanations/decisions/capacity-alerting.adoc[Converged Service Capacity Alerting] +** xref:app-catalog:ROOT:explanations/decisions/logging.adoc[Converged Service Logging] +** xref:app-catalog:ROOT:explanations/decisions/crossplane.adoc[Crossplane as Control Plane] +** xref:app-catalog:ROOT:explanations/decisions/composition-deployments.adoc[Composition Deployments] +** xref:app-catalog:ROOT:explanations/decisions/api-design.adoc[API Design] +** xref:app-catalog:ROOT:explanations/decisions/sla-reports.adoc[SLA Reports] +** xref:app-catalog:ROOT:explanations/decisions/converged-service-loc.adoc[Converged Service Provisioning Location] +** xref:app-catalog:ROOT:explanations/decisions/generic-metrics.adoc[] +** xref:app-catalog:ROOT:explanations/decisions/apiserver.adoc[API Server Replacement] +** xref:app-catalog:ROOT:explanations/decisions/deletion-protection.adoc[] +** xref:app-catalog:ROOT:explanations/decisions/user-management.adoc[] +** xref:app-catalog:ROOT:explanations/decisions/comp-function-error-handling.adoc[] +** xref:app-catalog:ROOT:explanations/decisions/release_process.adoc[] +** Archive +*** xref:app-catalog:ROOT:explanations/decisions/archive/converged-service-impl.adoc[Converged Service Provisioning Implementation] + +* SPKS +** xref:redis.adoc[Redis] +*** xref:app-catalog:ROOT:explanations/redis.adoc[Redis Service Details] +*** xref:app-catalog:ROOT:explanations/redis_sentinel_lb_with_haproxy.adoc[Redis Sentinel with HAProxy] +*** xref:app-catalog:ROOT:explanations/redis_fake_sentinel.adoc[Redis Fake Sentinel] +*** xref:app-catalog:ROOT:how-tos/redis/debug_sentinel.adoc[Debug Redis Sentinel] +*** xref:app-catalog:ROOT:how-tos/redis/manual_failover.adoc[Manually Perform a Redis Failover] +*** xref:app-catalog:ROOT:how-tos/redis/no_active_leader.adoc[Fix wrong/invalide leader after rollout/update] +*** Runbooks +**** xref:app-catalog:ROOT:runbooks/redis/RedisClusterFlapping.adoc[RedisClusterFlapping] +**** xref:app-catalog:ROOT:runbooks/redis/RedisDisconnectedSlaves.adoc[RedisDisconnectedSlaves] +**** xref:app-catalog:ROOT:runbooks/redis/RedisDown.adoc[RedisDown] +**** xref:app-catalog:ROOT:runbooks/redis/RedisKeyEviction.adoc[RedisKeyEviction] +**** xref:app-catalog:ROOT:runbooks/redis/RedisMasterMissing.adoc[RedisMasterMissing] +**** xref:app-catalog:ROOT:runbooks/redis/RedisMemoryHigh.adoc[RedisMemoryHigh] +**** xref:app-catalog:ROOT:runbooks/redis/RedisOutOfMemory.adoc[RedisOutOfMemory] +**** xref:app-catalog:ROOT:runbooks/redis/RedisReplicationBroken.adoc[RedisReplicationBroken] +**** xref:app-catalog:ROOT:runbooks/redis/RedisTooManyMasters.adoc[RedisTooManyMasters] + +** xref:mariadb_galera.adoc[MariaDB Galera] +*** xref:app-catalog:ROOT:explanations/decisions/mariadb.adoc[] +*** xref:app-catalog:ROOT:explanations/mariadb_galera_lb_with_haproxy.adoc[MariaDB Galera with HAProxy] +*** xref:app-catalog:ROOT:how-tos/mariadbgalera/debug.adoc[Debug MariaDB Galera] +*** xref:app-catalog:ROOT:how-tos/mariadbgalera/find_cluster_for_instance.adoc[Find the Service Cluster] +*** xref:app-catalog:ROOT:how-tos/mariadbgalera/bootstrap_cluster.adoc[Bootstrap Cluster] +*** Runbooks +**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraClusterDown.adoc[MySQLGaleraClusterDown] +**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraClusterEvenNodes.adoc[MySQLGaleraClusterEvenNodes] +**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraClusterSmall.adoc[MySQLGaleraClusterSmall] +**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraDonorFallingBehind.adoc[MySQLGaleraDonorFallingBehind] +**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraNotConnected.adoc[MySQLGaleraNotConnected] +**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraNotOperational.adoc[MySQLGaleraNotOperational] +**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraNotReady.adoc[MySQLGaleraNotReady] +**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLGaleraOutOfSync.adoc[MySQLGaleraOutOfSync] +**** xref:app-catalog:ROOT:runbooks/mariadbgalera/MySQLInnoDBLogWaits.adoc[MySQLInnoDBLogWaits] + +** xref:vault.adoc[Vault] +*** xref:app-catalog:ROOT:explanations/vault_auto_unseal.adoc[Auto Unseal] +*** xref:app-catalog:ROOT:explanations/vault_backup_restore.adoc[Backup and Restore] + +** Crossplane +*** xref:app-catalog:ROOT:how-tos/crossplane/investigate_service_instances.adoc[Investigate a Service] +*** xref:app-catalog:ROOT:how-tos/crossplane/enable_plan_upgrade.adoc[Enable Plan Upgrade] + +** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/overview.adoc[Crossplane Service Broker] +*** xref:app-catalog:ROOT:explanations/crossplane_service_broker.adoc[Service Broker] +*** xref:app-catalog:ROOT:explanations/crossplane_provider_mechanics.adoc[Provider Mechanics] +*** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/setup_crossplane_service_broker.adoc[Setup a _Crossplane Service Broker_] +*** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/setup_service_catalog.adoc[Setup a _Service Catalog_] +*** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/bearer_token_authentication.adoc[HTTP _Bearer Token_ authentication] +*** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/connect_service_catalog_to_service_broker.adoc[Connect the _Service Catalog_ to the _Service Broker_] +*** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/kube_token_refresher.adoc[Setup Kube Token Refresher] +*** xref:app-catalog:ROOT:how-tos/crossplane_service_broker/basic_authentication.adoc[HTTP _Basic_ authentication] +*** xref:app-catalog:ROOT:how-tos/crossplane/implement_new_service_offering.adoc[Implement a New Service] +*** xref:app-catalog:ROOT:tutorials/crossplane_service_broker/setting_up_crossplane_service_broker.adoc[Crossplane Complete Setup Tutorial] + +** xref:app-catalog:ROOT:how-tos/haproxy/stats.adoc[HAProxy] + +* HowTos +** xref:app-catalog:ROOT:how-tos/appcat/backfill_billing.adoc[] + +* Runbooks +** PostgreSQL By VSHN +*** xref:app-catalog:ROOT:how-tos/appcat/vshn/postgres/PostgreSQLConnectionsCritical.adoc[] +** xref:app-catalog:ROOT:how-tos/appcat/appuio-quotas.adoc[] +** xref:app-catalog:ROOT:how-tos/appcat/vshn/postgres/manual-restore.adoc[] +** xref:app-catalog:ROOT:how-tos/appcat/AppCatBackupJobError.adoc[] +** xref:app-catalog:ROOT:how-tos/appcat/GuaranteedUptimeTarget.adoc[] +** High Available Alerts +*** xref:app-catalog:ROOT:how-tos/appcat/vshn/AppCatHighAvailableStatefulsetWarning.adoc[] +*** xref:app-catalog:ROOT:how-tos/appcat/vshn/AppCatHighAvailableDeploymentWarning.adoc[] diff --git a/docs/modules/ROOT/partials/service-meta.adoc b/docs/modules/ROOT/partials/service-meta.adoc new file mode 100644 index 0000000..0d814a2 --- /dev/null +++ b/docs/modules/ROOT/partials/service-meta.adoc @@ -0,0 +1,14 @@ +[.meta-info-table,cols="2*"] +|=== +|Service Name +|{svc_name} + +|Owner +|{svc_owner} + +|Deployment Tech +|{svc_deploytech} + +|Status +|[.{svc_status} .status-macro]#{svc_status}# +|=== From 50c5ef7067fcdc4675687e50cb2e4d074170e92c Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Fri, 3 Jan 2025 11:54:40 +0100 Subject: [PATCH 02/22] initial try at templating with cookiecutter --- templates/service/cookiecutter.json | 19 +++++++++++++++++++ templates/service/hooks/post_gen_project.py | 18 ++++++++++++++++++ ...ookiecutter.service_name_lowercase }}.adoc | 18 ++++++++++++++++++ 3 files changed, 55 insertions(+) create mode 100644 templates/service/cookiecutter.json create mode 100644 templates/service/hooks/post_gen_project.py create mode 100644 templates/service/{{ cookiecutter.service_name_lowercase }}/{{ cookiecutter.service_name_lowercase }}.adoc diff --git a/templates/service/cookiecutter.json b/templates/service/cookiecutter.json new file mode 100644 index 0000000..b8345d4 --- /dev/null +++ b/templates/service/cookiecutter.json @@ -0,0 +1,19 @@ +{ + "service_name": "MyService", + "service_name_lowercase": "{{ cookiecutter.service_name.lower() }}", + "service_name_full": "{{ cookiecutter.service_name }} by VSHN", + "service_owner": [ + "Schedar", + "Aldebaran", + "Nunki", + "Vega" + ], + "service_deploytech": [ + "Helm", + "Operator" + ], + "service_status": [ + "production", + "development" + ] +} \ 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 0000000..293fb53 --- /dev/null +++ b/templates/service/hooks/post_gen_project.py @@ -0,0 +1,18 @@ +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() + +# 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, +) + +# After copying the files we can remove the source directory +shutil.rmtree(current_directory) diff --git a/templates/service/{{ cookiecutter.service_name_lowercase }}/{{ cookiecutter.service_name_lowercase }}.adoc b/templates/service/{{ cookiecutter.service_name_lowercase }}/{{ cookiecutter.service_name_lowercase }}.adoc new file mode 100644 index 0000000..4e7d0cc --- /dev/null +++ b/templates/service/{{ cookiecutter.service_name_lowercase }}/{{ cookiecutter.service_name_lowercase }}.adoc @@ -0,0 +1,18 @@ += Service: {{ cookiecutter.service_name }} +:svc_name: {{ cookiecutter.service_name_full }} +:svc_owner: {{ cookiecutter.service_owner }} +:svc_deploytech: {{ cookiecutter.service_deploytech }} +:svc_status: {{ cookiecutter.service_status }} + +include::partial$service-meta.adoc[] + +TODO: + +* Service Template - each service must have a page +* Link to product docs +* Link to end-user docs +* Link to service source + +== Related ADDRs + +* xref:addr/0002.adoc[] \ No newline at end of file From 47eac433eb229d25b60571823e73b7e4a61bddd1 Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Fri, 3 Jan 2025 15:49:53 +0100 Subject: [PATCH 03/22] addr is now adr and cookiecutter templates --- docs/modules/ROOT/pages/addr/0001.adoc | 18 --------- docs/modules/ROOT/pages/addr/0002.adoc | 18 --------- docs/modules/ROOT/pages/adr/0001.adoc | 18 +++++++++ docs/modules/ROOT/pages/adr/0002.adoc | 18 +++++++++ .../ROOT/pages/service/postgresql.adoc | 4 +- docs/modules/ROOT/pages/test.adoc | 18 --------- docs/modules/ROOT/partials/addr-meta.adoc | 17 --------- docs/modules/ROOT/partials/adr-meta.adoc | 17 +++++++++ docs/modules/ROOT/partials/nav-adrs.adoc | 2 + docs/modules/ROOT/partials/nav.adoc | 7 +--- templates/adr/cookiecutter.json | 38 +++++++++++++++++++ templates/adr/hooks/post_gen_project.py | 30 +++++++++++++++ .../{{ cookiecutter.adr_number }}.adoc | 18 +++++++++ templates/cookiecutter.json | 14 +++++++ ...ookiecutter.service_name_lowercase }}.adoc | 4 +- 15 files changed, 161 insertions(+), 80 deletions(-) delete mode 100644 docs/modules/ROOT/pages/addr/0001.adoc delete mode 100644 docs/modules/ROOT/pages/addr/0002.adoc create mode 100644 docs/modules/ROOT/pages/adr/0001.adoc create mode 100644 docs/modules/ROOT/pages/adr/0002.adoc delete mode 100644 docs/modules/ROOT/pages/test.adoc delete mode 100644 docs/modules/ROOT/partials/addr-meta.adoc create mode 100644 docs/modules/ROOT/partials/adr-meta.adoc create mode 100644 docs/modules/ROOT/partials/nav-adrs.adoc create mode 100644 templates/adr/cookiecutter.json create mode 100644 templates/adr/hooks/post_gen_project.py create mode 100644 templates/adr/{{ cookiecutter.adr_number }}/{{ cookiecutter.adr_number }}.adoc create mode 100644 templates/cookiecutter.json diff --git a/docs/modules/ROOT/pages/addr/0001.adoc b/docs/modules/ROOT/pages/addr/0001.adoc deleted file mode 100644 index 873d9b0..0000000 --- a/docs/modules/ROOT/pages/addr/0001.adoc +++ /dev/null @@ -1,18 +0,0 @@ -= ADDR 0001 - Architecture Design and Decision Records -:addr_author: Tobias Brunner -:addr_owner: Schedar -:addr_reviewers: TBD -:addr_date: 2025-01-01 -:addr_status: draft - -include::partial$addr-meta.adoc[] - -[NOTE] -.Summary -==== -This page describes what ADDRs are ... -==== - -== Introduction - -blubb diff --git a/docs/modules/ROOT/pages/addr/0002.adoc b/docs/modules/ROOT/pages/addr/0002.adoc deleted file mode 100644 index b03c9ec..0000000 --- a/docs/modules/ROOT/pages/addr/0002.adoc +++ /dev/null @@ -1,18 +0,0 @@ -= ADDR 0002 - PostgreSQL stuff -:addr_author: Tobias Brunner -:addr_owner: Schedar -:addr_reviewers: TBD -:addr_date: 2025-01-01 -:addr_status: draft - -include::partial$addr-meta.adoc[] - -[NOTE] -.Summary -==== -This page describes what ADDRs are ... -==== - -== Introduction - -blubb diff --git a/docs/modules/ROOT/pages/adr/0001.adoc b/docs/modules/ROOT/pages/adr/0001.adoc new file mode 100644 index 0000000..882bd00 --- /dev/null +++ b/docs/modules/ROOT/pages/adr/0001.adoc @@ -0,0 +1,18 @@ += ADR 0001 - Architecture Design or Decision Records +:adr_author: Tobias Brunner +:adr_owner: Schedar +:adr_reviewers: TBD +:adr_date: 2025-01-01 +:adr_status: draft + +include::partial$adr-meta.adoc[] + +[NOTE] +.Summary +==== +This page describes what ADRs are ... +==== + +== Introduction + +blubb diff --git a/docs/modules/ROOT/pages/adr/0002.adoc b/docs/modules/ROOT/pages/adr/0002.adoc new file mode 100644 index 0000000..1cebc1c --- /dev/null +++ b/docs/modules/ROOT/pages/adr/0002.adoc @@ -0,0 +1,18 @@ += ADR 0002 - PostgreSQL stuff +:adr_author: Tobias Brunner +:adr_owner: Schedar +:adr_reviewers: TBD +:adr_date: 2025-01-01 +:adr_status: draft + +include::partial$adr-meta.adoc[] + +[NOTE] +.Summary +==== +This page describes what ADRs are ... +==== + +== Introduction + +blubb diff --git a/docs/modules/ROOT/pages/service/postgresql.adoc b/docs/modules/ROOT/pages/service/postgresql.adoc index 59ce888..ba6e52c 100644 --- a/docs/modules/ROOT/pages/service/postgresql.adoc +++ b/docs/modules/ROOT/pages/service/postgresql.adoc @@ -13,6 +13,6 @@ TODO: * Link to end-user docs * Link to service source -== Related ADDRs +== Related ADRs -* xref:addr/0002.adoc[] +* xref:adr/0002.adoc[] diff --git a/docs/modules/ROOT/pages/test.adoc b/docs/modules/ROOT/pages/test.adoc deleted file mode 100644 index 873d9b0..0000000 --- a/docs/modules/ROOT/pages/test.adoc +++ /dev/null @@ -1,18 +0,0 @@ -= ADDR 0001 - Architecture Design and Decision Records -:addr_author: Tobias Brunner -:addr_owner: Schedar -:addr_reviewers: TBD -:addr_date: 2025-01-01 -:addr_status: draft - -include::partial$addr-meta.adoc[] - -[NOTE] -.Summary -==== -This page describes what ADDRs are ... -==== - -== Introduction - -blubb diff --git a/docs/modules/ROOT/partials/addr-meta.adoc b/docs/modules/ROOT/partials/addr-meta.adoc deleted file mode 100644 index 2793013..0000000 --- a/docs/modules/ROOT/partials/addr-meta.adoc +++ /dev/null @@ -1,17 +0,0 @@ -[.meta-info-table,cols="2*"] -|=== -|Author -|{addr_author} - -|Owner -|{addr_owner} - -|Reviewers -|{addr_reviewers} - -|Date -|{addr_date} - -|Status -|[.{addr_status} .status-macro]#{addr_status}# -|=== diff --git a/docs/modules/ROOT/partials/adr-meta.adoc b/docs/modules/ROOT/partials/adr-meta.adoc new file mode 100644 index 0000000..ff40752 --- /dev/null +++ b/docs/modules/ROOT/partials/adr-meta.adoc @@ -0,0 +1,17 @@ +[.meta-info-table,cols="2*"] +|=== +|Author +|{adr_author} + +|Owner +|{adr_owner} + +|Reviewers +|{adr_reviewers} + +|Date +|{adr_date} + +|Status +|[.{adr_status} .status-macro]#{adr_status}# +|=== diff --git a/docs/modules/ROOT/partials/nav-adrs.adoc b/docs/modules/ROOT/partials/nav-adrs.adoc new file mode 100644 index 0000000..a0f94cd --- /dev/null +++ b/docs/modules/ROOT/partials/nav-adrs.adoc @@ -0,0 +1,2 @@ +** xref:adr/0001.adoc[] +** xref:adr/0002.adoc[] diff --git a/docs/modules/ROOT/partials/nav.adoc b/docs/modules/ROOT/partials/nav.adoc index 37f3ed2..c24bbba 100644 --- a/docs/modules/ROOT/partials/nav.adoc +++ b/docs/modules/ROOT/partials/nav.adoc @@ -18,8 +18,5 @@ ** Exoscale ** Cloudscale -blubb - -* Decisions -** xref:addr/0001.adoc[] -** xref:addr/0002.adoc[] \ No newline at end of file +* ADRs +include::partial$nav-adrs.adoc[] \ No newline at end of file diff --git a/templates/adr/cookiecutter.json b/templates/adr/cookiecutter.json new file mode 100644 index 0000000..b0e5e87 --- /dev/null +++ b/templates/adr/cookiecutter.json @@ -0,0 +1,38 @@ +{ + "adr_number": "00XX", + "full_name": "VSHNeer Name", + "adr_title": "Title", + "adr_reviewers": "", + "adr_owner": [ + "Schedar", + "Aldebaran", + "Nunki", + "Vega" + ], + "adr_date": "{% now 'utc', '%Y-%m-%d' %}", + "adr_status": [ + "speculative", + "draft", + "accepted", + "rejected", + "implemented", + "obsolete" + ], + "__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_status": { + "__prompt__": "State of the ADR", + "draft": "Draft - designs strive toward acceptance. Designs may exist in draft for some time as we experiment and learn, but their ultimate goal is to become an accepted design.", + "speculative": "Speculative - designs explore an idea without yet explicitly proposing a change be made.", + "accepted": "Accepted - designs will be implemented.", + "rejected": "Rejected - designs won’t be implemented.", + "implemented": "Implemented - designs which were accepted and are implemented.", + "obsolete": "Obsolete - designs are kept for historical reasons, but don’t reflect the current or impending state of the codebase or project." + } + } +} \ 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 0000000..c07f6f1 --- /dev/null +++ b/templates/adr/hooks/post_gen_project.py @@ -0,0 +1,30 @@ +import os +import shutil + +destination_directory = "docs/modules/ROOT/pages/adr" +nav_file = "docs/modules/ROOT/partials/nav-adrs.adoc" + +# 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) + +# 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, +) + +# 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) diff --git a/templates/adr/{{ cookiecutter.adr_number }}/{{ cookiecutter.adr_number }}.adoc b/templates/adr/{{ cookiecutter.adr_number }}/{{ cookiecutter.adr_number }}.adoc new file mode 100644 index 0000000..eefe5f8 --- /dev/null +++ b/templates/adr/{{ cookiecutter.adr_number }}/{{ cookiecutter.adr_number }}.adoc @@ -0,0 +1,18 @@ += 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_status: {{ cookiecutter.adr_status }} + +include::partial$adr-meta.adoc[] + +[NOTE] +.Summary +==== +TODO +==== + +== Introduction + +blubb diff --git a/templates/cookiecutter.json b/templates/cookiecutter.json new file mode 100644 index 0000000..126e182 --- /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.service_name_lowercase }}/{{ cookiecutter.service_name_lowercase }}.adoc b/templates/service/{{ cookiecutter.service_name_lowercase }}/{{ cookiecutter.service_name_lowercase }}.adoc index 4e7d0cc..08a0799 100644 --- a/templates/service/{{ cookiecutter.service_name_lowercase }}/{{ cookiecutter.service_name_lowercase }}.adoc +++ b/templates/service/{{ cookiecutter.service_name_lowercase }}/{{ cookiecutter.service_name_lowercase }}.adoc @@ -13,6 +13,6 @@ TODO: * Link to end-user docs * Link to service source -== Related ADDRs +== Related adrs -* xref:addr/0002.adoc[] \ No newline at end of file +* xref:adr/0002.adoc[] \ No newline at end of file From 3ff8095767a686dca2ddc9dcd85391d651014ad9 Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Fri, 3 Jan 2025 16:33:07 +0100 Subject: [PATCH 04/22] wip including index creation tool --- docs/modules/ROOT/pages/adr/0001.adoc | 21 +++++-- docs/modules/ROOT/pages/adr/index.adoc | 10 +++ .../ROOT/pages/service/postgresql.adoc | 7 +-- docs/modules/ROOT/partials/nav.adoc | 4 +- docs/modules/ROOT/partials/service-meta.adoc | 11 +++- hack/generate_adr_index.py | 63 +++++++++++++++++++ 6 files changed, 104 insertions(+), 12 deletions(-) create mode 100644 docs/modules/ROOT/pages/adr/index.adoc create mode 100644 hack/generate_adr_index.py diff --git a/docs/modules/ROOT/pages/adr/0001.adoc b/docs/modules/ROOT/pages/adr/0001.adoc index 882bd00..f8a94eb 100644 --- a/docs/modules/ROOT/pages/adr/0001.adoc +++ b/docs/modules/ROOT/pages/adr/0001.adoc @@ -1,4 +1,4 @@ -= ADR 0001 - Architecture Design or Decision Records += ADR 0001 - Architecture Decision Records :adr_author: Tobias Brunner :adr_owner: Schedar :adr_reviewers: TBD @@ -10,9 +10,22 @@ include::partial$adr-meta.adoc[] [NOTE] .Summary ==== -This page describes what ADRs are ... +Architecture Decision Records (ADR) are a way to document decisions, ideas, architecture and other important aspects of the engineering process. ==== -== Introduction +== Problem -blubb +ADRs follow a certain structure, to make it easier to write them and to have a concise way of documenting things. + +== Relevant requirements + +== Relevant decisions + +== Proposals + +== Decision + +We use the existing structure from https://kb.vshn.ch/corp-tech/documents/document-decisions.html[VSHN Corporate Technology / How to read and document decisions]. + + +== Rationale diff --git a/docs/modules/ROOT/pages/adr/index.adoc b/docs/modules/ROOT/pages/adr/index.adoc new file mode 100644 index 0000000..411de3d --- /dev/null +++ b/docs/modules/ROOT/pages/adr/index.adoc @@ -0,0 +1,10 @@ += ADR Index +:navtitle: ADRs + +[cols="1,2,1,1,1,1"] +|=== +|Number |Title |Author |Owner |Status |Date + +|xref:adr/0001.adoc[0001] |ADR 0001 - Architecture Decision Records |Tobias Brunner |Schedar |draft |2025-01-01 +|xref:adr/0002.adoc[0002] |ADR 0002 - PostgreSQL stuff |Tobias Brunner |Schedar |draft |2025-01-01 +|=== diff --git a/docs/modules/ROOT/pages/service/postgresql.adoc b/docs/modules/ROOT/pages/service/postgresql.adoc index ba6e52c..26efb0c 100644 --- a/docs/modules/ROOT/pages/service/postgresql.adoc +++ b/docs/modules/ROOT/pages/service/postgresql.adoc @@ -6,12 +6,9 @@ include::partial$service-meta.adoc[] -TODO: +== Architecture -* Service Template - each service must have a page -* Link to product docs -* Link to end-user docs -* Link to service source +Brief introduction on the architecture of the service, to get an understanding how it is working. == Related ADRs diff --git a/docs/modules/ROOT/partials/nav.adoc b/docs/modules/ROOT/partials/nav.adoc index c24bbba..33422a8 100644 --- a/docs/modules/ROOT/partials/nav.adoc +++ b/docs/modules/ROOT/partials/nav.adoc @@ -5,9 +5,9 @@ ** xref:app-catalog:ROOT:reference/glossary.adoc[] * xref:service/postgresql.adoc[Service: PostgreSQL] -** Architecture ** Runbooks *** xref:app-catalog:ROOT:how-tos/appcat/vshn/postgres/PostgreSQLConnectionsCritical.adoc[] +*** xref:app-catalog:ROOT:how-tos/appcat/vshn/postgres/manual-restore.adoc[] * Service: SPKS * Service: Exoscale DBaaS * Control Plane @@ -18,5 +18,5 @@ ** Exoscale ** Cloudscale -* ADRs +* xref:adr/index.adoc[] include::partial$nav-adrs.adoc[] \ No newline at end of file diff --git a/docs/modules/ROOT/partials/service-meta.adoc b/docs/modules/ROOT/partials/service-meta.adoc index 0d814a2..61cfb01 100644 --- a/docs/modules/ROOT/partials/service-meta.adoc +++ b/docs/modules/ROOT/partials/service-meta.adoc @@ -1,4 +1,4 @@ -[.meta-info-table,cols="2*"] +[.meta-info-table,cols="1h,2"] |=== |Service Name |{svc_name} @@ -11,4 +11,13 @@ |Status |[.{svc_status} .status-macro]#{svc_status}# + +|End-User Documentation +|https://docs.appcat.ch/vshn-managed/postgresql/index.html[docs.appcat.ch^] - https://github.com/vshn/appcat-user-docs/tree/master/docs/modules/ROOT/pages/vshn-managed/postgresql[source^] + +|Product Documentation +|https://products.vshn.ch/appcat/postgresql.html[products.vshn.ch^] - https://git.vshn.net/vshn/docs/products/-/blob/master/docs/modules/ROOT/pages/appcat/postgresql.adoc[source^] + +|Code +|https://github.com/vshn/appcat[github.com/vshn/appcat^] |=== diff --git a/hack/generate_adr_index.py b/hack/generate_adr_index.py new file mode 100644 index 0000000..cf4bfaf --- /dev/null +++ b/hack/generate_adr_index.py @@ -0,0 +1,63 @@ +import re +from pathlib import Path + + +def extract_variables(file_path): + variables = {} + try: + with open(file_path, "r") as f: + content = f.read() + # Extract variables like :variable_name: value + pattern = r":(\w+):\s*(.*)" + matches = re.finditer(pattern, content) + for match in matches: + variables[match.group(1)] = match.group(2).strip() + + # Extract title (first line starting with '= ') + 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): + # Find all .adoc files + adr_files = sorted( + [f for f in Path(adr_dir).glob("*.adoc") if f.name != "index.adoc"] + ) + + # Generate index content + content = """= ADR Index +:navtitle: ADRs + +[cols="1,2,1,1,1,1"] +|=== +|Number |Title |Author |Owner |Status |Date + +""" + + for adr_file in adr_files: + vars = extract_variables(adr_file) + if vars: + number = adr_file.stem + title = vars.get("title", "Untitled") + author = vars.get("adr_author", "") + owner = vars.get("adr_owner", "") + status = vars.get("adr_status", "") + date = vars.get("adr_date", "") + + content += f"|xref:adr/{number}.adoc[{number}] |{title} |{author} |{owner} |{status} |{date}\n" + + content += "|===\n" + + # Write the index file + with open(output_file, "w") as f: + f.write(content) + + +if __name__ == "__main__": + base_dir = "docs/modules/ROOT/pages/adr" + output_file = f"{base_dir}/index.adoc" + generate_index(base_dir, output_file) From 31811082dfe770fab2ca47dec910c158babbc2c0 Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Mon, 6 Jan 2025 09:06:58 +0100 Subject: [PATCH 05/22] add pre-commit hook to generate adr index --- .pre-commit-config.yaml | 8 ++++++++ hack/{generate_adr_index.py => generate-adr-index.py} | 1 + 2 files changed, 9 insertions(+) create mode 100644 .pre-commit-config.yaml rename hack/{generate_adr_index.py => generate-adr-index.py} (99%) mode change 100644 => 100755 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..a59cb33 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,8 @@ +repos: + - repo: local + hooks: + - id: adr-index + name: Generate ADR Index + entry: hack/generate-adr-index.py + language: python + files: ^docs/modules/ROOT/pages/adr/ diff --git a/hack/generate_adr_index.py b/hack/generate-adr-index.py old mode 100644 new mode 100755 similarity index 99% rename from hack/generate_adr_index.py rename to hack/generate-adr-index.py index cf4bfaf..e5e50aa --- a/hack/generate_adr_index.py +++ b/hack/generate-adr-index.py @@ -1,3 +1,4 @@ +#!/usr/bin/python import re from pathlib import Path From 9862d03077f7b3b549c1d9e9e07d66588fc4765b Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Mon, 6 Jan 2025 09:23:20 +0100 Subject: [PATCH 06/22] add status validation --- .pre-commit-config.yaml | 11 +++- hack/adr-tool.py | 121 +++++++++++++++++++++++++++++++++++++ hack/generate-adr-index.py | 64 -------------------- 3 files changed, 131 insertions(+), 65 deletions(-) create mode 100755 hack/adr-tool.py delete mode 100755 hack/generate-adr-index.py diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index a59cb33..0129422 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,8 +1,17 @@ repos: - repo: local hooks: + - id: adr-status-valid + name: Validate ADR status + entry: hack/adr-tool.py + args: + - validate + language: python + files: ^docs/modules/ROOT/pages/adr/ - id: adr-index name: Generate ADR Index - entry: hack/generate-adr-index.py + entry: hack/adr-tool.py + args: + - generate language: python files: ^docs/modules/ROOT/pages/adr/ diff --git a/hack/adr-tool.py b/hack/adr-tool.py new file mode 100755 index 0000000..2aff78e --- /dev/null +++ b/hack/adr-tool.py @@ -0,0 +1,121 @@ +#!/usr/bin/env python3 + +import os +import re +import sys +import argparse +from pathlib import Path + + +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 != "index.adoc"] + ) + + content = """= ADR Index +:navtitle: ADRs + +[cols="1,2,1,1,1,1"] +|=== +|Number |Title |Author |Owner |Status |Date + +""" + + for adr_file in adr_files: + vars = extract_variables(adr_file) + if vars: + number = adr_file.stem + title = vars.get("title", "Untitled") + author = vars.get("adr_author", "") + owner = vars.get("adr_owner", "") + status = vars.get("adr_status", "") + date = vars.get("adr_date", "") + + content += f"|xref:adr/{number}.adoc[{number}] |{title} |{author} |{owner} |{status} |{date}\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 != "index.adoc"] + ) + 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/generate-adr-index.py b/hack/generate-adr-index.py deleted file mode 100755 index e5e50aa..0000000 --- a/hack/generate-adr-index.py +++ /dev/null @@ -1,64 +0,0 @@ -#!/usr/bin/python -import re -from pathlib import Path - - -def extract_variables(file_path): - variables = {} - try: - with open(file_path, "r") as f: - content = f.read() - # Extract variables like :variable_name: value - pattern = r":(\w+):\s*(.*)" - matches = re.finditer(pattern, content) - for match in matches: - variables[match.group(1)] = match.group(2).strip() - - # Extract title (first line starting with '= ') - 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): - # Find all .adoc files - adr_files = sorted( - [f for f in Path(adr_dir).glob("*.adoc") if f.name != "index.adoc"] - ) - - # Generate index content - content = """= ADR Index -:navtitle: ADRs - -[cols="1,2,1,1,1,1"] -|=== -|Number |Title |Author |Owner |Status |Date - -""" - - for adr_file in adr_files: - vars = extract_variables(adr_file) - if vars: - number = adr_file.stem - title = vars.get("title", "Untitled") - author = vars.get("adr_author", "") - owner = vars.get("adr_owner", "") - status = vars.get("adr_status", "") - date = vars.get("adr_date", "") - - content += f"|xref:adr/{number}.adoc[{number}] |{title} |{author} |{owner} |{status} |{date}\n" - - content += "|===\n" - - # Write the index file - with open(output_file, "w") as f: - f.write(content) - - -if __name__ == "__main__": - base_dir = "docs/modules/ROOT/pages/adr" - output_file = f"{base_dir}/index.adoc" - generate_index(base_dir, output_file) From b4310b9fc92e05047736359feae7ea8da8737f83 Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Mon, 6 Jan 2025 09:42:45 +0100 Subject: [PATCH 07/22] slugify adr filename --- docs/modules/ROOT/partials/nav-adrs.adoc | 2 +- ...r.adr_number }}-{{ cookiecutter.adr_title | slugify }}.adoc} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename templates/adr/{{ cookiecutter.adr_number }}/{{{ cookiecutter.adr_number }}.adoc => {{ cookiecutter.adr_number }}-{{ cookiecutter.adr_title | slugify }}.adoc} (100%) diff --git a/docs/modules/ROOT/partials/nav-adrs.adoc b/docs/modules/ROOT/partials/nav-adrs.adoc index a0f94cd..8d4c56c 100644 --- a/docs/modules/ROOT/partials/nav-adrs.adoc +++ b/docs/modules/ROOT/partials/nav-adrs.adoc @@ -1,2 +1,2 @@ ** xref:adr/0001.adoc[] -** xref:adr/0002.adoc[] +** xref:adr/0002.adoc[] \ No newline at end of file diff --git a/templates/adr/{{ cookiecutter.adr_number }}/{{ cookiecutter.adr_number }}.adoc b/templates/adr/{{ cookiecutter.adr_number }}/{{ cookiecutter.adr_number }}-{{ cookiecutter.adr_title | slugify }}.adoc similarity index 100% rename from templates/adr/{{ cookiecutter.adr_number }}/{{ cookiecutter.adr_number }}.adoc rename to templates/adr/{{ cookiecutter.adr_number }}/{{ cookiecutter.adr_number }}-{{ cookiecutter.adr_title | slugify }}.adoc From 59755ae7d083d2ea39cf970a111d8c456d443f48 Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Mon, 6 Jan 2025 11:06:55 +0100 Subject: [PATCH 08/22] document adr --- .../0001-architecture-decision-records.adoc | 74 +++++++++++++++++++ docs/modules/ROOT/pages/adr/0001.adoc | 31 -------- docs/modules/ROOT/pages/adr/0002.adoc | 18 ----- docs/modules/ROOT/pages/adr/index.adoc | 7 +- docs/modules/ROOT/pages/adr/working-with.adoc | 15 ++++ docs/modules/ROOT/partials/adr-meta.adoc | 10 ++- docs/modules/ROOT/partials/nav-adrs.adoc | 3 +- docs/modules/ROOT/partials/nav.adoc | 1 + hack/adr-tool.py | 20 +++-- templates/adr/cookiecutter.json | 4 +- ...{ cookiecutter.adr_title | slugify }}.adoc | 2 + 11 files changed, 116 insertions(+), 69 deletions(-) create mode 100644 docs/modules/ROOT/pages/adr/0001-architecture-decision-records.adoc delete mode 100644 docs/modules/ROOT/pages/adr/0001.adoc delete mode 100644 docs/modules/ROOT/pages/adr/0002.adoc create mode 100644 docs/modules/ROOT/pages/adr/working-with.adoc rename templates/adr/{{{ cookiecutter.adr_number }} => {{ cookiecutter.adr_number }}-{{ cookiecutter.adr_title | slugify }}}/{{ cookiecutter.adr_number }}-{{ cookiecutter.adr_title | slugify }}.adoc (86%) 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 0000000..1e0893f --- /dev/null +++ b/docs/modules/ROOT/pages/adr/0001-architecture-decision-records.adoc @@ -0,0 +1,74 @@ += 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 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 and tools. + +An ADR is a AsciiDoc file in the folder `docs/modules/ROOT/pages/adr/NNNN-slugified-title.adoc`. + +ADRs will be numbered sequentially and monotonically. Numbers will not be reused. + +If a decision is reversed, we will keep the old one around, but mark it as superseded. It's still relevant to know that it was the decision, but is no longer the decision. + +An existing ADR can be updated with new knowledge which has to be marked appropriately, for example with an annotation `Update: 2025-01-06`. +A new ADR must be created for significant changes. + +We will use a format with just a few parts, so each document is easy to digest. +If, for any reason, the format can be adjusted for a particular ADR. + +Status:: +* Draft: ADR still being worked on - no decision has been taken yet +* Accepted: The decision is accepted +* Implemented: ADRs which were accepted and are implemented. +* Rejected: The ADR has been rejected. It's still here for history reasons and to understand why it has been rejected. +* Obsolete: ADRs kept for historical reasons, but don't reflect the current or impending state of the codebase or project. + +Title:: +ADRs have names that are short noun phrases. For example, "ADR 0001: Architecture Decision Records" or "ADR 0042: StackGres for Managed PostgreSQL service" + +Context:: +This section describes the forces at play, including technological, political, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts. + +Decision:: +This section describes our response to these forces. It is stated in full sentences, with active voice. "We will ..." + +Consequences:: +This section describes the resulting context, after applying the decision. All consequences should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future. + +The whole document should short and concise. +We will write each ADR as if it is a conversation with a future VSHNeer. +This requires good writing style, with full sentences organized into paragraphs. Bullets are acceptable only for visual style, not as an excuse for writing sentence fragments. + +== Consequences + +ADRs will help current and future VSHNeers understand the "why". + +Initially, writing ADRs will feel like additional work or a burden. Over time, it will prove its value. + +Keeping ADRs up-to-date (status, updated date) is a manual effort which might lead into outdated information. + +The motivation behind previous decisions is visible for every VSHNeer, present and future. +Nobody is left scratching their heads to understand, "What were they thinking?" and the time to change old decisions will be clear from changes in the project's context. diff --git a/docs/modules/ROOT/pages/adr/0001.adoc b/docs/modules/ROOT/pages/adr/0001.adoc deleted file mode 100644 index f8a94eb..0000000 --- a/docs/modules/ROOT/pages/adr/0001.adoc +++ /dev/null @@ -1,31 +0,0 @@ -= ADR 0001 - Architecture Decision Records -:adr_author: Tobias Brunner -:adr_owner: Schedar -:adr_reviewers: TBD -:adr_date: 2025-01-01 -:adr_status: draft - -include::partial$adr-meta.adoc[] - -[NOTE] -.Summary -==== -Architecture Decision Records (ADR) are a way to document decisions, ideas, architecture and other important aspects of the engineering process. -==== - -== Problem - -ADRs follow a certain structure, to make it easier to write them and to have a concise way of documenting things. - -== Relevant requirements - -== Relevant decisions - -== Proposals - -== Decision - -We use the existing structure from https://kb.vshn.ch/corp-tech/documents/document-decisions.html[VSHN Corporate Technology / How to read and document decisions]. - - -== Rationale diff --git a/docs/modules/ROOT/pages/adr/0002.adoc b/docs/modules/ROOT/pages/adr/0002.adoc deleted file mode 100644 index 1cebc1c..0000000 --- a/docs/modules/ROOT/pages/adr/0002.adoc +++ /dev/null @@ -1,18 +0,0 @@ -= ADR 0002 - PostgreSQL stuff -:adr_author: Tobias Brunner -:adr_owner: Schedar -:adr_reviewers: TBD -:adr_date: 2025-01-01 -:adr_status: draft - -include::partial$adr-meta.adoc[] - -[NOTE] -.Summary -==== -This page describes what ADRs are ... -==== - -== Introduction - -blubb diff --git a/docs/modules/ROOT/pages/adr/index.adoc b/docs/modules/ROOT/pages/adr/index.adoc index 411de3d..d28b4fe 100644 --- a/docs/modules/ROOT/pages/adr/index.adoc +++ b/docs/modules/ROOT/pages/adr/index.adoc @@ -1,10 +1,9 @@ = ADR Index :navtitle: ADRs -[cols="1,2,1,1,1,1"] +[cols="3,1,1,1"] |=== -|Number |Title |Author |Owner |Status |Date +|Title |Status |Date |Updated -|xref:adr/0001.adoc[0001] |ADR 0001 - Architecture Decision Records |Tobias Brunner |Schedar |draft |2025-01-01 -|xref:adr/0002.adoc[0002] |ADR 0002 - PostgreSQL stuff |Tobias Brunner |Schedar |draft |2025-01-01 +|xref:adr/0001-architecture-decision-records.adoc[] |draft |2025-01-01 |2025-01-06 |=== 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 0000000..e01b712 --- /dev/null +++ b/docs/modules/ROOT/pages/adr/working-with.adoc @@ -0,0 +1,15 @@ += Working with ADRs + +As decided in xref:adr/0001-architecture-decision-records.adoc[], we use ADRs. +This page helps to work with ADRs. + +TODO + +== Related Links + +* https://adr.github.io/[Homepage of the ADR GitHub Organization^] +* https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html[Michael Nygard - Documenting Architecture Decisions^] +* https://mbuege.com/2022/11/14/architecture-decision-records/[Matthias Büge - Architecture Decision Records^] +* https://18f.gsa.gov/2021/07/06/architecture_decision_records_helpful_now_invaluable_later/[18F - Architecture Decision Records: Helpful now, invaluable later^] +* https://github.com/joelparkerhenderson/architecture-decision-record[GitHub joelparkerhenderson/architecture-decision-record^] +* https://www.heise.de/hintergrund/Gut-dokumentiert-Architecture-Decision-Records-4664988.html?seite=all[Heise - Gut dokumentiert: Architecture Decision Records^] diff --git a/docs/modules/ROOT/partials/adr-meta.adoc b/docs/modules/ROOT/partials/adr-meta.adoc index ff40752..5493da0 100644 --- a/docs/modules/ROOT/partials/adr-meta.adoc +++ b/docs/modules/ROOT/partials/adr-meta.adoc @@ -1,4 +1,4 @@ -[.meta-info-table,cols="2*"] +[.meta-info-table,cols="1h,2"] |=== |Author |{adr_author} @@ -9,9 +9,15 @@ |Reviewers |{adr_reviewers} -|Date +|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 index 8d4c56c..c340904 100644 --- a/docs/modules/ROOT/partials/nav-adrs.adoc +++ b/docs/modules/ROOT/partials/nav-adrs.adoc @@ -1,2 +1 @@ -** xref:adr/0001.adoc[] -** xref:adr/0002.adoc[] \ No newline at end of file +** xref:adr/0001-architecture-decision-records.adoc[] \ No newline at end of file diff --git a/docs/modules/ROOT/partials/nav.adoc b/docs/modules/ROOT/partials/nav.adoc index 33422a8..8dfa87c 100644 --- a/docs/modules/ROOT/partials/nav.adoc +++ b/docs/modules/ROOT/partials/nav.adoc @@ -19,4 +19,5 @@ ** Cloudscale * xref:adr/index.adoc[] +** xref:adr/working-with.adoc[] include::partial$nav-adrs.adoc[] \ No newline at end of file diff --git a/hack/adr-tool.py b/hack/adr-tool.py index 2aff78e..e4e24e2 100755 --- a/hack/adr-tool.py +++ b/hack/adr-tool.py @@ -1,11 +1,11 @@ #!/usr/bin/env python3 - -import os import re import sys import argparse from pathlib import Path +EXCLUDED_FILES = ("index.adoc", "working-with.adoc") + def validate_adr_status(status): valid_statuses = [ @@ -42,29 +42,27 @@ def extract_variables(file_path): def generate_index(adr_dir, output_file): adr_files = sorted( - [f for f in Path(adr_dir).glob("*.adoc") if f.name != "index.adoc"] + [f for f in Path(adr_dir).glob("*.adoc") if f.name not in EXCLUDED_FILES] ) content = """= ADR Index :navtitle: ADRs -[cols="1,2,1,1,1,1"] +[cols="3,1,1,1"] |=== -|Number |Title |Author |Owner |Status |Date +|Title |Status |Date |Updated """ for adr_file in adr_files: vars = extract_variables(adr_file) + filename = Path(adr_file).stem if vars: - number = adr_file.stem - title = vars.get("title", "Untitled") - author = vars.get("adr_author", "") - owner = vars.get("adr_owner", "") status = vars.get("adr_status", "") date = vars.get("adr_date", "") + updated = vars.get("adr_upd_date", "") - content += f"|xref:adr/{number}.adoc[{number}] |{title} |{author} |{owner} |{status} |{date}\n" + content += f"|xref:adr/{filename}.adoc[] |{status} |{date} |{updated}\n" content += "|===\n" @@ -74,7 +72,7 @@ def generate_index(adr_dir, output_file): def validate_adrs(adr_dir): adr_files = sorted( - [f for f in Path(adr_dir).glob("*.adoc") if f.name != "index.adoc"] + [f for f in Path(adr_dir).glob("*.adoc") if f.name not in EXCLUDED_FILES] ) has_errors = False diff --git a/templates/adr/cookiecutter.json b/templates/adr/cookiecutter.json index b0e5e87..6d61e96 100644 --- a/templates/adr/cookiecutter.json +++ b/templates/adr/cookiecutter.json @@ -18,6 +18,7 @@ "implemented", "obsolete" ], + "adr_tags": "tag1,tag2", "__prompts__": { "adr_number": "Number of the ADR (choose the next free)", "full_name": "Your Name", @@ -33,6 +34,7 @@ "rejected": "Rejected - designs won’t be implemented.", "implemented": "Implemented - designs which were accepted and are implemented.", "obsolete": "Obsolete - designs are 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/{{ cookiecutter.adr_number }}/{{ 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 similarity index 86% rename from templates/adr/{{ cookiecutter.adr_number }}/{{ cookiecutter.adr_number }}-{{ cookiecutter.adr_title | slugify }}.adoc rename to templates/adr/{{ cookiecutter.adr_number }}-{{ cookiecutter.adr_title | slugify }}/{{ cookiecutter.adr_number }}-{{ cookiecutter.adr_title | slugify }}.adoc index eefe5f8..eddb885 100644 --- a/templates/adr/{{ cookiecutter.adr_number }}/{{ 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 @@ -3,7 +3,9 @@ :adr_owner: {{ cookiecutter.adr_owner }} :adr_reviewers: {{ cookiecutter.adr_reviewers }} :adr_date: {{ cookiecutter.adr_date }} +:adr_upd_date: :adr_status: {{ cookiecutter.adr_status }} +:adr_tags: {{ cookiecutter.adr_tags }} include::partial$adr-meta.adoc[] From a934504001a52e5768cbdbfe6d349ea0deb6880c Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Mon, 6 Jan 2025 11:17:38 +0100 Subject: [PATCH 09/22] continuation --- .../0001-architecture-decision-records.adoc | 9 +++---- .../pages/adr/0002-service-documentation.adoc | 27 +++++++++++++++++++ docs/modules/ROOT/pages/adr/index.adoc | 1 + .../ROOT/pages/service/postgresql.adoc | 2 +- docs/modules/ROOT/partials/nav-adrs.adoc | 3 ++- templates/adr/cookiecutter.json | 13 +++++---- ...{ cookiecutter.adr_title | slugify }}.adoc | 14 +++++++--- 7 files changed, 51 insertions(+), 18 deletions(-) create mode 100644 docs/modules/ROOT/pages/adr/0002-service-documentation.adoc diff --git a/docs/modules/ROOT/pages/adr/0001-architecture-decision-records.adoc b/docs/modules/ROOT/pages/adr/0001-architecture-decision-records.adoc index 1e0893f..4ac8275 100644 --- a/docs/modules/ROOT/pages/adr/0001-architecture-decision-records.adoc +++ b/docs/modules/ROOT/pages/adr/0001-architecture-decision-records.adoc @@ -12,8 +12,7 @@ include::partial$adr-meta.adoc[] [NOTE] .Summary ==== -Architecture Decision Records (ADR) are our way to document decisions, ideas, architecture and other important aspects of the engineering process. -It helps us to understand the "why". +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 @@ -25,7 +24,7 @@ Also, it might not be clear by just reading the code, other influences of a deci == Decision -We will write ADRs to document our decisions on the architecture, processes and tools. +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`. @@ -40,8 +39,8 @@ 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 +* 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. 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 0000000..b779a97 --- /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/adr/index.adoc b/docs/modules/ROOT/pages/adr/index.adoc index d28b4fe..62fb96a 100644 --- a/docs/modules/ROOT/pages/adr/index.adoc +++ b/docs/modules/ROOT/pages/adr/index.adoc @@ -6,4 +6,5 @@ |Title |Status |Date |Updated |xref:adr/0001-architecture-decision-records.adoc[] |draft |2025-01-01 |2025-01-06 +|xref:adr/0002-service-documentation.adoc[] |draft |2025-01-06 |2025-01-06 |=== diff --git a/docs/modules/ROOT/pages/service/postgresql.adoc b/docs/modules/ROOT/pages/service/postgresql.adoc index 26efb0c..6fc1fc4 100644 --- a/docs/modules/ROOT/pages/service/postgresql.adoc +++ b/docs/modules/ROOT/pages/service/postgresql.adoc @@ -12,4 +12,4 @@ Brief introduction on the architecture of the service, to get an understanding h == Related ADRs -* xref:adr/0002.adoc[] +* TODO diff --git a/docs/modules/ROOT/partials/nav-adrs.adoc b/docs/modules/ROOT/partials/nav-adrs.adoc index c340904..1764f02 100644 --- a/docs/modules/ROOT/partials/nav-adrs.adoc +++ b/docs/modules/ROOT/partials/nav-adrs.adoc @@ -1 +1,2 @@ -** xref:adr/0001-architecture-decision-records.adoc[] \ No newline at end of file +** xref:adr/0001-architecture-decision-records.adoc[] +** xref:adr/0002-service-documentation.adoc[] \ No newline at end of file diff --git a/templates/adr/cookiecutter.json b/templates/adr/cookiecutter.json index 6d61e96..cdf5253 100644 --- a/templates/adr/cookiecutter.json +++ b/templates/adr/cookiecutter.json @@ -10,8 +10,8 @@ "Vega" ], "adr_date": "{% now 'utc', '%Y-%m-%d' %}", + "adr_upd_date": "{% now 'utc', '%Y-%m-%d' %}", "adr_status": [ - "speculative", "draft", "accepted", "rejected", @@ -28,12 +28,11 @@ "adr_date": "Start date when the ADR was written", "adr_status": { "__prompt__": "State of the ADR", - "draft": "Draft - designs strive toward acceptance. Designs may exist in draft for some time as we experiment and learn, but their ultimate goal is to become an accepted design.", - "speculative": "Speculative - designs explore an idea without yet explicitly proposing a change be made.", - "accepted": "Accepted - designs will be implemented.", - "rejected": "Rejected - designs won’t be implemented.", - "implemented": "Implemented - designs which were accepted and are implemented.", - "obsolete": "Obsolete - designs are kept for historical reasons, but don’t reflect the current or impending state of the codebase or project." + "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" } 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 index eddb885..069e56f 100644 --- 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 @@ -3,7 +3,7 @@ :adr_owner: {{ cookiecutter.adr_owner }} :adr_reviewers: {{ cookiecutter.adr_reviewers }} :adr_date: {{ cookiecutter.adr_date }} -:adr_upd_date: +:adr_upd_date: {{ cookiecutter.adr_upd_date }} :adr_status: {{ cookiecutter.adr_status }} :adr_tags: {{ cookiecutter.adr_tags }} @@ -12,9 +12,15 @@ include::partial$adr-meta.adoc[] [NOTE] .Summary ==== -TODO +Short and concise summary of the decision in this ADR. ==== -== Introduction +== Context -blubb + + +== Decision + + + +== Consequences From aae8c929c4396d772bafee9bc7a00aa02dd943bc Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Mon, 6 Jan 2025 11:52:23 +0100 Subject: [PATCH 10/22] Update docs/modules/ROOT/partials/service-meta.adoc Co-authored-by: wejdross --- docs/modules/ROOT/partials/service-meta.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/partials/service-meta.adoc b/docs/modules/ROOT/partials/service-meta.adoc index 61cfb01..549aaae 100644 --- a/docs/modules/ROOT/partials/service-meta.adoc +++ b/docs/modules/ROOT/partials/service-meta.adoc @@ -19,5 +19,5 @@ |https://products.vshn.ch/appcat/postgresql.html[products.vshn.ch^] - https://git.vshn.net/vshn/docs/products/-/blob/master/docs/modules/ROOT/pages/appcat/postgresql.adoc[source^] |Code -|https://github.com/vshn/appcat[github.com/vshn/appcat^] +|https://github.com/vshn/appcat[[github.com/vshn/appcat](https://github.com/vshn/appcat/tree/master/pkg/comp-functions/functions/vshnpostgres)^] |=== From 104aec3ceb95cb093da7985cdbbbc5dab7fc8a86 Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Mon, 6 Jan 2025 14:31:22 +0100 Subject: [PATCH 11/22] add convenience symlink --- pages | 1 + 1 file changed, 1 insertion(+) create mode 120000 pages diff --git a/pages b/pages new file mode 120000 index 0000000..f6be4b4 --- /dev/null +++ b/pages @@ -0,0 +1 @@ +docs/modules/ROOT/pages \ No newline at end of file From d9268ccaeb37edd5d6baf27645c562589ad98194 Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Mon, 6 Jan 2025 14:45:20 +0100 Subject: [PATCH 12/22] output adr path at the end --- templates/adr/cookiecutter.json | 1 + templates/adr/hooks/post_gen_project.py | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/templates/adr/cookiecutter.json b/templates/adr/cookiecutter.json index cdf5253..c0c44c3 100644 --- a/templates/adr/cookiecutter.json +++ b/templates/adr/cookiecutter.json @@ -26,6 +26,7 @@ "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.", diff --git a/templates/adr/hooks/post_gen_project.py b/templates/adr/hooks/post_gen_project.py index c07f6f1..d7c737a 100644 --- a/templates/adr/hooks/post_gen_project.py +++ b/templates/adr/hooks/post_gen_project.py @@ -28,3 +28,7 @@ # 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" +) From 552ca7a7173c92ee5e80b2e6a9afa9674e69aa66 Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Tue, 7 Jan 2025 08:40:16 +0100 Subject: [PATCH 13/22] auto-increment ADR number in cookiecutter config --- templates/adr/cookiecutter.json | 2 +- templates/adr/hooks/post_gen_project.py | 28 +++++++++++++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/templates/adr/cookiecutter.json b/templates/adr/cookiecutter.json index c0c44c3..b2a429a 100644 --- a/templates/adr/cookiecutter.json +++ b/templates/adr/cookiecutter.json @@ -1,5 +1,5 @@ { - "adr_number": "00XX", + "adr_number": "0003", "full_name": "VSHNeer Name", "adr_title": "Title", "adr_reviewers": "", diff --git a/templates/adr/hooks/post_gen_project.py b/templates/adr/hooks/post_gen_project.py index d7c737a..b930eed 100644 --- a/templates/adr/hooks/post_gen_project.py +++ b/templates/adr/hooks/post_gen_project.py @@ -1,8 +1,11 @@ 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() @@ -10,6 +13,18 @@ # 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( @@ -18,6 +33,19 @@ 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: From 306731163e7f7de084961eaff8bc1600499046cb Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Tue, 7 Jan 2025 08:46:12 +0100 Subject: [PATCH 14/22] document adr tooling --- .../0001-architecture-decision-records.adoc | 2 ++ docs/modules/ROOT/pages/adr/working-with.adoc | 19 ++++++++++++++++--- 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/docs/modules/ROOT/pages/adr/0001-architecture-decision-records.adoc b/docs/modules/ROOT/pages/adr/0001-architecture-decision-records.adoc index 4ac8275..43034a9 100644 --- a/docs/modules/ROOT/pages/adr/0001-architecture-decision-records.adoc +++ b/docs/modules/ROOT/pages/adr/0001-architecture-decision-records.adoc @@ -61,6 +61,8 @@ 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". diff --git a/docs/modules/ROOT/pages/adr/working-with.adoc b/docs/modules/ROOT/pages/adr/working-with.adoc index e01b712..f3f7ef3 100644 --- a/docs/modules/ROOT/pages/adr/working-with.adoc +++ b/docs/modules/ROOT/pages/adr/working-with.adoc @@ -3,13 +3,26 @@ As decided in xref:adr/0001-architecture-decision-records.adoc[], we use ADRs. This page helps to work with ADRs. -TODO +== 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^] +* 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 Records^] +* 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] From 6a1f7799b8cfd8dc174449a95bfeef2711605cfb Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Tue, 7 Jan 2025 08:56:56 +0100 Subject: [PATCH 15/22] cleanup service metadata --- docs/modules/ROOT/pages/service/postgresql.adoc | 10 +++++++--- docs/modules/ROOT/partials/service-meta.adoc | 9 +++------ 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/modules/ROOT/pages/service/postgresql.adoc b/docs/modules/ROOT/pages/service/postgresql.adoc index 6fc1fc4..c187551 100644 --- a/docs/modules/ROOT/pages/service/postgresql.adoc +++ b/docs/modules/ROOT/pages/service/postgresql.adoc @@ -1,8 +1,12 @@ = Service: PostgreSQL -:svc_name: PostgreSQL by VSHN -:svc_owner: Schedar +:svc_name: PostgreSQL by VSHN +:svc_owner: Schedar :svc_deploytech: Operator (Stackgres) -:svc_status: production +: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[] diff --git a/docs/modules/ROOT/partials/service-meta.adoc b/docs/modules/ROOT/partials/service-meta.adoc index 549aaae..af9e9a8 100644 --- a/docs/modules/ROOT/partials/service-meta.adoc +++ b/docs/modules/ROOT/partials/service-meta.adoc @@ -9,15 +9,12 @@ |Deployment Tech |{svc_deploytech} -|Status -|[.{svc_status} .status-macro]#{svc_status}# - |End-User Documentation -|https://docs.appcat.ch/vshn-managed/postgresql/index.html[docs.appcat.ch^] - https://github.com/vshn/appcat-user-docs/tree/master/docs/modules/ROOT/pages/vshn-managed/postgresql[source^] +|{svc_doc_enduser}[docs^] - {svc_doc_enduser_src}[source^] |Product Documentation -|https://products.vshn.ch/appcat/postgresql.html[products.vshn.ch^] - https://git.vshn.net/vshn/docs/products/-/blob/master/docs/modules/ROOT/pages/appcat/postgresql.adoc[source^] +|{svc_doc_product}[docs^] - {svc_doc_product_src}[source^] |Code -|https://github.com/vshn/appcat[[github.com/vshn/appcat](https://github.com/vshn/appcat/tree/master/pkg/comp-functions/functions/vshnpostgres)^] +|{svc_code}[git repo^] |=== From 43dc3b7cf4ea4dd1cc5d04d7dd42dee1c1244eb2 Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Tue, 7 Jan 2025 09:38:08 +0100 Subject: [PATCH 16/22] move postgresql docs to the new place --- ...03-stackgres-operator-for-postgresql.adoc} | 19 ++++++++++++++++++- .../0004-postgresql-metrics-exporter.adoc} | 18 +++++++++++++++++- ...utomated-postgresql-service-upgrades.adoc} | 18 +++++++++++++++++- docs/modules/ROOT/pages/adr/index.adoc | 3 +++ .../ROOT/pages/runbooks/_runbooktpl.adoc | 9 --------- .../index.adoc} | 6 ++++-- .../alert-postgresqlconnectionscritical.adoc} | 2 ++ .../runbooks/howto-manual-restore.adoc} | 3 ++- docs/modules/ROOT/partials/nav-adrs.adoc | 5 ++++- docs/modules/ROOT/partials/nav.adoc | 6 +++--- docs/modules/ROOT/partials/nav_orig.adoc | 6 ------ templates/adr/cookiecutter.json | 2 +- 12 files changed, 71 insertions(+), 26 deletions(-) rename docs/modules/ROOT/pages/{explanations/decisions/postgresql.adoc => adr/0003-stackgres-operator-for-postgresql.adoc} (96%) rename docs/modules/ROOT/pages/{explanations/decisions/postgres-monitoring.adoc => adr/0004-postgresql-metrics-exporter.adoc} (89%) rename docs/modules/ROOT/pages/{explanations/decisions/postgres-upgrades.adoc => adr/0005-automated-postgresql-service-upgrades.adoc} (84%) delete mode 100644 docs/modules/ROOT/pages/runbooks/_runbooktpl.adoc rename docs/modules/ROOT/pages/service/{postgresql.adoc => postgresql/index.adoc} (70%) rename docs/modules/ROOT/pages/{how-tos/appcat/vshn/postgres/PostgreSQLConnectionsCritical.adoc => service/postgresql/runbooks/alert-postgresqlconnectionscritical.adoc} (86%) rename docs/modules/ROOT/pages/{how-tos/appcat/vshn/postgres/manual-restore.adoc => service/postgresql/runbooks/howto-manual-restore.adoc} (98%) 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 fbecfec..872c5db 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 c03f584..bf561f7 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 5d21d40..b9dad69 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/adr/index.adoc b/docs/modules/ROOT/pages/adr/index.adoc index 62fb96a..57ba189 100644 --- a/docs/modules/ROOT/pages/adr/index.adoc +++ b/docs/modules/ROOT/pages/adr/index.adoc @@ -7,4 +7,7 @@ |xref:adr/0001-architecture-decision-records.adoc[] |draft |2025-01-01 |2025-01-06 |xref:adr/0002-service-documentation.adoc[] |draft |2025-01-06 |2025-01-06 +|xref:adr/0003-stackgres-operator-for-postgresql.adoc[] |implemented |2022-11-15 |2023-11-01 +|xref:adr/0004-postgresql-metrics-exporter.adoc[] |implemented |2023-02-21 |2023-03-07 +|xref:adr/0005-automated-postgresql-service-upgrades.adoc[] |implemented |2023-05-23 |2023-05-04 |=== diff --git a/docs/modules/ROOT/pages/runbooks/_runbooktpl.adoc b/docs/modules/ROOT/pages/runbooks/_runbooktpl.adoc deleted file mode 100644 index da33575..0000000 --- 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/postgresql.adoc b/docs/modules/ROOT/pages/service/postgresql/index.adoc similarity index 70% rename from docs/modules/ROOT/pages/service/postgresql.adoc rename to docs/modules/ROOT/pages/service/postgresql/index.adoc index c187551..587bd27 100644 --- a/docs/modules/ROOT/pages/service/postgresql.adoc +++ b/docs/modules/ROOT/pages/service/postgresql/index.adoc @@ -12,8 +12,10 @@ include::partial$service-meta.adoc[] == Architecture -Brief introduction on the architecture of the service, to get an understanding how it is working. +TODO: Brief introduction on the architecture of the service, to get an understanding how it is working. == Related ADRs -* TODO +** 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 2079763..d22ecc5 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 6610317..da17caa 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/partials/nav-adrs.adoc b/docs/modules/ROOT/partials/nav-adrs.adoc index 1764f02..7e150a2 100644 --- a/docs/modules/ROOT/partials/nav-adrs.adoc +++ b/docs/modules/ROOT/partials/nav-adrs.adoc @@ -1,2 +1,5 @@ ** xref:adr/0001-architecture-decision-records.adoc[] -** xref:adr/0002-service-documentation.adoc[] \ No newline at end of file +** 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[] \ No newline at end of file diff --git a/docs/modules/ROOT/partials/nav.adoc b/docs/modules/ROOT/partials/nav.adoc index 8dfa87c..64e796d 100644 --- a/docs/modules/ROOT/partials/nav.adoc +++ b/docs/modules/ROOT/partials/nav.adoc @@ -4,10 +4,10 @@ ** xref:app-catalog:ROOT:explanations/app_catalog.adoc[Concept] ** xref:app-catalog:ROOT:reference/glossary.adoc[] -* xref:service/postgresql.adoc[Service: PostgreSQL] +* xref:service/postgresql/index.adoc[Service: PostgreSQL] ** Runbooks -*** xref:app-catalog:ROOT:how-tos/appcat/vshn/postgres/PostgreSQLConnectionsCritical.adoc[] -*** xref:app-catalog:ROOT:how-tos/appcat/vshn/postgres/manual-restore.adoc[] +*** xref:service/postgresql/runbooks/alert-postgresqlconnectionscritical.adoc[] +*** xref:service/postgresql/runbooks/howto-manual-restore.adoc[] * Service: SPKS * Service: Exoscale DBaaS * Control Plane diff --git a/docs/modules/ROOT/partials/nav_orig.adoc b/docs/modules/ROOT/partials/nav_orig.adoc index ca33bda..ff34ced 100644 --- a/docs/modules/ROOT/partials/nav_orig.adoc +++ b/docs/modules/ROOT/partials/nav_orig.adoc @@ -42,10 +42,6 @@ *** xref:app-catalog:ROOT:runbooks/exoscale/restore_dbaas.adoc[] * Decisions -** PostgreSQL by VSHN -*** xref:app-catalog:ROOT:explanations/decisions/postgresql.adoc[Operator evaluation] -*** xref:app-catalog:ROOT:explanations/decisions/postgres-monitoring.adoc[Availability Check] -*** xref:app-catalog:ROOT:explanations/decisions/postgres-upgrades.adoc[Upgrade Policy] ** Redis by VSHN *** xref:app-catalog:ROOT:explanations/decisions/redis.adoc[Chart evaluation] *** xref:app-catalog:ROOT:explanations/decisions/redis-upgrades.adoc[Upgrade Policy] @@ -137,9 +133,7 @@ * 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 diff --git a/templates/adr/cookiecutter.json b/templates/adr/cookiecutter.json index b2a429a..a6fa4b4 100644 --- a/templates/adr/cookiecutter.json +++ b/templates/adr/cookiecutter.json @@ -1,5 +1,5 @@ { - "adr_number": "0003", + "adr_number": "0006", "full_name": "VSHNeer Name", "adr_title": "Title", "adr_reviewers": "", From 794e67ad7bd2088b0ae5b117030fec444826b1fa Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Tue, 7 Jan 2025 09:43:03 +0100 Subject: [PATCH 17/22] remove very old and outdated billing docs --- .../ROOT/pages/reference/billing-appuio.adoc | 49 ------------- .../ROOT/pages/reference/billing-naming.adoc | 73 ------------------- docs/modules/ROOT/partials/nav.adoc | 8 +- docs/modules/ROOT/partials/nav_orig.adoc | 9 --- 4 files changed, 4 insertions(+), 135 deletions(-) delete mode 100644 docs/modules/ROOT/pages/reference/billing-appuio.adoc delete mode 100644 docs/modules/ROOT/pages/reference/billing-naming.adoc 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 2c52e61..0000000 --- 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 6483294..0000000 --- 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/partials/nav.adoc b/docs/modules/ROOT/partials/nav.adoc index 64e796d..5558862 100644 --- a/docs/modules/ROOT/partials/nav.adoc +++ b/docs/modules/ROOT/partials/nav.adoc @@ -1,8 +1,8 @@ * 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[] +** xref:explanations/what_is.adoc[What is it?] +** xref:explanations/why_exists.adoc[Why does it exist?] +** xref:explanations/app_catalog.adoc[Concept] +** xref:reference/glossary.adoc[] * xref:service/postgresql/index.adoc[Service: PostgreSQL] ** Runbooks diff --git a/docs/modules/ROOT/partials/nav_orig.adoc b/docs/modules/ROOT/partials/nav_orig.adoc index ff34ced..3259a2a 100644 --- a/docs/modules/ROOT/partials/nav_orig.adoc +++ b/docs/modules/ROOT/partials/nav_orig.adoc @@ -1,8 +1,3 @@ -* 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 @@ -31,10 +26,6 @@ **** xref:app-catalog:ROOT:reference/quality-requirements/usability/provisioning-time.adoc[Automated Provisioning of a Service] **** xref:app-catalog:ROOT:reference/quality-requirements/usability/logs.adoc[Service Instance Logs] -** Archive -*** xref:app-catalog:ROOT:reference/billing-appuio.adoc[Billing on APPUiO Cloud] -*** xref:app-catalog:ROOT:reference/billing-naming.adoc[] - * Exoscale ** xref:app-catalog:ROOT:how-tos/exoscale_dbaas/price-api.adoc[Exoscale Price API] ** xref:app-catalog:ROOT:reference/exoscale-osbapi.adoc[] From 9360ea48d72f7229ecef1040f9b3fc2126e8ed1e Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Tue, 7 Jan 2025 10:09:07 +0100 Subject: [PATCH 18/22] improve service template --- templates/service/cookiecutter.json | 31 +++++++++++++------ templates/service/hooks/post_gen_project.py | 12 ++----- ...ookiecutter.service_name_lowercase }}.adoc | 18 ----------- .../index.adoc | 19 ++++++++++++ 4 files changed, 44 insertions(+), 36 deletions(-) delete mode 100644 templates/service/{{ cookiecutter.service_name_lowercase }}/{{ cookiecutter.service_name_lowercase }}.adoc create mode 100644 templates/service/{{ cookiecutter.svc_name_lowercase }}/index.adoc diff --git a/templates/service/cookiecutter.json b/templates/service/cookiecutter.json index b8345d4..c14a86e 100644 --- a/templates/service/cookiecutter.json +++ b/templates/service/cookiecutter.json @@ -1,19 +1,32 @@ { - "service_name": "MyService", - "service_name_lowercase": "{{ cookiecutter.service_name.lower() }}", - "service_name_full": "{{ cookiecutter.service_name }} by VSHN", - "service_owner": [ + "svc_name": "MyService", + "svc_name_lowercase": "{{ cookiecutter.svc_name.lower() }}", + "svc_name_full": "{{ cookiecutter.svc_name }} by VSHN", + "svc_owner": [ "Schedar", "Aldebaran", "Nunki", "Vega" ], - "service_deploytech": [ + "svc_deploytech": [ "Helm", "Operator" ], - "service_status": [ - "production", - "development" - ] + "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 index 293fb53..1312be9 100644 --- a/templates/service/hooks/post_gen_project.py +++ b/templates/service/hooks/post_gen_project.py @@ -6,13 +6,7 @@ # Current directory is a directory where a cookiecutter template was rendered current_directory = os.getcwd() -# 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, +# Move the entire current directory to the destination directory +shutil.move( + current_directory, f"{os.path.dirname(current_directory)}/{destination_directory}" ) - -# After copying the files we can remove the source directory -shutil.rmtree(current_directory) diff --git a/templates/service/{{ cookiecutter.service_name_lowercase }}/{{ cookiecutter.service_name_lowercase }}.adoc b/templates/service/{{ cookiecutter.service_name_lowercase }}/{{ cookiecutter.service_name_lowercase }}.adoc deleted file mode 100644 index 08a0799..0000000 --- a/templates/service/{{ cookiecutter.service_name_lowercase }}/{{ cookiecutter.service_name_lowercase }}.adoc +++ /dev/null @@ -1,18 +0,0 @@ -= Service: {{ cookiecutter.service_name }} -:svc_name: {{ cookiecutter.service_name_full }} -:svc_owner: {{ cookiecutter.service_owner }} -:svc_deploytech: {{ cookiecutter.service_deploytech }} -:svc_status: {{ cookiecutter.service_status }} - -include::partial$service-meta.adoc[] - -TODO: - -* Service Template - each service must have a page -* Link to product docs -* Link to end-user docs -* Link to service source - -== Related adrs - -* xref:adr/0002.adoc[] \ No newline at end of file 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 0000000..71e8b3b --- /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[] From f74a9265d8fdfad138b9af719e77f3f1f59c1ebf Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Tue, 7 Jan 2025 10:12:34 +0100 Subject: [PATCH 19/22] move redis docs to the new place --- .../0006-bitnami-helm-chart-for-redis.adoc} | 18 ++++++++++++++++- ...007-automated-redis-service-upgrades.adoc} | 18 ++++++++++++++++- docs/modules/ROOT/pages/adr/index.adoc | 2 ++ .../ROOT/pages/service/redis/index.adoc | 20 +++++++++++++++++++ docs/modules/ROOT/partials/nav-adrs.adoc | 4 +++- docs/modules/ROOT/partials/nav.adoc | 3 +-- docs/modules/ROOT/partials/nav_orig.adoc | 3 --- templates/adr/cookiecutter.json | 2 +- 8 files changed, 61 insertions(+), 9 deletions(-) rename docs/modules/ROOT/pages/{explanations/decisions/redis.adoc => adr/0006-bitnami-helm-chart-for-redis.adoc} (85%) rename docs/modules/ROOT/pages/{explanations/decisions/redis-upgrades.adoc => adr/0007-automated-redis-service-upgrades.adoc} (94%) create mode 100644 docs/modules/ROOT/pages/service/redis/index.adoc 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 02d6e32..7096edb 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 6c5be84..ad3b1ee 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/adr/index.adoc b/docs/modules/ROOT/pages/adr/index.adoc index 57ba189..3bf5ca7 100644 --- a/docs/modules/ROOT/pages/adr/index.adoc +++ b/docs/modules/ROOT/pages/adr/index.adoc @@ -10,4 +10,6 @@ |xref:adr/0003-stackgres-operator-for-postgresql.adoc[] |implemented |2022-11-15 |2023-11-01 |xref:adr/0004-postgresql-metrics-exporter.adoc[] |implemented |2023-02-21 |2023-03-07 |xref:adr/0005-automated-postgresql-service-upgrades.adoc[] |implemented |2023-05-23 |2023-05-04 +|xref:adr/0006-bitnami-helm-chart-for-redis.adoc[] |implemented |2022-12-27 |2023-01-04 +|xref:adr/0007-automated-redis-service-upgrades.adoc[] |implemented |2023-07-11 |2023-07-11 |=== 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 0000000..9f57a2b --- /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/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 + +* xref:adr/0006-bitnami-helm-chart-for-redis.adoc[] +* xref:adr/0007-automated-redis-service-upgrades.adoc[] diff --git a/docs/modules/ROOT/partials/nav-adrs.adoc b/docs/modules/ROOT/partials/nav-adrs.adoc index 7e150a2..62a2505 100644 --- a/docs/modules/ROOT/partials/nav-adrs.adoc +++ b/docs/modules/ROOT/partials/nav-adrs.adoc @@ -2,4 +2,6 @@ ** 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[] \ No newline at end of file +** 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[] \ No newline at end of file diff --git a/docs/modules/ROOT/partials/nav.adoc b/docs/modules/ROOT/partials/nav.adoc index 5558862..eeaa099 100644 --- a/docs/modules/ROOT/partials/nav.adoc +++ b/docs/modules/ROOT/partials/nav.adoc @@ -8,8 +8,7 @@ ** Runbooks *** xref:service/postgresql/runbooks/alert-postgresqlconnectionscritical.adoc[] *** xref:service/postgresql/runbooks/howto-manual-restore.adoc[] -* Service: SPKS -* Service: Exoscale DBaaS +* xref:service/redis/index.adoc[Service: Redis] * Control Plane * Framework ** CI/CD diff --git a/docs/modules/ROOT/partials/nav_orig.adoc b/docs/modules/ROOT/partials/nav_orig.adoc index 3259a2a..4896913 100644 --- a/docs/modules/ROOT/partials/nav_orig.adoc +++ b/docs/modules/ROOT/partials/nav_orig.adoc @@ -33,9 +33,6 @@ *** xref:app-catalog:ROOT:runbooks/exoscale/restore_dbaas.adoc[] * Decisions -** 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] diff --git a/templates/adr/cookiecutter.json b/templates/adr/cookiecutter.json index a6fa4b4..4ece8fa 100644 --- a/templates/adr/cookiecutter.json +++ b/templates/adr/cookiecutter.json @@ -1,5 +1,5 @@ { - "adr_number": "0006", + "adr_number": "0008", "full_name": "VSHNeer Name", "adr_title": "Title", "adr_reviewers": "", From d243b489a39bb88f1100f289a91312a3f1d99012 Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Tue, 7 Jan 2025 10:39:14 +0100 Subject: [PATCH 20/22] include tags in adr index --- docs/modules/ROOT/pages/adr/index.adoc | 35 ++++++++++++++++++++------ hack/adr-tool.py | 3 ++- 2 files changed, 30 insertions(+), 8 deletions(-) diff --git a/docs/modules/ROOT/pages/adr/index.adoc b/docs/modules/ROOT/pages/adr/index.adoc index 3bf5ca7..116624e 100644 --- a/docs/modules/ROOT/pages/adr/index.adoc +++ b/docs/modules/ROOT/pages/adr/index.adoc @@ -5,11 +5,32 @@ |=== |Title |Status |Date |Updated -|xref:adr/0001-architecture-decision-records.adoc[] |draft |2025-01-01 |2025-01-06 -|xref:adr/0002-service-documentation.adoc[] |draft |2025-01-06 |2025-01-06 -|xref:adr/0003-stackgres-operator-for-postgresql.adoc[] |implemented |2022-11-15 |2023-11-01 -|xref:adr/0004-postgresql-metrics-exporter.adoc[] |implemented |2023-02-21 |2023-03-07 -|xref:adr/0005-automated-postgresql-service-upgrades.adoc[] |implemented |2023-05-23 |2023-05-04 -|xref:adr/0006-bitnami-helm-chart-for-redis.adoc[] |implemented |2022-12-27 |2023-01-04 -|xref:adr/0007-automated-redis-service-upgrades.adoc[] |implemented |2023-07-11 |2023-07-11 +|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 |=== diff --git a/hack/adr-tool.py b/hack/adr-tool.py index e4e24e2..633029b 100755 --- a/hack/adr-tool.py +++ b/hack/adr-tool.py @@ -61,8 +61,9 @@ def generate_index(adr_dir, output_file): 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[] |{status} |{date} |{updated}\n" + content += f"|xref:adr/{filename}.adoc[]\n\n`{tags}`\n|{status} |{date} |{updated}\n" content += "|===\n" From 817612ef763d4d4b4a81135f6cb153972668a10e Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Tue, 7 Jan 2025 10:49:18 +0100 Subject: [PATCH 21/22] move mariadb docs to the new place --- .../0008-bitnami-helm-chart-for-mariadb.adoc} | 19 ++++++++++++++++-- ...0009-proxysql-for-mariadb-clustering.adoc} | 17 +++++++++++++++- docs/modules/ROOT/pages/adr/index.adoc | 8 ++++++++ .../ROOT/pages/service/mariadb/index.adoc | 20 +++++++++++++++++++ .../ROOT/pages/service/redis/index.adoc | 2 +- docs/modules/ROOT/partials/nav-adrs.adoc | 4 +++- docs/modules/ROOT/partials/nav.adoc | 1 + docs/modules/ROOT/partials/nav_orig.adoc | 3 --- templates/adr/cookiecutter.json | 2 +- 9 files changed, 67 insertions(+), 9 deletions(-) rename docs/modules/ROOT/pages/{explanations/decisions/mariadb.adoc => adr/0008-bitnami-helm-chart-for-mariadb.adoc} (92%) rename docs/modules/ROOT/pages/{explanations/decisions/mariadb-proxy.adoc => adr/0009-proxysql-for-mariadb-clustering.adoc} (92%) create mode 100644 docs/modules/ROOT/pages/service/mariadb/index.adoc 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 9d8dc0b..59e71c5 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 feee18f..5b212dd 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/adr/index.adoc b/docs/modules/ROOT/pages/adr/index.adoc index 116624e..2db6aea 100644 --- a/docs/modules/ROOT/pages/adr/index.adoc +++ b/docs/modules/ROOT/pages/adr/index.adoc @@ -33,4 +33,12 @@ `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 |=== 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 0000000..a73e97b --- /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/redis/index.adoc b/docs/modules/ROOT/pages/service/redis/index.adoc index 9f57a2b..589bb1c 100644 --- a/docs/modules/ROOT/pages/service/redis/index.adoc +++ b/docs/modules/ROOT/pages/service/redis/index.adoc @@ -6,7 +6,7 @@ :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/FUNCTIONNAME +:svc_code: https://github.com/vshn/appcat/tree/master/pkg/comp-functions/functions/vshnredis include::partial$service-meta.adoc[] diff --git a/docs/modules/ROOT/partials/nav-adrs.adoc b/docs/modules/ROOT/partials/nav-adrs.adoc index 62a2505..ed8b3d3 100644 --- a/docs/modules/ROOT/partials/nav-adrs.adoc +++ b/docs/modules/ROOT/partials/nav-adrs.adoc @@ -4,4 +4,6 @@ ** 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[] \ No newline at end of file +** 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[] \ No newline at end of file diff --git a/docs/modules/ROOT/partials/nav.adoc b/docs/modules/ROOT/partials/nav.adoc index eeaa099..bd14177 100644 --- a/docs/modules/ROOT/partials/nav.adoc +++ b/docs/modules/ROOT/partials/nav.adoc @@ -9,6 +9,7 @@ *** xref:service/postgresql/runbooks/alert-postgresqlconnectionscritical.adoc[] *** xref:service/postgresql/runbooks/howto-manual-restore.adoc[] * xref:service/redis/index.adoc[Service: Redis] +* xref:service/mariadb/index.adoc[Service: MariaDB] * Control Plane * Framework ** CI/CD diff --git a/docs/modules/ROOT/partials/nav_orig.adoc b/docs/modules/ROOT/partials/nav_orig.adoc index 4896913..0c7f9fb 100644 --- a/docs/modules/ROOT/partials/nav_orig.adoc +++ b/docs/modules/ROOT/partials/nav_orig.adoc @@ -33,9 +33,6 @@ *** xref:app-catalog:ROOT:runbooks/exoscale/restore_dbaas.adoc[] * Decisions -** 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] diff --git a/templates/adr/cookiecutter.json b/templates/adr/cookiecutter.json index 4ece8fa..0baadab 100644 --- a/templates/adr/cookiecutter.json +++ b/templates/adr/cookiecutter.json @@ -1,5 +1,5 @@ { - "adr_number": "0008", + "adr_number": "0010", "full_name": "VSHNeer Name", "adr_title": "Title", "adr_reviewers": "", From eb56080e630e18acd60315cc20db3f095bdf3dae Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Tue, 7 Jan 2025 10:57:47 +0100 Subject: [PATCH 22/22] move minio docs to the new place --- .../0010-minio-for-local-object-storage.adoc} | 17 +++- ...0011-monitor-object-bucket-with-probe.adoc | 89 +++++++++++++++++++ docs/modules/ROOT/pages/adr/index.adoc | 8 ++ .../ROOT/pages/service/minio/index.adoc | 20 +++++ docs/modules/ROOT/partials/nav-adrs.adoc | 4 +- docs/modules/ROOT/partials/nav.adoc | 2 + docs/modules/ROOT/partials/nav_orig.adoc | 3 - templates/adr/cookiecutter.json | 2 +- 8 files changed, 139 insertions(+), 6 deletions(-) rename docs/modules/ROOT/pages/{explanations/decisions/local-objectstorage-provider.adoc => adr/0010-minio-for-local-object-storage.adoc} (94%) create mode 100644 docs/modules/ROOT/pages/adr/0011-monitor-object-bucket-with-probe.adoc create mode 100644 docs/modules/ROOT/pages/service/minio/index.adoc 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 0daf730..0a9da6b 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/adr/0011-monitor-object-bucket-with-probe.adoc b/docs/modules/ROOT/pages/adr/0011-monitor-object-bucket-with-probe.adoc new file mode 100644 index 0000000..babe7b2 --- /dev/null +++ b/docs/modules/ROOT/pages/adr/0011-monitor-object-bucket-with-probe.adoc @@ -0,0 +1,89 @@ += 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 + +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/adr/index.adoc b/docs/modules/ROOT/pages/adr/index.adoc index 2db6aea..f8318a9 100644 --- a/docs/modules/ROOT/pages/adr/index.adoc +++ b/docs/modules/ROOT/pages/adr/index.adoc @@ -41,4 +41,12 @@ `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 |=== 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 0000000..f3f4bf5 --- /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/partials/nav-adrs.adoc b/docs/modules/ROOT/partials/nav-adrs.adoc index ed8b3d3..8a72e8a 100644 --- a/docs/modules/ROOT/partials/nav-adrs.adoc +++ b/docs/modules/ROOT/partials/nav-adrs.adoc @@ -6,4 +6,6 @@ ** 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[] \ No newline at end of file +** 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[] \ No newline at end of file diff --git a/docs/modules/ROOT/partials/nav.adoc b/docs/modules/ROOT/partials/nav.adoc index bd14177..2d06620 100644 --- a/docs/modules/ROOT/partials/nav.adoc +++ b/docs/modules/ROOT/partials/nav.adoc @@ -10,6 +10,8 @@ *** xref:service/postgresql/runbooks/howto-manual-restore.adoc[] * xref:service/redis/index.adoc[Service: Redis] * xref:service/mariadb/index.adoc[Service: MariaDB] +* xref:service/minio/index.adoc[Service: MinIO] + * Control Plane * Framework ** CI/CD diff --git a/docs/modules/ROOT/partials/nav_orig.adoc b/docs/modules/ROOT/partials/nav_orig.adoc index 0c7f9fb..053e914 100644 --- a/docs/modules/ROOT/partials/nav_orig.adoc +++ b/docs/modules/ROOT/partials/nav_orig.adoc @@ -33,9 +33,6 @@ *** xref:app-catalog:ROOT:runbooks/exoscale/restore_dbaas.adoc[] * Decisions -** 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] diff --git a/templates/adr/cookiecutter.json b/templates/adr/cookiecutter.json index 0baadab..336c93b 100644 --- a/templates/adr/cookiecutter.json +++ b/templates/adr/cookiecutter.json @@ -1,5 +1,5 @@ { - "adr_number": "0010", + "adr_number": "0012", "full_name": "VSHNeer Name", "adr_title": "Title", "adr_reviewers": "",