chore: update documentation for 1.25 - fixing admonitions

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

Author: leonardoce

versioned_docs/version-1.25/appendixes/object_stores.md

@@ -1,20 +1,11 @@
 ---
 id: object_stores
-title: object_stores
+title: Appendix A - Common object stores for backups
 ---
 
-# Appendix C - Common object stores for backups
+# Appendix A - Common object stores for backups
 <!-- SPDX-License-Identifier: CC-BY-4.0 -->
 
-:::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:
 
@@ -353,8 +344,133 @@ 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.
 :::
+
+## MinIO Gateway
+
+Optionally, you can use MinIO Gateway as a common interface which
+relays backup objects to other cloud storage solutions, like S3 or GCS.
+For more information, please refer to [MinIO official documentation](https://docs.min.io/).
+
+Specifically, the CloudNativePG cluster can directly point to a local
+MinIO Gateway as an endpoint, using previously created credentials and service.
+
+MinIO secrets will be used by both the PostgreSQL cluster and the MinIO instance.
+Therefore, you must create them in the same namespace:
+
+```sh
+kubectl create secret generic minio-creds \
+  --from-literal=MINIO_ACCESS_KEY=<minio access key here> \
+  --from-literal=MINIO_SECRET_KEY=<minio secret key here>
+```
+
+:::note
+    Cloud Object Storage credentials will be used only by MinIO Gateway in this case.
+:::
+
+:::info[Important]
+    In order to allow PostgreSQL to reach MinIO Gateway, it is necessary to create a
+    `ClusterIP` service on port `9000` bound to the MinIO Gateway instance.
+:::
+
+For example:
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: minio-gateway-service
+spec:
+  type: ClusterIP
+  ports:
+    - port: 9000
+      targetPort: 9000
+      protocol: TCP
+  selector:
+    app: minio
+```
+
+:::warning
+    At the time of writing this documentation, the official
+    [MinIO Operator](https://github.com/minio/minio-operator/issues/71)
+    for Kubernetes does not support the gateway feature. As such, we will use a
+    `deployment` instead.
+:::
+
+The MinIO deployment will use cloud storage credentials to upload objects to the
+remote bucket and relay backup files to different locations.
+
+Here is an example using AWS S3 as Cloud Object Storage:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+[...]
+spec:
+  containers:
+  - name: minio
+    image: minio/minio:RELEASE.2020-06-03T22-13-49Z
+    args:
+    - gateway
+    - s3
+    env:
+    # MinIO access key and secret key
+    - name: MINIO_ACCESS_KEY
+      valueFrom:
+        secretKeyRef:
+          name: minio-creds
+          key: MINIO_ACCESS_KEY
+    - name: MINIO_SECRET_KEY
+      valueFrom:
+        secretKeyRef:
+          name: minio-creds
+          key: MINIO_SECRET_KEY
+    # AWS credentials
+    - name: AWS_ACCESS_KEY_ID
+      valueFrom:
+        secretKeyRef:
+          name: aws-creds
+          key: ACCESS_KEY_ID
+    - name: AWS_SECRET_ACCESS_KEY
+      valueFrom:
+        secretKeyRef:
+          name: aws-creds
+          key: ACCESS_SECRET_KEY
+# Uncomment the below section if session token is required
+#   - name: AWS_SESSION_TOKEN
+#     valueFrom:
+#       secretKeyRef:
+#         name: aws-creds
+#         key: ACCESS_SESSION_TOKEN
+        ports:
+        - containerPort: 9000
+```
+
+Proceed by configuring MinIO Gateway service as the `endpointURL` in the `Cluster`
+definition, then choose a bucket name to replace `BUCKET_NAME`:
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: Cluster
+[...]
+spec:
+  backup:
+    barmanObjectStore:
+      destinationPath: s3://BUCKET_NAME/
+      endpointURL: http://minio-gateway-service:9000
+      s3Credentials:
+        accessKeyId:
+          name: minio-creds
+          key: MINIO_ACCESS_KEY
+        secretAccessKey:
+          name: minio-creds
+          key: MINIO_SECRET_KEY
+    [...]
+```
+
+Verify on `s3://BUCKET_NAME/` the presence of archived WAL files before
+proceeding with a backup.

versioned_docs/version-1.25/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.25/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,25 +427,24 @@ 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.
 :::
 
-In the example above, the designated primary receives WAL updates via streaming
-replication (`primary_conninfo`). As a fallback, it can retrieve WAL segments
-from an object store using file-based WAL shipping—for instance, with the
-Barman Cloud plugin through `restore_command` and `barman-cloud-wal-restore`.
+The designated primary in the above example is fed via WAL streaming
+(`primary_conninfo`), with fallback option for file-based WAL shipping through
+the `restore_command` and `barman-cloud-wal-restore`.
 
 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.
-:::
+:::