chore: update documentation for 1.28 - fixing admonitions

Signed-off-by: Leonardo Cecchi <[email protected]>

Author: leonardoce

versioned_docs/version-1.28/appendixes/backup_barmanobjectstore.md

@@ -7,13 +7,14 @@ title: Appendix B - Backup on object stores
 
 <!-- SPDX-License-Identifier: CC-BY-4.0 -->
 
-!!! Warning
+:::warning
     As of CloudNativePG 1.26, **native Barman Cloud support is deprecated** in
     favor of the **Barman Cloud Plugin**. This page has been moved to the appendix
     for reference purposes. While the native integration remains functional for
     now, we strongly recommend beginning a gradual migration to the plugin-based
     interface after appropriate testing.  For guidance, see
     [Migrating from Built-in CloudNativePG Backup](https://cloudnative-pg.io/plugin-barman-cloud/docs/migration/).
+:::
 
 CloudNativePG natively supports **online/hot backup** of PostgreSQL
 clusters through continuous physical backup and WAL archiving on an object
@@ -35,19 +36,21 @@ You can use the image `ghcr.io/cloudnative-pg/postgresql` for this scope,
 as it is composed of a community PostgreSQL image and the latest
 `barman-cli-cloud` package.
 
-!!! Important
+:::info[Important]
     Always ensure that you are running the latest version of the operands
     in your system to take advantage of the improvements introduced in
     Barman cloud (as well as improve the security aspects of your cluster).
+:::
 
-!!! Warning "Changes in Barman Cloud 3.16+ and Bucket Creation"
+:::warning[Changes in Barman Cloud 3.16+ and Bucket Creation]
     Starting with Barman Cloud 3.16, most Barman Cloud commands no longer
     automatically create the target bucket, assuming it already exists. Only the
     `barman-cloud-check-wal-archive` command creates the bucket now. Whenever this
     is not the first operation run on an empty bucket, CloudNativePG will throw an
     error. As a result, to ensure reliable, future-proof operations and avoid
     potential issues, we strongly recommend that you create and configure your
     object store bucket *before* creating a `Cluster` resource that references it.
+:::
 
 A backup is performed from a primary or a designated primary instance in a
 `Cluster` (please refer to
@@ -71,9 +74,10 @@ in CloudNativePG.
 The WAL archive is defined in the `.spec.backup.barmanObjectStore` stanza of
 a `Cluster` resource.
 
-!!! Info
+:::info
     Please refer to [`BarmanObjectStoreConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#BarmanObjectStoreConfiguration)
     in the barman-cloud API for a full list of options.
+:::
 
 If required, you can choose to compress WAL files as soon as they
 are uploaded and/or encrypt them:
@@ -98,14 +102,15 @@ PostgreSQL implements a sequential archiving scheme, where the
 `archive_command` will be executed sequentially for every WAL
 segment to be archived.
 
-!!! Important
+:::info[Important]
     By default, CloudNativePG sets `archive_timeout` to `5min`, ensuring
     that WAL files, even in case of low workloads, are closed and archived
     at least every 5 minutes, providing a deterministic time-based value for
     your Recovery Point Objective ([RPO](../before_you_start.md#rpo)). Even though you change the value
     of the [`archive_timeout` setting in the PostgreSQL configuration](https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-ARCHIVE-TIMEOUT),
     our experience suggests that the default value set by the operator is
     suitable for most use cases.
+:::
 
 When the bandwidth between the PostgreSQL instance and the object
 store allows archiving more than one WAL file in parallel, you
@@ -164,7 +169,7 @@ spec:
     retentionPolicy: "30d"
 ```
 
-!!! Note "There's more ..."
+:::note[There's more ...]
     The **recovery window retention policy** is focused on the concept of
     *Point of Recoverability* (`PoR`), a moving point in time determined by
     `current time - recovery window`. The *first valid backup* is the first
@@ -174,6 +179,7 @@ spec:
     file, starting from the first valid backup. Base backups that are older
     than the first valid backup will be marked as *obsolete* and permanently
     removed after the next backup is completed.
+:::
 
 ## Compression algorithms
 
@@ -338,16 +344,18 @@ are named `app` by default. If the PostgreSQL cluster being restored uses
 different names, you must specify these names before exiting the recovery phase,
 as documented in ["Configure the application database"](../recovery.md#configure-the-application-database).
 
-!!! Important
+:::info[Important]
     By default, the `recovery` method strictly uses the `name` of the
     cluster in the `externalClusters` section as the name of the main folder
     of the backup data within the object store. This name is normally reserved
     for the name of the server. You can specify a different folder name
     using the `barmanObjectStore.serverName` property.
+:::
 
-!!! Note
+:::note
     This example takes advantage of the parallel WAL restore feature,
     dedicating up to 8 jobs to concurrently fetch the required WAL files from the
     archive. This feature can appreciably reduce the recovery time. Make sure that
     you plan ahead for this scenario and correctly tune the value of this parameter
     for your environment. It will make a difference when you need it, and you will.
+:::

versioned_docs/version-1.28/appendixes/backup_volumesnapshot.md

@@ -6,10 +6,11 @@ title: Appendix A - Backup on volume snapshots
 # Appendix A - Backup on volume snapshots
 <!-- SPDX-License-Identifier: CC-BY-4.0 -->
 
-!!! Important
+:::info[Important]
     Please refer to the official Kubernetes documentation for a list of all
     the supported [Container Storage Interface (CSI) drivers](https://kubernetes-csi.github.io/docs/drivers.html)
     that provide snapshotting capabilities.
+:::
 
 CloudNativePG is one of the first known cases of database operators that
 directly leverages the Kubernetes native Volume Snapshot API for both
@@ -53,20 +54,22 @@ that is responsible to ensure that snapshots can be taken from persistent
 volumes of a given storage class, and managed as `VolumeSnapshot` and
 `VolumeSnapshotContent` resources.
 
-!!! Important
+:::info[Important]
     It is your responsibility to verify with the third party vendor
     that volume snapshots are supported. CloudNativePG only interacts
     with the Kubernetes API on this matter, and we cannot support issues
     at the storage level for each specific CSI driver.
+:::
 
 ## How to configure Volume Snapshot backups
 
 CloudNativePG allows you to configure a given Postgres cluster for Volume
 Snapshot backups through the `backup.volumeSnapshot` stanza.
 
-!!! Info
-    Please refer to [`VolumeSnapshotConfiguration`](../cloudnative-pg.v1.md#postgresql-cnpg-io-v1-VolumeSnapshotConfiguration)
+:::info
+    Please refer to [`VolumeSnapshotConfiguration`](../cloudnative-pg.v1.md#volumesnapshotconfiguration)
     in the API reference for a full list of options.
+:::
 
 A generic example with volume snapshots (assuming that PGDATA and WALs share
 the same storage class) is the following:
@@ -102,32 +105,35 @@ As you can see, the `backup` section contains both the `volumeSnapshot` stanza
 (controlling physical base backups on volume snapshots) and the
 `plugins` one (controlling the [WAL archive](../wal_archiving.md)).
 
-!!! Info
+:::info
     Once you have defined the `plugin`, you can decide to use
     both volume snapshot and plugin backup strategies simultaneously
     to take physical backups.
+:::
 
 The `volumeSnapshot.className` option allows you to reference the default
 `VolumeSnapshotClass` object used for all the storage volumes you have
 defined in your PostgreSQL cluster.
 
-!!! Info
+:::info
     In case you are using a different storage class for `PGDATA` and
     WAL files, you can specify a separate `VolumeSnapshotClass` for
     that volume through the `walClassName` option (which defaults to
     the same value as `className`).
+:::
 
 Once a cluster is defined for volume snapshot backups, you need to define
 a `ScheduledBackup` resource that requests such backups on a periodic basis.
 
 ## Hot and cold backups
 
-!!! Warning
+:::warning
     As noted in the [backup document](../backup.md), a cold snapshot explicitly
     set to target the primary will result in the primary being fenced for
     the duration of the backup, making the cluster read-only during this
     period. For safety, in a cluster already containing fenced instances, a cold
     snapshot is rejected.
+:::
 
 By default, CloudNativePG requests an online/hot backup on volume snapshots, using the
 [PostgreSQL defaults of the low-level API for base backups](https://www.postgresql.org/docs/current/continuous-archiving.html#BACKUP-LOWLEVEL-BASE-BACKUP):
@@ -136,12 +142,13 @@ By default, CloudNativePG requests an online/hot backup on volume snapshots, usi
 - it waits for the WAL archiver to archive the last segment of the backup when
   terminating the backup procedure
 
-!!! Important
+:::info[Important]
     The default values are suitable for most production environments. Hot
     backups are consistent and can be used to perform snapshot recovery, as we
     ensure WAL retention from the start of the backup through a temporary
     replication slot. However, our recommendation is to rely on cold backups for
     that purpose.
+:::
 
 You can explicitly change the default behavior through the following options in
 the `.spec.backup.volumeSnapshot` stanza of the `Cluster` resource:
@@ -241,13 +248,14 @@ In case a `VolumeSnapshot` is deleted, the `deletionPolicy` specified in the
 - if set to `Retain`, the `VolumeSnapshotContent` object is kept
 - if set to `Delete`, the `VolumeSnapshotContent` object is removed as well
 
-!!! Warning
+:::warning
     `VolumeSnapshotContent` objects do not keep all the information regarding the
     backup and the cluster they refer to (like the annotations and labels that
     are contained in the `VolumeSnapshot` object). Although possible, restoring
     from just this kind of object might not be straightforward. For this reason,
     our recommendation is to always backup the `VolumeSnapshot` definitions,
     even using a Kubernetes level data protection solution.
+:::
 
 The value in `VolumeSnapshotContent` is determined by the `deletionPolicy` set
 in the corresponding `VolumeSnapshotClass` definition, which is
@@ -350,11 +358,11 @@ The following example shows how to configure volume snapshot base backups on an
 EKS cluster on AWS using the `ebs-sc` storage class and the `csi-aws-vsc`
 volume snapshot class.
 
-!!! Important
+:::info[Important]
     If you are interested in testing the example, please read
     ["Volume Snapshots" for the Amazon Elastic Block Store (EBS) CSI driver](https://github.com/kubernetes-sigs/aws-ebs-csi-driver/tree/master/examples/kubernetes/snapshot) <!-- wokeignore:rule=master -->
     for detailed instructions on the installation process for the storage class and the snapshot class.
-
+:::
 
 The following manifest creates a `Cluster` that is ready to be used for volume
 snapshots and that stores the WAL archive in a S3 bucket via IAM role for the

versioned_docs/version-1.28/appendixes/object_stores.md

@@ -6,13 +6,14 @@ title: Appendix C - Common object stores for backups
 # Appendix C - Common object stores for backups
 <!-- SPDX-License-Identifier: CC-BY-4.0 -->
 
-!!! Warning
+:::warning
     As of CloudNativePG 1.26, **native Barman Cloud support is deprecated** in
     favor of the **Barman Cloud Plugin**. While the native integration remains
     functional for now, we strongly recommend beginning a gradual migration to
     the plugin-based interface after appropriate testing. The Barman Cloud
     Plugin documentation describes
     [how to use common object stores](https://cloudnative-pg.io/plugin-barman-cloud/docs/object_stores/).
+:::
 
 You can store the [backup](../backup.md) files in any service that is supported
 by the Barman Cloud infrastructure. That is:
@@ -183,10 +184,11 @@ spec:
         key: ca.crt
 ```
 
-!!! Note
+:::note
     If you want ConfigMaps and Secrets to be **automatically** reloaded by instances, you can
     add a label with key `cnpg.io/reload` to the Secrets/ConfigMaps. Otherwise, you will have to reload
     the instances using the `kubectl cnpg reload` subcommand.
+:::
 
 ## Azure Blob Storage
 
@@ -351,7 +353,8 @@ spec:
 
 Now the operator will use the credentials to authenticate against Google Cloud Storage.
 
-!!! Important
+:::info[Important]
     This way of authentication will create a JSON file inside the container with all the needed
     information to access your Google Cloud Storage bucket, meaning that if someone gets access to the pod
     will also have write permissions to the bucket.
+:::

versioned_docs/version-1.28/applications.md

@@ -13,10 +13,11 @@ in the same Kubernetes cluster.
 For more information on services and how to manage them, please refer to the
 ["Service management"](service_management.md) section.
 
-!!! Hint
+:::tip[Hint]
     It is highly recommended using those services in your applications,
     and avoiding connecting directly to a specific PostgreSQL instance, as the latter
     can change during the cluster lifetime.
+:::
 
 You can use these services in your applications through:
 
@@ -26,10 +27,11 @@ You can use these services in your applications through:
 For the credentials to connect to PostgreSQL, you can
 use the secrets generated by the operator.
 
-!!! Seealso "Connection Pooling"
+:::note[Connection Pooling]
     Please refer to the ["Connection Pooling" section](connection_pooling.md) for
     information about how to take advantage of PgBouncer as a connection pooler,
     and create an access layer between your applications and the PostgreSQL clusters.
+:::
 
 ### DNS resolution
 
@@ -93,5 +95,6 @@ database.
 The `-superuser` ones are supposed to be used only for administrative purposes,
 and correspond to the `postgres` user.
 
-!!! Important
+:::info[Important]
     Superuser access over the network is disabled by default.
+:::