docs: updated 1.23, 1.24 and 1.25 (#250)

Closes #246

Signed-off-by: Gabriele Bartolini <[email protected]>

Author: gbartolini

assets/documentation/1.23/appendixes/object_stores/index.html

@@ -269,6 +269,8 @@
     <li class="toctree-l3"><a class="reference internal" href="#s3-lifecycle-policy">S3 lifecycle policy</a>
     </li>
     <li class="toctree-l3"><a class="reference internal" href="#other-s3-compatible-object-storages-providers">Other S3-compatible Object Storages providers</a>
+    </li>
+    <li class="toctree-l3"><a class="reference internal" href="#using-object-storage-with-a-private-ca">Using Object Storage with a private CA</a>
     </li>
         </ul>
     </li>
@@ -435,12 +437,28 @@ <h3 id="other-s3-compatible-object-storages-providers">Other S3-compatible Objec
       s3Credentials:
         [...]
 </code></pre>
-<div class="admonition important">
-<p class="admonition-title">Important</p>
-<p>Suppose you configure an Object Storage provider which uses a certificate signed with a private CA,
-like when using MinIO via HTTPS. In that case, you need to set the option <code>endpointCA</code>
-referring to a secret containing the CA bundle so that Barman can verify the certificate correctly.</p>
-</div>
+<h3 id="using-object-storage-with-a-private-ca">Using Object Storage with a private CA</h3>
+<p>Suppose you configure an Object Storage provider which uses a certificate
+signed with a private CA, for example when using MinIO via HTTPS. In that case,
+you need to set the option <code>endpointCA</code> inside <code>barmanObjectStore</code> referring
+to a secret containing the CA bundle, so that Barman can verify the certificate
+correctly.
+You can find instructions on creating a secret using your cert files in the
+<a href="../../certificates/#example">certificates</a> document.
+Once you have created the secret, you can populate the <code>endpointCA</code> as in the
+following example:</p>
+<pre><code class="language-yaml">apiVersion: postgresql.cnpg.io/v1
+kind: Cluster
+[...]
+spec:
+  [...]
+  backup:
+    barmanObjectStore:
+      endpointURL: &lt;myEndpointURL&gt;
+      endpointCA:
+        name: my-ca-secret
+        key: ca.crt
+</code></pre>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
 <p>If you want ConfigMaps and Secrets to be <strong>automatically</strong> reloaded by instances, you can
@@ -475,7 +493,7 @@ <h2 id="azure-blob-storage">Azure Blob Storage</h2>
 <p>On the other side, using both <strong>Storage account access key</strong> or <strong>Storage account SAS Token</strong>,
 the credentials need to be stored inside a Kubernetes Secret, adding data entries only when
 needed. The following command performs that:</p>
-<pre><code>kubectl create secret generic azure-creds \
+<pre><code class="language-sh">kubectl create secret generic azure-creds \
   --from-literal=AZURE_STORAGE_ACCOUNT=&lt;storage account name&gt; \
   --from-literal=AZURE_STORAGE_KEY=&lt;storage account key&gt; \
   --from-literal=AZURE_STORAGE_SAS_TOKEN=&lt;SAS token&gt; \
@@ -508,14 +526,14 @@ <h2 id="azure-blob-storage">Azure Blob Storage</h2>
 </code></pre>
 <p>When using the Azure Blob Storage, the <code>destinationPath</code> fulfills the following
 structure:</p>
-<pre><code>&lt;http|https&gt;://&lt;account-name&gt;.&lt;service-name&gt;.core.windows.net/&lt;resource-path&gt;
+<pre><code class="language-sh">&lt;http|https&gt;://&lt;account-name&gt;.&lt;service-name&gt;.core.windows.net/&lt;resource-path&gt;
 </code></pre>
 <p>where <code>&lt;resource-path&gt;</code> is <code>&lt;container&gt;/&lt;blob&gt;</code>. The <strong>account name</strong>,
 which is also called <strong>storage account name</strong>, is included in the used host name.</p>
 <h3 id="other-azure-blob-storage-compatible-providers">Other Azure Blob Storage compatible providers</h3>
 <p>If you are using a different implementation of the Azure Blob Storage APIs,
 the <code>destinationPath</code> will have the following structure:</p>
-<pre><code>&lt;http|https&gt;://&lt;local-machine-address&gt;:&lt;port&gt;/&lt;account-name&gt;/&lt;resource-path&gt;
+<pre><code class="language-sh">&lt;http|https&gt;://&lt;local-machine-address&gt;:&lt;port&gt;/&lt;account-name&gt;/&lt;resource-path&gt;
 </code></pre>
 <p>In that case, <code>&lt;account-name&gt;</code> is the first component of the path.</p>
 <p>This is required if you are testing the Azure support via the Azure Storage

assets/documentation/1.23/architecture/index.html

@@ -517,11 +517,12 @@ <h2 id="deployments-across-kubernetes-clusters">Deployments across Kubernetes cl
 only write inside a single Kubernetes cluster, at any time.</p>
 <p>However, for business continuity objectives it is fundamental to:</p>
 <ul>
-<li>reduce global <strong>recovery point objectives</strong> (RPO) by storing PostgreSQL backup data
-  in multiple locations, regions and possibly using different providers
-  (Disaster Recovery)</li>
-<li>reduce global <strong>recovery time objectives</strong> (RTO) by taking advantage of PostgreSQL
-  replication beyond the primary Kubernetes cluster (High Availability)</li>
+<li>reduce global <strong>recovery point objectives</strong> (<a href="../before_you_start/#rpo">RPO</a>)
+  by storing PostgreSQL backup data in multiple locations, regions and possibly
+  using different providers (Disaster Recovery)</li>
+<li>reduce global <strong>recovery time objectives</strong> (<a href="../before_you_start/#rto">RTO</a>)
+  by taking advantage of PostgreSQL replication beyond the primary Kubernetes
+  cluster (High Availability)</li>
 </ul>
 <p>In order to address the above concerns, CloudNativePG introduces the
 concept of a <em>PostgreSQL Replica Cluster</em>. Replica clusters are the

assets/documentation/1.23/backup/index.html

@@ -373,7 +373,8 @@ <h2 id="wal-archive">WAL archive</h2>
 as they can simply rely on the WAL archive to synchronize across long
 distances, extending disaster recovery goals across different regions.</p>
 <p>When you <a href="../wal_archiving/">configure a WAL archive</a>, CloudNativePG provides
-out-of-the-box an RPO &lt;= 5 minutes for disaster recovery, even across regions.</p>
+out-of-the-box an <a href="../before_you_start/#rpo">RPO</a> &lt;= 5 minutes for disaster
+recovery, even across regions.</p>
 <div class="admonition important">
 <p class="admonition-title">Important</p>
 <p>Our recommendation is to always setup the WAL archive in production.
@@ -419,9 +420,9 @@ <h2 id="object-stores-or-volume-snapshots-which-one-to-use">Object stores or vol
 <li>availability of a trusted storage class that supports volume snapshots</li>
 <li>size of the database: with object stores, the larger your database, the
   longer backup and, most importantly, recovery procedures take (the latter
-  impacts RTO); in presence of Very Large Databases (VLDB), the general
-  advice is to rely on Volume Snapshots as, thanks to copy-on-write, they
-  provide faster recovery</li>
+  impacts <a href="../before_you_start/#rto">RTO</a>); in presence of Very Large Databases
+  (VLDB), the general advice is to rely on Volume Snapshots as, thanks to
+  copy-on-write, they provide faster recovery</li>
 <li>data mobility and possibility to store or relay backup files on a
   secondary location in a different region, or any subsequent one</li>
 <li>other factors, mostly based on the confidence and familiarity with the
