Add end-user documentation for new MariaDB service

docs/modules/ROOT/nav.adoc

@@ -34,6 +34,14 @@
 ** xref:exoscale-dbaas/mysql/usage.adoc[Usage]
 ** xref:exoscale-dbaas/mysql/delete.adoc[Deletion]
 
+.MariaDB
+* xref:vshn-managed/mariadb/index.adoc[On cloudscale.ch]
+** xref:vshn-managed/mariadb/create.adoc[Creation]
+** xref:vshn-managed/mariadb/maintenance.adoc[]
+** xref:vshn-managed/mariadb/usage.adoc[Usage]
+** xref:vshn-managed/mariadb/delete.adoc[Deletion]
+** xref:vshn-managed/mariadb/plans.adoc[]
+
 .Redis
 * xref:exoscale-dbaas/redis/index.adoc[On Exoscale]
 ** xref:exoscale-dbaas/redis/create.adoc[Creation]

docs/modules/ROOT/pages/exoscale-dbaas/mysql/create.adoc

@@ -57,4 +57,4 @@ $ oc get secrets mysql-creds -o yaml
 
 The output of the command above is a secret specification with the following structure:
 
-include::page$references/secrets.adoc[tag=mariadb]
+include::page$references/secrets.adoc[tag=mysql]

docs/modules/ROOT/pages/index.adoc

@@ -23,6 +23,12 @@ To get started, click xref:getting-started.adoc[here].
 |
 |
 
+|MariaDB
+|
+|xref:vshn-managed/mariadb/create.adoc[Create] and xref:vshn-managed/mariadb/usage.adoc[use]
+|xref:vshn-managed/mariadb/create.adoc[Create] and xref:vshn-managed/mariadb/usage.adoc[use]
+
+
 |Redis
 |xref:exoscale-dbaas/redis/create.adoc[Create] and xref:exoscale-dbaas/redis/usage.adoc[use]
 |xref:vshn-managed/redis/create.adoc[Create] and xref:vshn-managed/redis/usage.adoc[use]
@@ -50,4 +56,4 @@ To get started, click xref:getting-started.adoc[here].
 
 |===
 
-AppCat stands for VSHN **App**lication **Cat**alog, sometimes also abbreviated as AppCatalog.
+AppCat stands for VSHN **App**lication **Cat**alog, sometimes also abbreviated as AppCatalog.

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

@@ -44,7 +44,7 @@ NOTE: Not all fields apply to all providers
 == MySQL
 
 The example secrets on this page contains the plaintext values for the given keys.
-// tag::mariadb[]
+// tag::mysql[]
 [source,yaml]
 ----
 apiVersion: v1
@@ -71,6 +71,37 @@ stringData:
 <6> Username
 <7> ca.crt to use when using `ssl-mode=VERIFY-CA`
 
+NOTE: Not all fields apply to all providers
+// end::mysql[]
+
+== MariaDB
+
+The example secrets on this page contains the plaintext values for the given keys.
+// tag::mariadb[]
+[source,yaml]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  name: mariadb-creds
+stringData:
+  MARIADB_HOST: my-mariadb.my-cloud.com <1>
+  MARIADB_PASSWORD: my-secret <2>
+  MARIADB_PORT: 3306 <3>
+  MARIADB_URL: mysql://superuser:[email protected]:3306?ssl-mode=VERIFY-CA <4>
+  MARIADB_USERNAME: superuser <5>
+  ca.crt: | <6>
+    -----BEGIN CERTIFICATE-----
+    HexValues
+    -----END CERTIFICATE-----
+----
+<1> Host to connect to
+<2> Password
+<3> Port
+<4> URL containing all necessary information to connect to the instance
+<5> Username
+<6> ca.crt to use when using `ssl-mode=VERIFY-CA`
+
 NOTE: Not all fields apply to all providers
 // end::mariadb[]
 

docs/modules/ROOT/pages/vshn-managed/mariadb/create.adoc

