Merge pull request #77 from vshn/pg/ha

Add documentation on PostgreSQL High Availability

docs/modules/ROOT/nav.adoc

@@ -24,6 +24,7 @@
 ** xref:vshn-managed/postgresql/alerting.adoc[]
 ** xref:vshn-managed/postgresql/update-strategy.adoc[]
 ** xref:vshn-managed/postgresql/extensions.adoc[]
+** xref:vshn-managed/postgresql/replicas.adoc[]
 
 .MySQL
 * xref:exoscale-dbaas/mysql/index.adoc[On Exoscale]

docs/modules/ROOT/pages/references/crds.adoc

@@ -366,7 +366,7 @@ ExoscaleKafka is the API for creating Kafka instances on Exoscale.
 [cols="25a,75a", options="header"]
 |===
 | Field | Description
-| *`ExoscaleDBaaSServiceSpec`* __xref:{anchor_prefix}-github-com-vshn-appcat-apis-exoscale-v1-exoscaledbaasservicespec[$$ExoscaleDBaaSServiceSpec$$]__ | 
+| *`zone`* __string__ | Zone is the datacenter identifier in which the instance runs in.
 | *`kafkaSettings`* __xref:{anchor_prefix}-k8s-io-apimachinery-pkg-runtime-rawextension[$$RawExtension$$]__ | KafkaSettings contains additional Kafka settings.
 | *`version`* __string__ | Version contains the minor version for Kafka. Currently only "3.4" is supported. Leave it empty to always get the latest supported version.
 |===
@@ -444,7 +444,7 @@ ExoscaleMySQL is the API for creating MySQL on Exoscale.
 [cols="25a,75a", options="header"]
 |===
 | Field | Description
-| *`ExoscaleDBaaSServiceSpec`* __xref:{anchor_prefix}-github-com-vshn-appcat-apis-exoscale-v1-exoscaledbaasservicespec[$$ExoscaleDBaaSServiceSpec$$]__ | 
+| *`zone`* __string__ | Zone is the datacenter identifier in which the instance runs in.
 | *`majorVersion`* __string__ | MajorVersion contains the major version for MySQL. Currently only "8" is supported. Leave it empty to always get the latest supported version.
 | *`mysqlSettings`* __xref:{anchor_prefix}-k8s-io-apimachinery-pkg-runtime-rawextension[$$RawExtension$$]__ | MySQLSettings contains additional MySQL settings.
 |===
@@ -522,7 +522,7 @@ ExoscaleOpenSearch is the api for creating OpenSearch on Exoscale
 [cols="25a,75a", options="header"]
 |===
 | Field | Description
-| *`ExoscaleDBaaSServiceSpec`* __xref:{anchor_prefix}-github-com-vshn-appcat-apis-exoscale-v1-exoscaledbaasservicespec[$$ExoscaleDBaaSServiceSpec$$]__ | 
+| *`zone`* __string__ | Zone is the datacenter identifier in which the instance runs in.
 | *`majorVersion`* __string__ | MajorVersion contains the version for OpenSearch. Currently only "2" and "1" is supported. Leave it empty to always get the latest supported version.
 | *`opensearchSettings`* __xref:{anchor_prefix}-k8s-io-apimachinery-pkg-runtime-rawextension[$$RawExtension$$]__ | OpenSearchSettings contains additional OpenSearch settings.
 |===
@@ -600,7 +600,7 @@ ExoscalePostgreSQL is the API for creating PostgreSQL on Exoscale.
 [cols="25a,75a", options="header"]
 |===
 | Field | Description
-| *`ExoscaleDBaaSServiceSpec`* __xref:{anchor_prefix}-github-com-vshn-appcat-apis-exoscale-v1-exoscaledbaasservicespec[$$ExoscaleDBaaSServiceSpec$$]__ | 
+| *`zone`* __string__ | Zone is the datacenter identifier in which the instance runs in.
 | *`majorVersion`* __string__ | MajorVersion contains the major version for PostgreSQL. Currently only "14" is supported. Leave it empty to always get the latest supported version.
 | *`pgSettings`* __xref:{anchor_prefix}-k8s-io-apimachinery-pkg-runtime-rawextension[$$RawExtension$$]__ | PGSettings contains additional PostgreSQL settings.
 |===
@@ -677,7 +677,7 @@ ExoscaleRedis is the API for creating Redis instances on Exoscale.
 [cols="25a,75a", options="header"]
 |===
 | Field | Description
-| *`ExoscaleDBaaSServiceSpec`* __xref:{anchor_prefix}-github-com-vshn-appcat-apis-exoscale-v1-exoscaledbaasservicespec[$$ExoscaleDBaaSServiceSpec$$]__ | 
+| *`zone`* __string__ | Zone is the datacenter identifier in which the instance runs in.
 | *`redisSettings`* __xref:{anchor_prefix}-k8s-io-apimachinery-pkg-runtime-rawextension[$$RawExtension$$]__ | RedisSettings contains additional Redis settings.
 |===
 