@@ -528,7 +529,7 @@ <h2 id="scheduled-backups">Scheduled backups</h2>
 are not included.</p>
 <div class="admonition hint">
 <p class="admonition-title">Hint</p>
-<p>Backup frequency might impact your recovery time object (RTO) after a
+<p>Backup frequency might impact your recovery time objective (<a href="../before_you_start/#rto">RTO</a>) after a
 disaster which requires a full or Point-In-Time recovery operation. Our
 advice is that you regularly test your backups by recovering them, and then
 measuring the time it takes to recover from scratch so that you can refine

assets/documentation/1.23/backup_barmanobjectstore/index.html

@@ -383,9 +383,9 @@ <h2 id="compression-algorithms">Compression algorithms</h2>
 <li>snappy</li>
 </ul>
 <p>The compression settings for backups and WALs are independent. See the
-<a href="../cloudnative-pg.v1/#postgresql-cnpg-io-v1-DataBackupConfiguration">DataBackupConfiguration</a> and
-<a href="../cloudnative-pg.v1/#postgresql-cnpg-io-v1-WalBackupConfiguration">WALBackupConfiguration</a> sections in
-the API reference.</p>
+<a href="https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#DataBackupConfiguration">DataBackupConfiguration</a> and
+<a href="https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#WalBackupConfiguration">WALBackupConfiguration</a> sections in
+the barman-cloud API reference.</p>
 <p>It is important to note that archival time, restore time, and size change
 between the algorithms, so the compression algorithm should be chosen according
 to your use case.</p>