@@ -0,0 +1,52 @@
+= Create a MariaDB service
+
+Apply the following object on your namespace, as specified by its YAML description.
+
+.Example to create a MariaDB instance
+[source,yaml]
+----
+apiVersion: vshn.appcat.vshn.io/v1
+kind: VSHNMariaDB
+metadata:
+  name: mariadb-app1-prod # <1>
+  namespace: prod-app # <2>
+spec:
+  parameters:
+    service:
+      version: "11.2" # <3>
+    size: <4>
+      plan: standard-2
+  writeConnectionSecretToRef:
+    name: mariadb-creds # <5>
+----
+<1> Instance name
+<2> The namespace where the object will be created
+<3> MariaDB version
+<4> Size of the MariaDB instance. See xref:vshn-managed/mariadb/plans.adoc[Plans and Sizing] for more information.
+<5> Secret where the connection details are provisioned. This secret shouldn't exist before creation.
+
+NOTE: To get more information about all available configuration options, please see the xref:references/crds.adoc#k8s-api-github-com-vshn-component-appcat-apis-vshn-v1-vshnmariadb[API Reference]
+
+== Inspect your new MariaDB service
+
+[source,bash]
+----
+$  oc get vshnmariadb.vshn.appcat.vshn.io
+NAME                SYNCED   READY   CONNECTION-SECRET   AGE
+mariadb-app1-prod   True     True    mariadb-creds       3m32s
+----
+
+When you see `True` in the READY column, it means the instance is provisioned and ready to use.
+
+== Find the connection details
+
+The connection details are stored in a secret. You can retrieve them with the following command:
+
+[source,bash]
+----
+$ oc get secrets mariadb-creds -o yaml
+----
+
+The output of the command above is a secret specification with the following structure:
+
+include::page$references/secrets.adoc[tag=mariadb]

docs/modules/ROOT/pages/vshn-managed/mariadb/delete.adoc

@@ -0,0 +1,16 @@
+= Delete a MariaDB service
+
+== Delete non protected MariaDB instance
+
+If you do not need your MariaDB service anymore, you can delete it in the same way as you would with any other object in your cluster:
+
+[source,bash]
+----
+$ oc delete vshnmariadb.vshn.appcat.vshn.io mariadb-app1-prod
+----
+
+[IMPORTANT]
+.Non-reversible operation
+====
+If you delete the `VSHNMariaDB` object from the cluster, it will be deleted together with all of its data!
+====

docs/modules/ROOT/pages/vshn-managed/mariadb/index.adoc

@@ -0,0 +1,12 @@
+= MariaDB by VSHN
+
+This section provides documentation related to the MariaDB service managed by VSHN in the Application Catalog.
+
+Learn more about this service, including its pricing, in our https://products.docs.vshn.ch/products/appcat/mariadb.html#_pricing[product portfolio^].
+
+TIP: Get started and xref:vshn-managed/mariadb/create.adoc[create a MariaDB instance].
+
+== Links
+
+* https://mariadb.org/[Mariadb^]
+* xref:references/crds.adoc#k8s-api-github-com-vshn-component-appcat-apis-vshn-v1-vshnmariadb[VSHN Application Catalog API reference]

docs/modules/ROOT/pages/vshn-managed/mariadb/maintenance.adoc

@@ -0,0 +1,24 @@
+= Scheduled Maintenance
+
+By default, there will be a security maintenance on Tuesday night (Central Europe Time).
+
+NOTE: For more information about maintenance procedures, please visit https://products.docs.vshn.ch/products/appcat/mariadb.html#_recurring_maintenance[the product description].
+
+The day and time can be adjusted as described below. Times are in the CET time zone.
+
+.Redis instance with custom maintenance
+[source,yaml]
+----
+apiVersion: vshn.appcat.vshn.io/v1
+kind: VshnMariaDB
+metadata:
+  name: mariadb-app1-prod
+  namespace: prod-app
+spec:
+  parameters:
+    maintenance:
+      dayOfWeek: wednesday # <1>
+      timeOfDay: '23:30:00' # <2>
+----
+<1> The day when the maintenance should take place
+<2> The time when the maintenance should be started

docs/modules/ROOT/pages/vshn-managed/mariadb/plans.adoc

