From 78704363770f0d1958305f49d1fbf3f336960fa9 Mon Sep 17 00:00:00 2001 From: Nicolas Bigler Date: Fri, 5 Jan 2024 13:24:53 +0100 Subject: [PATCH 1/3] Add end-user documentation for new MariaDB service Signed-off-by: Nicolas Bigler --- docs/modules/ROOT/nav.adoc | 10 ++ .../pages/exoscale-dbaas/mysql/create.adoc | 2 +- docs/modules/ROOT/pages/index.adoc | 8 +- .../ROOT/pages/references/secrets.adoc | 33 +++- .../pages/vshn-managed/mariadb/backup.adoc | 62 ++++++++ .../pages/vshn-managed/mariadb/create.adoc | 56 +++++++ .../pages/vshn-managed/mariadb/delete.adoc | 57 +++++++ .../pages/vshn-managed/mariadb/index.adoc | 12 ++ .../vshn-managed/mariadb/maintenance.adoc | 24 +++ .../pages/vshn-managed/mariadb/plans.adoc | 145 ++++++++++++++++++ .../pages/vshn-managed/mariadb/restore.adoc | 44 ++++++ .../pages/vshn-managed/mariadb/usage.adoc | 90 +++++++++++ .../ROOT/pages/vshn-managed/redis/create.adoc | 2 +- .../pages/vshn-managed/redis/maintenance.adoc | 2 +- .../ROOT/pages/vshn-managed/redis/plans.adoc | 4 +- 15 files changed, 544 insertions(+), 7 deletions(-) create mode 100644 docs/modules/ROOT/pages/vshn-managed/mariadb/backup.adoc create mode 100644 docs/modules/ROOT/pages/vshn-managed/mariadb/create.adoc create mode 100644 docs/modules/ROOT/pages/vshn-managed/mariadb/delete.adoc create mode 100644 docs/modules/ROOT/pages/vshn-managed/mariadb/index.adoc create mode 100644 docs/modules/ROOT/pages/vshn-managed/mariadb/maintenance.adoc create mode 100644 docs/modules/ROOT/pages/vshn-managed/mariadb/plans.adoc create mode 100644 docs/modules/ROOT/pages/vshn-managed/mariadb/restore.adoc create mode 100644 docs/modules/ROOT/pages/vshn-managed/mariadb/usage.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index dad7fae..7924e89 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -34,6 +34,16 @@ ** 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[] +** xref:vshn-managed/mariadb/backup.adoc[Backup] +** xref:vshn-managed/mariadb/restore.adoc[Restore] + .Redis * xref:exoscale-dbaas/redis/index.adoc[On Exoscale] ** xref:exoscale-dbaas/redis/create.adoc[Creation] diff --git a/docs/modules/ROOT/pages/exoscale-dbaas/mysql/create.adoc b/docs/modules/ROOT/pages/exoscale-dbaas/mysql/create.adoc index 479653e..66f603a 100644 --- a/docs/modules/ROOT/pages/exoscale-dbaas/mysql/create.adoc +++ b/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] diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 57ea7cc..1eb5a88 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/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. \ No newline at end of file +AppCat stands for VSHN **App**lication **Cat**alog, sometimes also abbreviated as AppCatalog. diff --git a/docs/modules/ROOT/pages/references/secrets.adoc b/docs/modules/ROOT/pages/references/secrets.adoc index 2753fd9..b1868c1 100644 --- a/docs/modules/ROOT/pages/references/secrets.adoc +++ b/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:my-secret@my-mariadb.my-cloud.com: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[] diff --git a/docs/modules/ROOT/pages/vshn-managed/mariadb/backup.adoc b/docs/modules/ROOT/pages/vshn-managed/mariadb/backup.adoc new file mode 100644 index 0000000..c7ee7fd --- /dev/null +++ b/docs/modules/ROOT/pages/vshn-managed/mariadb/backup.adoc @@ -0,0 +1,62 @@ += Backups + +Backups are enabled by default. The MariaDB instance will be backed up daily at a randomly chosen time between 22:00 and 4:00. + +You can specify a different backup time and interval using the following backup configuration: + +[source,yaml] +---- +apiVersion: vshn.appcat.vshn.io/v1 +kind: VSHNMariaDB +metadata: + name: mariadb-app1-prod + namespace: +spec: + parameters: + ... + backup: + schedule: 0 22 * * * <1> + ... +---- +<1> The schedules for your backups. + +== Listing Backups + +Get an overview of all backups performed of your database instance: + +[source,bash] +---- +$ kubectl -n get vshnmariadbbackups +BACKUP ID DATABASE INSTANCE BACKUP TIME +6678cecd mariadb-app1-prod 2024-01-05T08:11:02Z +6df7d405 mariadb-app1-prod 2024-01-05T07:30:05Z +4bb23139 mariadb-app2-prod 2024-01-05T12:29:05Z +e5164ada mariadb-app2-prod 2024-01-05T12:33:02Z +---- +NOTE: The list will show all backups from all instances in this namespace. In the example above there are two database instances with two backups each. + +== Backup Details + +Learn more about a chosen backup: + +[source,bash] +---- +$ kubectl -n get vshnmariadbbackups 6678cecd -oyaml +apiVersion: api.appcat.vshn.io/v1 +kind: VSHNMariaDBBackup +metadata: + creationTimestamp: "2024-01-05T08:11:03Z" + generation: 1 + name: 6678cecd <1> + namespace: default + resourceVersion: "14581" + uid: ee105483-2a15-476b-b2d1-561526c74e25 +status: + date: "2024-01-05T08:11:02Z" <2> + id: 6678cecd3a006ff04111a3bd992c2a22183f7b69b2a8632dc365843341927c4a <3> + instance: mariadb-app1-prod <4> +---- +<1> Short ID of the backup +<2> The time when the backup finished +<3> Full ID of the backup, this is used for internal restore operations +<4> Name of the instance this backup belongs to diff --git a/docs/modules/ROOT/pages/vshn-managed/mariadb/create.adoc b/docs/modules/ROOT/pages/vshn-managed/mariadb/create.adoc new file mode 100644 index 0000000..11bf134 --- /dev/null +++ b/docs/modules/ROOT/pages/vshn-managed/mariadb/create.adoc @@ -0,0 +1,56 @@ += 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> + mariadbSettings: | # <4> + [mariadb] + enable_slow_query_log + size: <5> + plan: standard-2 + writeConnectionSecretToRef: + name: mariadb-creds # <6> +---- +<1> Instance name +<2> The namespace where the object will be created +<3> MariaDB version +<4> Specify custom MariaDB settings [optional] +<5> Size of the MariaDB instance. See xref:vshn-managed/mariadb/plans.adoc[Plans and Sizing] for more information. +<6> 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] diff --git a/docs/modules/ROOT/pages/vshn-managed/mariadb/delete.adoc b/docs/modules/ROOT/pages/vshn-managed/mariadb/delete.adoc new file mode 100644 index 0000000..d4afe77 --- /dev/null +++ b/docs/modules/ROOT/pages/vshn-managed/mariadb/delete.adoc @@ -0,0 +1,57 @@ += 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! +==== + +== Delete protected MariaDB instance + +A MariaDB instance that is protected from deletion cannot be deleted right away. +First disable deletion protection then delete the instance. + +. Disable deletion protection: ++ +[source,bash] +---- +$ oc edit vshnmariadb.vshn.appcat.vshn.io mariadb-app1-prod +---- ++ +[source,yaml] +---- +apiVersion: vshn.appcat.vshn.io/v1 +kind: VSHNMariaDB +metadata: + name: mariadb-app1-prod + namespace: prod-app +spec: + parameters: + backup: + deletionProtection: false # <1> + writeConnectionSecretToRef: + name: mariadb-creds +---- +<1> Make sure the parameter is set to false + +. Delete the instance ++ +[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! +==== diff --git a/docs/modules/ROOT/pages/vshn-managed/mariadb/index.adoc b/docs/modules/ROOT/pages/vshn-managed/mariadb/index.adoc new file mode 100644 index 0000000..5d933fc --- /dev/null +++ b/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] diff --git a/docs/modules/ROOT/pages/vshn-managed/mariadb/maintenance.adoc b/docs/modules/ROOT/pages/vshn-managed/mariadb/maintenance.adoc new file mode 100644 index 0000000..a0d77c2 --- /dev/null +++ b/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 diff --git a/docs/modules/ROOT/pages/vshn-managed/mariadb/plans.adoc b/docs/modules/ROOT/pages/vshn-managed/mariadb/plans.adoc new file mode 100644 index 0000000..15e38b3 --- /dev/null +++ b/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 + +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. +==== diff --git a/docs/modules/ROOT/pages/vshn-managed/mariadb/restore.adoc b/docs/modules/ROOT/pages/vshn-managed/mariadb/restore.adoc new file mode 100644 index 0000000..df0fe6e --- /dev/null +++ b/docs/modules/ROOT/pages/vshn-managed/mariadb/restore.adoc @@ -0,0 +1,44 @@ += Restores + +IMPORTANT: *Restore operation will create a new MariaDB instance with new credentials* + +By default, every mariadb instance creates a backup once a day or at the time you specified. + +Please visit the (xref:vshn-managed/mariadb/backup.adoc[Backup documentation] for more information. + +You can list all the backups that are available with the following command: + +[source,bash] +---- +kubectl -n get vshnmariadb + +BACKUP ID DATABASE INSTANCE BACKUP TIME +6678cecd mariadb-app1-prod 2024-01-05T08:11:02Z +6df7d405 mariadb-app1-prod 2024-01-05T07:30:05Z +4bb23139 mariadb-app2-prod 2024-01-05T12:29:05Z +e5164ada mariadb-app2-prod 2024-01-05T12:33:02Z +---- + +This will list all the backup available to you. +You can then restore the backup to a new instance, by using the following restore configuration: + +[source,yaml] +---- +apiVersion: vshn.appcat.vshn.io/v1 +kind: VSHNMariaDB +metadata: + name: mariadb-app2-prod + namespace: +spec: + parameters: + ... + restore: + claimName: mariadb-app1-prod <1> + backupName: e5164ada <2> + ... +---- +<1> The claimName of the original mariadb instance to restore from +<2> The Backup ID which you want to restore + +This configuration will spin up a new mariadb instance and will restore the specified backup to your instance. +In the example above, the new mariadb instance will be called `mariadb-app2-prod` and will be running the restored data from the mariadb instance `mariadb-app1-prod` using the backup `e5164ada` tat was taken at `2024-01-05T12:33:02Z` diff --git a/docs/modules/ROOT/pages/vshn-managed/mariadb/usage.adoc b/docs/modules/ROOT/pages/vshn-managed/mariadb/usage.adoc new file mode 100644 index 0000000..8fd4747 --- /dev/null +++ b/docs/modules/ROOT/pages/vshn-managed/mariadb/usage.adoc @@ -0,0 +1,90 @@ += Using a MariaDB service + +The YAML code below creates two objects: a `VSHNMariaDB` instance and a pod accessing it to show information about the instance. +The latter references the `redis-creds` secret that will contain the access keys required to connect to the instance. + +[source,yaml] +---- +apiVersion: vshn.appcat.vshn.io/v1 +kind: VSHNMariaDB +metadata: + name: my-mariadb-example + namespace: my-namespace +spec: + parameters: + service: + version: "11.2" + writeConnectionSecretToRef: + name: mariadb-creds-connection # <1> +--- +apiVersion: v1 +kind: Pod +metadata: + name: mariadb-client +spec: + containers: + - name: mariadb + image: mariadb:11.2 + command: + - /bin/sh + - -c + args: + - mariadb --host=$MARIADB_HOST --user=$MARIADB_USERNAME --port=$MARIADB_PORT --password=$MARIADB_PASSWORD --ssl-verify-server-cert --ssl-ca=/etc/mariadb-tls/ca.crt -e 'SHOW DATABASES' # <3> + volumeMounts: + - name: mariadb-tls-secrets # <4> + readOnly: true + mountPath: "/etc/mariadb-tls" + envFrom: + - secretRef: + name: mariadb-creds-connection # <2> + volumes: + - name: mariadb-tls-secrets # <4> + secret: + defaultMode: 0600 + secretName: mariadb-creds-connection # <2> + restartPolicy: Never +---- +<1> The operator will create a secret with the access keys to connect to the instance. +<2> The pod and the volume will use the new secret. +<3> Uses mariadb to print all existing databases to stdout. +<4> Mount the secret with the credentials to the pod, for TLS support (enabled by default) + +== Debug the service + +To check the status and potential issues or errors in the service, check the `status` field of the new object: + +[source,bash] +---- +$ oc describe vshnmariadb.vshn.appcat.vshn.io my-mariadb-example +[...] +Status: + Conditions: + Last Transition Time: 2023-02-17T23:25:57Z + Reason: ReconcileSuccess + Status: True + Type: Synced + Last Transition Time: 2023-02-17T23:26:07Z + Reason: Available + Status: True + Type: Ready + Connection Details: + Last Published Time: 2023-02-17T23:26:07Z + Local CA Debug: + Last Transition Time: 2023-02-17T23:25:59Z + Reason: Available + Status: True + Type: Ready + Last Transition Time: 2023-02-17T23:25:58Z + Reason: ReconcileSuccess + Status: True + Type: Synced + Namespace Debug: + Last Transition Time: 2023-02-17T23:25:59Z + Reason: Available + Status: True + Type: Ready + Last Transition Time: 2023-02-17T23:25:58Z + Reason: ReconcileSuccess + Status: True + Type: Synced +---- diff --git a/docs/modules/ROOT/pages/vshn-managed/redis/create.adoc b/docs/modules/ROOT/pages/vshn-managed/redis/create.adoc index 082e299..fcc6bbf 100644 --- a/docs/modules/ROOT/pages/vshn-managed/redis/create.adoc +++ b/docs/modules/ROOT/pages/vshn-managed/redis/create.adoc @@ -36,7 +36,7 @@ NOTE: To get more information about all available configuration options, please ---- $ oc get vshnredis.vshn.appcat.vshn.io NAME SYNCED READY CONNECTION-SECRET AGE -pgsql-app1-prod True True redis-creds 3m32s +redis-app1-prod True True redis-creds 3m32s ---- When you see `True` in the READY column, it means the instance is provisioned and ready to use. diff --git a/docs/modules/ROOT/pages/vshn-managed/redis/maintenance.adoc b/docs/modules/ROOT/pages/vshn-managed/redis/maintenance.adoc index 950d922..228829b 100644 --- a/docs/modules/ROOT/pages/vshn-managed/redis/maintenance.adoc +++ b/docs/modules/ROOT/pages/vshn-managed/redis/maintenance.adoc @@ -10,7 +10,7 @@ The day and time can be adjusted as described below. Times are in the CET time z [source,yaml] ---- apiVersion: vshn.appcat.vshn.io/v1 -kind: Redis +kind: VSHNRedis metadata: name: redis-app1-prod namespace: prod-app diff --git a/docs/modules/ROOT/pages/vshn-managed/redis/plans.adoc b/docs/modules/ROOT/pages/vshn-managed/redis/plans.adoc index 66f4c70..af7b30d 100644 --- a/docs/modules/ROOT/pages/vshn-managed/redis/plans.adoc +++ b/docs/modules/ROOT/pages/vshn-managed/redis/plans.adoc @@ -92,7 +92,7 @@ spec: cpuRequests: "2" cpuLimits: "9" writeConnectionSecretToRef: - name: postgres-creds + name: redis-creds ---- NOTE: Changing the disk size from a default plan will restart the Redis pods. Any further disk size changes should not trigger a restart. @@ -113,7 +113,7 @@ The default plans all adhere to the Fair Use Policy. You have the option to specify a custom node selector for your Redis 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 PostgreSQL instance that runs on a node with the label `speed=fast`. +The following configuration would create a Redis instance that runs on a node with the label `speed=fast`. [source,yaml] ---- From fba058792f5f7101122d81bd86ea5d16fb167edc Mon Sep 17 00:00:00 2001 From: Nicolas Bigler Date: Mon, 8 Jan 2024 16:07:51 +0100 Subject: [PATCH 2/3] Remove unimplemented stuff Signed-off-by: Nicolas Bigler --- docs/modules/ROOT/nav.adoc | 2 - .../pages/vshn-managed/mariadb/backup.adoc | 62 ------------------- .../pages/vshn-managed/mariadb/create.adoc | 12 ++-- .../pages/vshn-managed/mariadb/delete.adoc | 41 ------------ .../pages/vshn-managed/mariadb/restore.adoc | 44 ------------- 5 files changed, 4 insertions(+), 157 deletions(-) delete mode 100644 docs/modules/ROOT/pages/vshn-managed/mariadb/backup.adoc delete mode 100644 docs/modules/ROOT/pages/vshn-managed/mariadb/restore.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 7924e89..d093e01 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -41,8 +41,6 @@ ** xref:vshn-managed/mariadb/usage.adoc[Usage] ** xref:vshn-managed/mariadb/delete.adoc[Deletion] ** xref:vshn-managed/mariadb/plans.adoc[] -** xref:vshn-managed/mariadb/backup.adoc[Backup] -** xref:vshn-managed/mariadb/restore.adoc[Restore] .Redis * xref:exoscale-dbaas/redis/index.adoc[On Exoscale] diff --git a/docs/modules/ROOT/pages/vshn-managed/mariadb/backup.adoc b/docs/modules/ROOT/pages/vshn-managed/mariadb/backup.adoc deleted file mode 100644 index c7ee7fd..0000000 --- a/docs/modules/ROOT/pages/vshn-managed/mariadb/backup.adoc +++ /dev/null @@ -1,62 +0,0 @@ -= Backups - -Backups are enabled by default. The MariaDB instance will be backed up daily at a randomly chosen time between 22:00 and 4:00. - -You can specify a different backup time and interval using the following backup configuration: - -[source,yaml] ----- -apiVersion: vshn.appcat.vshn.io/v1 -kind: VSHNMariaDB -metadata: - name: mariadb-app1-prod - namespace: -spec: - parameters: - ... - backup: - schedule: 0 22 * * * <1> - ... ----- -<1> The schedules for your backups. - -== Listing Backups - -Get an overview of all backups performed of your database instance: - -[source,bash] ----- -$ kubectl -n get vshnmariadbbackups -BACKUP ID DATABASE INSTANCE BACKUP TIME -6678cecd mariadb-app1-prod 2024-01-05T08:11:02Z -6df7d405 mariadb-app1-prod 2024-01-05T07:30:05Z -4bb23139 mariadb-app2-prod 2024-01-05T12:29:05Z -e5164ada mariadb-app2-prod 2024-01-05T12:33:02Z ----- -NOTE: The list will show all backups from all instances in this namespace. In the example above there are two database instances with two backups each. - -== Backup Details - -Learn more about a chosen backup: - -[source,bash] ----- -$ kubectl -n get vshnmariadbbackups 6678cecd -oyaml -apiVersion: api.appcat.vshn.io/v1 -kind: VSHNMariaDBBackup -metadata: - creationTimestamp: "2024-01-05T08:11:03Z" - generation: 1 - name: 6678cecd <1> - namespace: default - resourceVersion: "14581" - uid: ee105483-2a15-476b-b2d1-561526c74e25 -status: - date: "2024-01-05T08:11:02Z" <2> - id: 6678cecd3a006ff04111a3bd992c2a22183f7b69b2a8632dc365843341927c4a <3> - instance: mariadb-app1-prod <4> ----- -<1> Short ID of the backup -<2> The time when the backup finished -<3> Full ID of the backup, this is used for internal restore operations -<4> Name of the instance this backup belongs to diff --git a/docs/modules/ROOT/pages/vshn-managed/mariadb/create.adoc b/docs/modules/ROOT/pages/vshn-managed/mariadb/create.adoc index 11bf134..d5608cb 100644 --- a/docs/modules/ROOT/pages/vshn-managed/mariadb/create.adoc +++ b/docs/modules/ROOT/pages/vshn-managed/mariadb/create.adoc @@ -14,20 +14,16 @@ spec: parameters: service: version: "11.2" # <3> - mariadbSettings: | # <4> - [mariadb] - enable_slow_query_log - size: <5> + size: <4> plan: standard-2 writeConnectionSecretToRef: - name: mariadb-creds # <6> + name: mariadb-creds # <5> ---- <1> Instance name <2> The namespace where the object will be created <3> MariaDB version -<4> Specify custom MariaDB settings [optional] -<5> Size of the MariaDB instance. See xref:vshn-managed/mariadb/plans.adoc[Plans and Sizing] for more information. -<6> Secret where the connection details are provisioned. This secret shouldn't exist before creation. +<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] diff --git a/docs/modules/ROOT/pages/vshn-managed/mariadb/delete.adoc b/docs/modules/ROOT/pages/vshn-managed/mariadb/delete.adoc index d4afe77..c1a1300 100644 --- a/docs/modules/ROOT/pages/vshn-managed/mariadb/delete.adoc +++ b/docs/modules/ROOT/pages/vshn-managed/mariadb/delete.adoc @@ -14,44 +14,3 @@ $ oc delete vshnmariadb.vshn.appcat.vshn.io mariadb-app1-prod ==== If you delete the `VSHNMariaDB` object from the cluster, it will be deleted together with all of its data! ==== - -== Delete protected MariaDB instance - -A MariaDB instance that is protected from deletion cannot be deleted right away. -First disable deletion protection then delete the instance. - -. Disable deletion protection: -+ -[source,bash] ----- -$ oc edit vshnmariadb.vshn.appcat.vshn.io mariadb-app1-prod ----- -+ -[source,yaml] ----- -apiVersion: vshn.appcat.vshn.io/v1 -kind: VSHNMariaDB -metadata: - name: mariadb-app1-prod - namespace: prod-app -spec: - parameters: - backup: - deletionProtection: false # <1> - writeConnectionSecretToRef: - name: mariadb-creds ----- -<1> Make sure the parameter is set to false - -. Delete the instance -+ -[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! -==== diff --git a/docs/modules/ROOT/pages/vshn-managed/mariadb/restore.adoc b/docs/modules/ROOT/pages/vshn-managed/mariadb/restore.adoc deleted file mode 100644 index df0fe6e..0000000 --- a/docs/modules/ROOT/pages/vshn-managed/mariadb/restore.adoc +++ /dev/null @@ -1,44 +0,0 @@ -= Restores - -IMPORTANT: *Restore operation will create a new MariaDB instance with new credentials* - -By default, every mariadb instance creates a backup once a day or at the time you specified. - -Please visit the (xref:vshn-managed/mariadb/backup.adoc[Backup documentation] for more information. - -You can list all the backups that are available with the following command: - -[source,bash] ----- -kubectl -n get vshnmariadb - -BACKUP ID DATABASE INSTANCE BACKUP TIME -6678cecd mariadb-app1-prod 2024-01-05T08:11:02Z -6df7d405 mariadb-app1-prod 2024-01-05T07:30:05Z -4bb23139 mariadb-app2-prod 2024-01-05T12:29:05Z -e5164ada mariadb-app2-prod 2024-01-05T12:33:02Z ----- - -This will list all the backup available to you. -You can then restore the backup to a new instance, by using the following restore configuration: - -[source,yaml] ----- -apiVersion: vshn.appcat.vshn.io/v1 -kind: VSHNMariaDB -metadata: - name: mariadb-app2-prod - namespace: -spec: - parameters: - ... - restore: - claimName: mariadb-app1-prod <1> - backupName: e5164ada <2> - ... ----- -<1> The claimName of the original mariadb instance to restore from -<2> The Backup ID which you want to restore - -This configuration will spin up a new mariadb instance and will restore the specified backup to your instance. -In the example above, the new mariadb instance will be called `mariadb-app2-prod` and will be running the restored data from the mariadb instance `mariadb-app1-prod` using the backup `e5164ada` tat was taken at `2024-01-05T12:33:02Z` From 53975d8694d4197af4bf28eb3f1185a1916eaec6 Mon Sep 17 00:00:00 2001 From: Nicolas Bigler Date: Mon, 8 Jan 2024 16:10:40 +0100 Subject: [PATCH 3/3] Fix wrong references Signed-off-by: Nicolas Bigler --- docs/modules/ROOT/pages/vshn-managed/mariadb/usage.adoc | 2 +- docs/modules/ROOT/pages/vshn-managed/postgresql/usage.adoc | 2 +- docs/modules/ROOT/pages/vshn-managed/redis/usage.adoc | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/modules/ROOT/pages/vshn-managed/mariadb/usage.adoc b/docs/modules/ROOT/pages/vshn-managed/mariadb/usage.adoc index 8fd4747..4cbe82f 100644 --- a/docs/modules/ROOT/pages/vshn-managed/mariadb/usage.adoc +++ b/docs/modules/ROOT/pages/vshn-managed/mariadb/usage.adoc @@ -1,7 +1,7 @@ = Using a MariaDB service The YAML code below creates two objects: a `VSHNMariaDB` instance and a pod accessing it to show information about the instance. -The latter references the `redis-creds` secret that will contain the access keys required to connect to the instance. +The latter references the `mariadb-creds-connection` secret that will contain the access keys required to connect to the instance. [source,yaml] ---- diff --git a/docs/modules/ROOT/pages/vshn-managed/postgresql/usage.adoc b/docs/modules/ROOT/pages/vshn-managed/postgresql/usage.adoc index 5ac3edc..b0f699b 100644 --- a/docs/modules/ROOT/pages/vshn-managed/postgresql/usage.adoc +++ b/docs/modules/ROOT/pages/vshn-managed/postgresql/usage.adoc @@ -1,7 +1,7 @@ = Using a PostgreSQL service The YAML code below creates two objects: a `VSHNPostgreSQL` instance and a pod accessing it to show information about the instance. -The latter references the `postgres-creds` secret that will contain the access keys required to connect to the instance. +The latter references the `postgres-creds-connection` secret that will contain the access keys required to connect to the instance. [source,yaml] ---- diff --git a/docs/modules/ROOT/pages/vshn-managed/redis/usage.adoc b/docs/modules/ROOT/pages/vshn-managed/redis/usage.adoc index 9bc792e..af86d0e 100644 --- a/docs/modules/ROOT/pages/vshn-managed/redis/usage.adoc +++ b/docs/modules/ROOT/pages/vshn-managed/redis/usage.adoc @@ -1,7 +1,7 @@ = Using a Redis service The YAML code below creates two objects: a `VSHNRedis` instance and a pod accessing it to show information about the instance. -The latter references the `redis-creds` secret that will contain the access keys required to connect to the instance. +The latter references the `redis-creds-connection` secret that will contain the access keys required to connect to the instance. [source,yaml] ----