assets/documentation/1.23/before_you_start/index.html

@@ -397,6 +397,12 @@ <h2 id="postgresql-terminology">PostgreSQL terminology</h2>
 <dd>A PVC group in CloudNativePG's terminology is a group of related PVCs
   belonging to the same PostgreSQL instance, namely the main volume containing
   the PGDATA (<code>storage</code>) and the volume for WALs (<code>walStorage</code>).</dd>
+<dt><a id="rto"></a>RTO</dt>
+<dd>Acronym for "recovery time objective", the amount of time a system can be
+  unavailable without adversely impacting the application.</dd>
+<dt><a id="rpo"></a>RPO</dt>
+<dd>Acronym for "recovery point objective", a calculation of the level of
+  acceptable data loss following a disaster recovery scenario.</dd>
 </dl>
 <h2 id="cloud-terminology">Cloud terminology</h2>
 <dl>

assets/documentation/1.23/bootstrap/index.html

@@ -774,7 +774,7 @@ <h4 id="usernamepassword-authentication">Username/Password authentication</h4>
 <pre><code># A more restrictive rule for TLS and IP of origin is recommended
 host replication streaming_replica all md5
 </code></pre>
-<p>The following manifest creates a new PostgreSQL 17.0 cluster,
+<p>The following manifest creates a new PostgreSQL 17.2 cluster,
 called <code>target-db</code>, using the <code>pg_basebackup</code> bootstrap method
 to clone an external PostgreSQL cluster defined as <code>source-db</code>
 (in the <code>externalClusters</code> array). As you can see, the <code>source-db</code>
@@ -787,7 +787,7 @@ <h4 id="usernamepassword-authentication">Username/Password authentication</h4>
   name: target-db
 spec:
   instances: 3
-  imageName: ghcr.io/cloudnative-pg/postgresql:17.0
+  imageName: ghcr.io/cloudnative-pg/postgresql:17.2
 
   bootstrap:
     pg_basebackup:
@@ -806,7 +806,7 @@ <h4 id="usernamepassword-authentication">Username/Password authentication</h4>
       key: password
 </code></pre>
 <p>All the requirements must be met for the clone operation to work, including
-the same PostgreSQL version (in our case 17.0).</p>
+the same PostgreSQL version (in our case 17.2).</p>
 <h4 id="tls-certificate-authentication">TLS certificate authentication</h4>
 <p>The second authentication method supported by CloudNativePG
 with the <code>pg_basebackup</code> bootstrap is based on TLS client certificates.
@@ -818,7 +818,7 @@ <h4 id="tls-certificate-authentication">TLS certificate authentication</h4>
 <p>This example can be easily adapted to cover an instance that resides
 outside the Kubernetes cluster.</p>
 </div>
-<p>The manifest defines a new PostgreSQL 17.0 cluster called <code>cluster-clone-tls</code>,
+<p>The manifest defines a new PostgreSQL 17.2 cluster called <code>cluster-clone-tls</code>,
 which is bootstrapped using the <code>pg_basebackup</code> method from the <code>cluster-example</code>
 external cluster. The host is identified by the read/write service
 in the same cluster, while the <code>streaming_replica</code> user is authenticated
@@ -831,7 +831,7 @@ <h4 id="tls-certificate-authentication">TLS certificate authentication</h4>
   name: cluster-clone-tls
 spec:
   instances: 3
-  imageName: ghcr.io/cloudnative-pg/postgresql:17.0
+  imageName: ghcr.io/cloudnative-pg/postgresql:17.2
 
   bootstrap:
     pg_basebackup:

assets/documentation/1.23/certificates/index.html

@@ -431,11 +431,11 @@ <h4 id="example">Example</h4>
 <li><code>server.key</code> – The private key of the server TLS certificate.</li>
 </ul>
 <p>Create a secret containing the CA certificate:</p>
-<pre><code>kubectl create secret generic my-postgresql-server-ca \
+<pre><code class="language-sh">kubectl create secret generic my-postgresql-server-ca \
   --from-file=ca.crt=./server-ca.crt
 </code></pre>
 <p>Create a secret with the TLS certificate:</p>
-<pre><code>kubectl create secret tls my-postgresql-server \
+<pre><code class="language-sh">kubectl create secret tls my-postgresql-server \
   --cert=./server.crt --key=./server.key
 </code></pre>
 <p>Create a PostgreSQL cluster referencing those secrets:</p>