@@ -0,0 +1,145 @@
+= Plans and Sizing
+
+== Plans
+
+We provide a few preconfigured plans that should make sizing your MariaDB instance easier.
+Just choose one of the provided plans.
+
+[source,yaml]
+----
+apiVersion: vshn.appcat.vshn.io/v1
+kind: VSHNMariaDB
+metadata:
+  name: example
+spec:
+  parameters:
+    size:
+      plan: standard-2
+  writeConnectionSecretToRef:
+    name: mariadb-creds
+----
+
+By default, the following plans are available on every cluster:
+
+[cols="25a,15,15,15", options="header"]
+|===
+| Plan | CPU | Memory | Disk
+| standard-512m | 125m | 512Mi | 16Gi
+| standard-1 | 250m | 1Gi | 16Gi
+| standard-2 | 500m | 2Gi | 16Gi
+| standard-4 | 1 | 4Gi | 16Gi
+| standard-8 | 2 | 8Gi | 16Gi
+|===
+
+Depending on which cluster you're working with, there might be some slight differences in available plans.
+You can see all available plans running:
+
+[source,bash]
+----
+$ kubectl explain vshnmariadb.spec.parameters.size.plan
+
+KIND:     VSHNMariaDB
+VERSION:  vshn.appcat.vshn.io/v1
+
+FIELD:    plan <string>
+
+DESCRIPTION:
+     Plan is the name of the resource plan that defines the compute resources.
+     The following plans are available:
+
+     plus-1 - CPU: 1; Memory: 1Gi; Disk: 16Gi - Will be scheduled on APPUiO
+     Cloud plus nodes
+
+     standard-1 - CPU: 250m; Memory: 1Gi; Disk: 16Gi
+
+     standard-2 - CPU: 500m; Memory: 2Gi; Disk: 16Gi
+
+     standard-4 - CPU: 1; Memory: 4Gi; Disk: 16Gi
+
+     standard-8 - CPU: 2; Memory: 8Gi; Disk: 16Gi
+
+     standard-512m - CPU: 125m; Memory: 512Mi; Disk: 16Gi
+----
+
+[WARNING]
+.About APPUiO Cloud
+====
+On https://docs.appuio.cloud[APPUiO Cloud^] two important differences apply:
+
+* There is a `plus-X` variant of each plan that will schedule the instance on a https://docs.appuio.cloud/user/references/node-classes.html[Plus Node].
+If you use the `standard-X` plans, the instance will be scheduled on a `flex` node.
+* The `standard-8` plan is not available as it requests more memory than the https://docs.appuio.cloud/user/references/default-quota.html[Default Quota] allows.
+If you need a larger instance, please contact https://docs.appuio.cloud/user/contact.html[APPUiO Cloud support] and manually request more memory according to <<_custom_sizing>>.
+====
+
+== Custom Sizing
+
+While we provide some pre-configured plans, you are free to choose custom values for CPU, memory, and disk size.
+To do that simply set `spec.parameters.size.cpuRequests`, `spec.parameters.size.cpuLimits`, `spec.parameters.size.memoryRequests`, `spec.parameters.size.memoryLimits`,or `spec.parameters.size.disk`.
+
+The following example would keep the memory requests from the `standard-2` plan while increasing the CPU request to `1` and the CPU limits to `9`.
+
+[source,yaml]
+----
+apiVersion: vshn.appcat.vshn.io/v1
+kind: VSHNMariaDB
+metadata:
+  name: example
+spec:
+  parameters:
+    size:
+      plan: standard-2
+      cpuRequests: "2"
+      cpuLimits: "9"
+  writeConnectionSecretToRef:
+    name: mariadb-creds
+----
+
+NOTE: Changing the disk size from a default plan will restart the MariaDB pods. Any further disk size changes should not trigger a restart.
+
+NOTE: We don't recommend setting the requests to a lower value then the limit, as this might negatively impact the performance and stability of your instance.
+
+[WARNING]
+.APPUiO Cloud Fair Use Policy
+====
+On APPUiO Cloud, the https://docs.appuio.cloud/user/explanation/fair-use-policy.html[Fair Use Policy] also applies to all AppCat Services by VSHN.
+You will be billed extra for CPU requests that exceed the memory to CPU ratio.
+
+The default plans all adhere to the Fair Use Policy.
+====
+
+== Node Selectors
+
+You have the option to specify a custom node selector for your MariaDB instance.
+This allows you to assign the instance to a specific node, which can be helpful if your cluster has dedicated nodes to run databases on.
+
+The following configuration would create a MariaDB instance that runs on a node with the label `speed=fast`.
+
+[source,yaml]
+----
+apiVersion: vshn.appcat.vshn.io/v1
+kind: VSHNMariaDB
+metadata:
+  name: example
+spec:
+  parameters:
+    size:
+      plan: standard-4
+    scheduling:
+      nodeSelector:
+        speed: fast # <1>
+  writeConnectionSecretToRef:
+    name: mariadb-creds
+----
+<1> Annotation specifying a faster node.
+
+Please consult the Kubernetes documentation on https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes/[how to assign workloads to nodes using node selectors].
+
+
+[WARNING]
+.APPUiO Cloud Node Classes
+====
+On APPUiO Cloud, this can be used to schedule instances on specific https://docs.appuio.cloud/user/references/node-classes.html[Node Classes].
+
+However, this can also be done by choosing the `standard-x` or `plus-X` plans, which will schedule the instance on `flex` or `plus` nodes.
+====