Merge pull request #49 from vshn/pg-docs

Document behaviour limitations of PostgreSQL on Exoscale

docs/modules/ROOT/nav.adoc

@@ -13,6 +13,7 @@
 
 .Explanation
 * xref:explanations/iamkey.adoc[IAMKeys permissions]
+* xref:explanations/dbaas-postgresql.adoc[DBaaS: PostgreSQL]
 * For Developers
 ** xref:explanations/dev/iamkey-reconciliation.adoc[ObjectsUser Reconciliation]
 ** xref:explanations/dev/bucket-reconciliation.adoc[Bucket Reconciliation]

docs/modules/ROOT/pages/explanations/dbaas-postgresql.adoc

@@ -0,0 +1,28 @@
+= DBaaS: PostgreSQL
+
+== Immutable Fields
+
+After an instance has been created in Exoscale, certain restrictions apply to the following properties:
+
+`spec.forProvider.zone`::
+Changing the Zone/Datacenter doesn't automatically move an instance, thus this field has been made immutable via admission webhook.
+
+`spec.forProvider.version`::
+This field is basically only there to set the initial version upon first creation.
+After provisioning, this field becomes effectively unused and the observed version is incremented according to the maintenance policy and available updates.
+This field only accepts a change if it's set to the exact same version as the observed version, for every other value it's immutable.
++
+NOTE: The behaviour of this field might change in a future release.
+
+== Long Delays When Updating Instances
+
+When a change to the spec is made, the provider attempts to update the instance via Exoscale API.
+Even if updating the instance is successful, it can take a few seconds until the `Ready` condition becomes false with reason `Rebuilding`.
+This is most likely due to the provider observing the resource on Exoscale API again, before Exoscale actually sets the instance status to `Rebuilding`.
+
+NOTE: Depending on the change, the rebuilding can take a few minutes.
+
+Also, after the instance is rebuilt on Exoscale, there can be an additional delay until the status is updated.
+The current reconcile interval for the PostgreSQL resources is once per minute.
+
+TIP: Scripts and other automations that change the spec and await updated status should expect delays of 2 minutes or more before potentially reporting an error or timeout.