@@ -722,6 +722,7 @@ This is a https://github.com/elastic/crd-ref-docs[generated] API documentation.
 - xref:{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-xvshnpostgresql[$$XVSHNPostgreSQL$$]
 - xref:{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-vshnpostgresqllist[$$VSHNPostgreSQLList$$]
 - xref:{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-vshnredis[$$VSHNRedis$$]
+- xref:{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-vshnredislist[$$VSHNRedisList$$]
 - xref:{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-xvshnpostgresql[$$XVSHNPostgreSQL$$]
 - xref:{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-xvshnpostgresqllist[$$XVSHNPostgreSQLList$$]
 
@@ -803,6 +804,23 @@ VSHNDBaaSNetworkSpec contains any network related settings.
 |===
 
 
+[id="{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-vshndbaaspostgresextension"]
+=== VSHNDBaaSPostgresExtension 
+
+VSHNDBaaSPostgresExtension contains the name of a single extension.
+
+.Appears In:
+****
+- xref:{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-vshnpostgresqlservicespec[$$VSHNPostgreSQLServiceSpec$$]
+****
+
+[cols="25a,75a", options="header"]
+|===
+| Field | Description
+| *`name`* __string__ | Name is the name of the extension to enable. For an extensive list, please consult https://stackgres.io/doc/latest/intro/extensions/
+|===
+
+
 [id="{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-vshndbaasschedulingspec"]
 === VSHNDBaaSSchedulingSpec 
 
@@ -958,6 +976,30 @@ VSHNPostgreSQLParameters are the configurable fields of a VSHNPostgreSQL.
 | *`monitoring`* __xref:{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-vshnpostgresqlmonitoring[$$VSHNPostgreSQLMonitoring$$]__ | Monitoring contains settings to control monitoring.
 | *`encryption`* __xref:{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-vshnpostgresqlencryption[$$VSHNPostgreSQLEncryption$$]__ | Encryption contains settings to control the storage encryption of an instance.
 | *`updateStrategy`* __xref:{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-vshnpostgresqlupdatestrategy[$$VSHNPostgreSQLUpdateStrategy$$]__ | UpdateStrategy indicates when updates to the instance spec will be applied.
+| *`instances`* __integer__ | Instances configures the number of PostgreSQL instances for the cluster. Each instance contains one Postgres server. Out of all of the Postgres servers, one is elected as the primary, the rest remain as read-only replicas.
+| *`replication`* __xref:{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-vshnpostgresqlreplicationstrategy[$$VSHNPostgreSQLReplicationStrategy$$]__ | This section allows to configure Postgres replication mode and HA roles groups. 
+ The main replication group is implicit and contains the total number of instances less the sum of all instances in other replication groups.
+|===
+
+
+[id="{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-vshnpostgresqlreplicationstrategy"]
+=== VSHNPostgreSQLReplicationStrategy 
+
+
+
+.Appears In:
+****
+- xref:{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-vshnpostgresqlparameters[$$VSHNPostgreSQLParameters$$]
+****
+
+[cols="25a,75a", options="header"]
+|===
+| Field | Description
+| *`mode`* __string__ | Mode defines the replication mode applied to the whole cluster. Possible values are: "async"(default), "sync", and "strict-sync" 
+ "async": When in asynchronous mode the cluster is allowed to lose some committed transactions. When the primary server fails or becomes unavailable for any other reason a sufficiently healthy standby will automatically be promoted to primary. Any transactions that have not been replicated to that standby remain in a “forked timeline” on the primary, and are effectively unrecoverable 
+ "sync": When in synchronous mode a standby will not be promoted unless it is certain that the standby contains all transactions that may have returned a successful commit status to client. This means that the system may be unavailable for writes even though some servers are available. 
+ "strict-sync": When it is absolutely necessary to guarantee that each write is stored durably on at least two nodes, use the strict synchronous mode. This mode prevents synchronous replication to be switched off on the primary when no synchronous standby candidates are available. As a downside, the primary will not be available for writes, blocking all client write requests until at least one synchronous replica comes up. 
+ NOTE: We recommend to always use three intances when setting the mode to "strict-sync".
 |===
 
 
@@ -995,6 +1037,7 @@ VSHNPostgreSQLServiceSpec contains PostgreSQL DBaaS specific properties
 | Field | Description
 | *`majorVersion`* __string__ | MajorVersion contains supported version of PostgreSQL. Multiple versions are supported. The latest version "15" is the default version.
 | *`pgSettings`* __xref:{anchor_prefix}-k8s-io-apimachinery-pkg-runtime-rawextension[$$RawExtension$$]__ | PGSettings contains additional PostgreSQL settings.
+| *`extensions`* __xref:{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-vshndbaaspostgresextension[$$VSHNDBaaSPostgresExtension$$] array__ | Extensions allow to enable/disable any of the supported
 |===
 
 
@@ -1033,7 +1076,7 @@ VSHNPostgreSQLUpdateStrategy indicates how and when updates to the instance spec
 [cols="25a,75a", options="header"]
 |===
 | Field | Description
-| *`type`* __string__ | Type indicates the type of the UpdateStrategy. Default is OnRestart. Possible enum values:   - `"OnRestart"` indicates that the changes to the spec will only be applied once the instance is restarted by other means, most likely during maintenance.   - `"Immediate"` indicates that update will be applied to the instance as soon as the spec changes. Please be aware that this might lead to short downtime.
+| *`type`* __string__ | Type indicates the type of the UpdateStrategy. Default is OnRestart. Possible enum values: - `"OnRestart"` indicates that the changes to the spec will only be applied once the instance is restarted by other means, most likely during maintenance. - `"Immediate"` indicates that update will be applied to the instance as soon as the spec changes. Please be aware that this might lead to short downtime.
 |===
 
 
@@ -1042,7 +1085,10 @@ VSHNPostgreSQLUpdateStrategy indicates how and when updates to the instance spec
 
 VSHNRedis is the API for creating Redis clusters.
 
-
+.Appears In:
+****
+- xref:{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-vshnredislist[$$VSHNRedisList$$]
+****
 
 [cols="25a,75a", options="header"]
 |===
@@ -1055,6 +1101,24 @@ VSHNRedis is the API for creating Redis clusters.
 |===
 
 
+[id="{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-vshnredislist"]
+=== VSHNRedisList 
+
+
+
+
+
+[cols="25a,75a", options="header"]
+|===
+| Field | Description
+| *`apiVersion`* __string__ | `vshn.appcat.vshn.io/v1`
+| *`kind`* __string__ | `VSHNRedisList`
+| *`metadata`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.20/#listmeta-v1-meta[$$ListMeta$$]__ | Refer to Kubernetes API documentation for fields of `metadata`.
+
+| *`items`* __xref:{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-vshnredis[$$VSHNRedis$$] array__ | 
+|===
+
+
 [id="{anchor_prefix}-github-com-vshn-appcat-apis-vshn-v1-vshnredisparameters"]
 === VSHNRedisParameters 
 

docs/modules/ROOT/pages/vshn-managed/postgresql/replicas.adoc

@@ -0,0 +1,69 @@
+= Replication and High Availability
+
+PostgreSQL by VSHN comes with support for multiple instances and High Availability using https://github.com/zalando/patroni[Patroni].
+You have the option to configure up to two additional replicas and also choose between three replication modes.
+
+== Enable High Availability
+
+To enable high availability you need to set the number of instances to `2` or `3`, which will provision one or two stand-by replicas.
+
+The following example configuration will start a PostgreSQL service with two replicas.
+
+[source,yaml]
+----
+apiVersion: vshn.appcat.vshn.io/v1
+kind: VSHNPostgreSQL
+metadata:
+  name: pgsql-app1-prod
+spec:
+  parameters:
+    instances: 3
+----
+
+NOTE: Please be aware that enabling high availability will use significantly more resources and will cost two to three times more.
+
+IMPORTANT: On APPUiO Cloud, it's currently not possible to deploy more than two instances, or more than a single instance that is larger than `standard-2`.
+Please contact https://docs.appuio.cloud/user/contact.html[APPUiO Cloud support], if this blocks you from running your application.
+
+
+== Replication Modes
+
+You can also choose between one of three replication modes, by configuring it in the `replication` parameter.
+
+[source,yaml]
+----
+apiVersion: vshn.appcat.vshn.io/v1
+kind: VSHNPostgreSQL
+metadata:
+  name: pgsql-app1-prod
+spec:
+  parameters:
+    instances: 3
+    replication:
+      mode: sync
+----
+
+
+The three available modes are:
+
+`async`::
+The asynchronous mode is the default replication mode.
+In this mode the cluster is allowed to lose some committed transactions to ensure availability. 
+When the primary server fails or becomes unavailable for any other reason a sufficiently healthy standby will be promoted to primary.
+Any transactions that have not been replicated to that standby remain in a “forked timeline” on the primary, and are effectively unrecoverable.
+
+
+`sync`::
+When synchronous mode is turned on a standby will not be promoted unless it is certain that the standby contains all transactions that may have returned a successful commit status to client.
+If no suitable standby is available, primary server will still accept writes, but does not guarantee their replication.
+When the primary fails in this situation no standby will be promoted.
++
+NOTE: This mode essentially reduces the availability guarantee for better consistency guarantees.
+If you don't have a use case where losing committed transactions is not permissible, we recommend using the asynchronous mode instead.
+
+`strict-sync`::
+If it is absolutely necessary to guarantee that each write is stored durably on at least two nodes, you can enable the strict synchronous mode.
+In this mode, when no synchronous standby candidates are available, the primary won't be available for writes, blocking all client write requests until at least one synchronous replica comes up.
++
+WARNING: We recommend to only use this mode if you have very strong consistency requirements and that you only use this mode with three instances, otherwise your instance will likely not accept any writes during maintenance and similar events.
+