chore: update documentation for 1.27 - fixing admonitions

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

Author: leonardoce

versioned_docs/version-1.27/appendixes/backup_barmanobjectstore.md

@@ -1,6 +1,6 @@
 ---
 id: backup_barmanobjectstore
-title: backup_barmanobjectstore
+title: Appendix B - Backup on object stores
 ---
 
 # Appendix B - Backup on object stores
@@ -36,12 +36,22 @@ 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]
+    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
 [replica clusters](../replica_cluster.md)
@@ -92,7 +102,7 @@ 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
@@ -159,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
@@ -334,7 +344,7 @@ 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
@@ -348,4 +358,4 @@ as documented in ["Configure the application database"](../recovery.md#configure
     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.27/appendixes/backup_volumesnapshot.md

@@ -1,12 +1,12 @@
 ---
 id: backup_volumesnapshot
-title: backup_volumesnapshot
+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.
@@ -54,7 +54,7 @@ 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
@@ -67,7 +67,7 @@ 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)
+    Please refer to [`VolumeSnapshotConfiguration`](../cloudnative-pg.v1.md#volumesnapshotconfiguration)
     in the API reference for a full list of options.
 :::
 
@@ -142,7 +142,7 @@ 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
@@ -358,7 +358,7 @@ 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.

versioned_docs/version-1.27/appendixes/object_stores.md

@@ -1,6 +1,6 @@
 ---
 id: object_stores
-title: object_stores
+title: Appendix C - Common object stores for backups
 ---
 
 # Appendix C - Common object stores for backups
@@ -353,8 +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.27/applications.md

@@ -1,10 +1,10 @@
 ---
 id: applications
-sidebar_position: 35
-title: Connecting from an Application
+sidebar_position: 340
+title: Connecting from an application
 ---
 
-# Connecting from an Application
+# Connecting from an application
 <!-- SPDX-License-Identifier: CC-BY-4.0 -->
 
 Applications are supposed to work with the services created by CloudNativePG
@@ -13,7 +13,7 @@ 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.
 
-:::info
+:::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.
@@ -27,7 +27,7 @@ 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.
 
-:::tip 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.
@@ -95,6 +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.
-:::
+:::

versioned_docs/version-1.27/architecture.md

@@ -1,13 +1,13 @@
 ---
 id: architecture
-sidebar_position: 5
+sidebar_position: 40
 title: Architecture
 ---
 
 # Architecture
 <!-- SPDX-License-Identifier: CC-BY-4.0 -->
 
-:::tip
+:::tip[Hint]
     For a deeper understanding, we recommend reading our article on the CNCF
     blog post titled ["Recommended Architectures for PostgreSQL in Kubernetes"](https://www.cncf.io/blog/2023/09/29/recommended-architectures-for-postgresql-in-kubernetes/),
     which provides valuable insights into best practices and design
@@ -57,7 +57,7 @@ used as a fallback option, for example, to store WAL files in an object store).
 Replicas are usually called *standby servers* and can also be used for
 read-only workloads, thanks to the *Hot Standby* feature.
 
-:::important
+:::info[Important]
     **We recommend against storage-level replication with PostgreSQL**, although
     CloudNativePG allows you to adopt that strategy. For more information, please refer
     to the talk given by Chris Milsted and Gabriele Bartolini at KubeCon NA 2022 entitled
@@ -91,7 +91,7 @@ The multi-availability zone Kubernetes architecture with three (3) or more
 zones is the one that we recommend for PostgreSQL usage.
 This scenario is typical of Kubernetes services managed by Cloud Providers.
 
-![Kubernetes cluster spanning over 3 independent data centers](/img/k8s-architecture-3-az.png)
+![Kubernetes cluster spanning over 3 independent data centers](./images/k8s-architecture-3-az.png)
 
 Such an architecture enables the CloudNativePG operator to control the full
 lifecycle of a `Cluster` resource across the zones within a single Kubernetes
@@ -113,15 +113,15 @@ to deploy distributed PostgreSQL topologies hosting "passive"
 managing them via declarative configuration. This setup is ideal for disaster
 recovery (DR), read-only operations, or cross-region availability.
 
-:::important
+:::info[Important]
     Each operator deployment can only manage operations within its local
     Kubernetes cluster. For operations across Kubernetes clusters, such as
     controlled switchover or unexpected failover, coordination must be handled
     manually (through GitOps, for example) or by using a higher-level cluster
     management tool.
 :::
 
-![Example of a multiple Kubernetes cluster architecture distributed over 3 regions each with 3 independent data centers](/img/k8s-architecture-multi.png)
+![Example of a multiple Kubernetes cluster architecture distributed over 3 regions each with 3 independent data centers](./images/k8s-architecture-multi.png)
 
 ### Single availability zone Kubernetes clusters
 
@@ -143,9 +143,9 @@ Kubernetes clusters in an active/passive configuration, with the second cluster
 primarily used for Disaster Recovery (see
 the [replica cluster feature](replica_cluster.md)).
 
-![Example of a Kubernetes architecture with only 2 data centers](/img/k8s-architecture-2-az.png)
+![Example of a Kubernetes architecture with only 2 data centers](./images/k8s-architecture-2-az.png)
 
-:::tip
+:::tip[Hint]
     If you are at an early stage of your Kubernetes journey, please share this
     document with your infrastructure team. The two data centers setup might
     be simply the result of a "lift-and-shift" transition to Kubernetes
@@ -179,7 +179,7 @@ is now fully declarative, automated failover across Kubernetes clusters is not
 within CloudNativePG's scope, as the operator can only function within a single
 Kubernetes cluster.
 
-:::important
+:::info[Important]
     CloudNativePG provides all the necessary primitives and probes to
     coordinate PostgreSQL active/passive topologies across different Kubernetes
     clusters through a higher-level operator or management tool.
@@ -195,7 +195,7 @@ PostgreSQL workloads is referred to as a **Postgres node** or `postgres` node.
 This approach ensures optimal performance and resource allocation for your
 database operations.
 
-:::hint
+:::tip[Hint]
     As a general rule of thumb, deploy Postgres nodes in multiples of
     three—ideally with one node per availability zone. Three nodes is
     an optimal number because it ensures that a PostgreSQL cluster with three
@@ -209,7 +209,7 @@ labels ensure that a node is capable of running `postgres` workloads, while
 taints help prevent any non-`postgres` workloads from being scheduled on that
 node.
 
-:::important
+:::info[Important]
     This methodology is the most straightforward way to ensure that PostgreSQL
     workloads are isolated from other workloads in terms of both computing
     resources and, when using locally attached disks, storage. While different
@@ -289,7 +289,7 @@ Kubernetes cluster, with the following specifications:
     * PostgreSQL instances should reside in different availability zones
       within the same Kubernetes cluster / region
 
-:::important
+:::info[Important]
     You can configure the above services through the `managed.services` section
     in the `Cluster` configuration. This can be done by reducing the number of
     services and selecting the type (default is `ClusterIP`). For more details,
@@ -302,26 +302,26 @@ architecture for a PostgreSQL cluster spanning across 3 different availability
 zones, running on separate nodes, each with dedicated local storage for
 PostgreSQL data.
 
-![Bird-eye view of the recommended shared nothing architecture for PostgreSQL in Kubernetes](/img/k8s-pg-architecture.png)
+![Bird-eye view of the recommended shared nothing architecture for PostgreSQL in Kubernetes](./images/k8s-pg-architecture.png)
 
 CloudNativePG automatically takes care of updating the above services if
 the topology of the cluster changes. For example, in case of failover, it
 automatically updates the `-rw` service to point to the promoted primary,
 making sure that traffic from the applications is seamlessly redirected.
 
-:::info Replication
+:::note[Replication]
     Please refer to the ["Replication" section](replication.md) for more
     information about how CloudNativePG relies on PostgreSQL replication,
     including synchronous settings.
 :::
 
-:::info Connecting from an application
+:::note[Connecting from an application]
     Please refer to the ["Connecting from an application" section](applications.md) for
     information about how to connect to CloudNativePG from a stateless
     application within the same Kubernetes cluster.
 :::
 
-:::info 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.
@@ -333,7 +333,7 @@ Applications can decide to connect to the PostgreSQL instance elected as
 *current primary* by the Kubernetes operator, as depicted in the following
 diagram:
 
-![Applications writing to the single primary](/img/architecture-rw.png)
+![Applications writing to the single primary](./images/architecture-rw.png)
 
 Applications can use the `-rw` suffix service.
 
@@ -343,7 +343,7 @@ service to another instance of the cluster.
 
 ### Read-only workloads
 
-:::important
+:::info[Important]
     Applications must be aware of the limitations that
     [Hot Standby](https://www.postgresql.org/docs/current/hot-standby.html)
     presents and familiar with the way PostgreSQL operates when dealing with
@@ -356,7 +356,7 @@ primary node.
 
 The following diagram shows the architecture:
 
-![Applications reading from hot standby replicas in round robin](/img/architecture-read-only.png)
+![Applications reading from hot standby replicas in round robin](./images/architecture-read-only.png)
 
 Applications can also access any PostgreSQL instance through the
 `-r` service.
@@ -400,7 +400,7 @@ cluster and the replica cluster is in the second. The second Kubernetes cluster
 acts as the company's disaster recovery cluster, ready to be activated in case
 of disaster and unavailability of the first one.
 
-![An example of multi-cluster deployment with a primary and a replica cluster](/img/multi-cluster.png)
+![An example of multi-cluster deployment with a primary and a replica cluster](./images/multi-cluster.png)
 
 A replica cluster can have the same architecture as the primary cluster.
 Instead of a primary instance, a replica cluster has a **designated primary**
@@ -427,7 +427,7 @@ This is typically triggered by:
     cluster-aware authority.
 :::
 
-:::important
+:::info[Important]
     CloudNativePG allows you to control the distributed topology via
     declarative configuration, enabling you to automate these procedures as part of
     your Infrastructure as Code (IaC) process, including GitOps.
@@ -442,10 +442,10 @@ CloudNativePG allows you to define topologies with multiple replica clusters.
 You can also define replica clusters with a lower number of replicas, and then
 increase this number when the cluster is promoted to primary.
 
-:::info Replica clusters
+:::note[Replica clusters]
     Please refer to the ["Replica Clusters" section](replica_cluster.md) for
     more detailed information on how physical replica clusters operate and how to
     define a distributed topology with read-only clusters across different
     Kubernetes clusters. This approach can significantly enhance your global
     disaster recovery and high availability (HA) strategy.
-:::
+:::