Sync docs from Discourse (canonical#682)

Co-authored-by: GitHub Actions <41898282+github-actions[bot]@users.noreply.github.com>
Zvirovyi · Sep 20, 2024 · 61c68ce · 61c68ce
1 parent a1a946d
commit 61c68ce
Show file tree

Hide file tree

Showing 9 changed files with 236 additions and 49 deletions.
diff --git a/docs/how-to/h-async-integrate.md b/docs/how-to/h-async-integrate.md
@@ -3,9 +3,11 @@
 This guide will show you how to integrate a client application with a cross-regional async setup using an example PostgreSQL K8s deployment with two servers: one in Rome and one in Lisbon.
 
 ## Prerequisites
-* `juju v.3.4.2+`
+* Juju `v.3.4.2+`
+* Make sure your machine(s) fulfill the [system requirements](/t/11744)
+* See [supported target/source model relationships](t/15413#substrate-dependencies).
 * A cross-regional async replication setup
-  * Refer to the page [How to set up clusters](/t/13895)
+  * See [How to set up clusters](/t/13895)
 
 ## Summary
 * [Configure database endpoints](#configure-database-endpoints)

diff --git a/docs/how-to/h-async-remove-recover.md b/docs/how-to/h-async-remove-recover.md
@@ -3,9 +3,11 @@
 This guide will cover how to manage clusters (switchover, detach, reuse, remove, recover) using an example PostgreSQL deployment with two servers: one in Rome and one in Lisbon. 
 
 ## Prerequisites
-* `juju v.3.4.2+`
+* Juju `v.3.4.2+`
+* Make sure your machine(s) fulfill the [system requirements](/t/11744)
+* See [supported target/source model relationships](t/15413#substrate-dependencies).
 * A cross-regional async replication setup
-  * Refer to the page [How to set up clusters](/t/13895)
+  * See [How to set up clusters](/t/13895)
 
 ## Summary
 * [Switchover](#switchover)

diff --git a/docs/how-to/h-async-set-up.md b/docs/how-to/h-async-set-up.md
@@ -4,6 +4,11 @@ Cross-regional (or multi-server) asynchronous replication focuses on disaster re
 
 This guide will show you the basics of initiating a cross-regional async setup using an example PostgreSQL K8s deployment with two servers: one in Rome and one in Lisbon.
 
+## Prerequisites
+* Juju `v.3.4.2+`
+* Make sure your machine(s) fulfill the [system requirements](/t/11744)
+* See [supported target/source model relationships](t/15413#substrate-dependencies).
+
 ## Summary
 * [Deploy](#deploy)
 * [Offer](#offer)

diff --git a/docs/how-to/h-async.md b/docs/how-to/h-async.md
@@ -0,0 +1,30 @@
+# Cross-regional async replication
+
+Cross-regional (or multi-server) asynchronous replication focuses on disaster recovery by distributing data across different servers.
+
+## Prerequisites
+* Juju `v.3.4.2+`
+* Make sure your machine(s) fulfill the [system requirements](/t/11744)
+
+### Substrate dependencies
+
+The following table shows the source and target controller/model combinations that are currently supported:
+
+|  | AWS | GCP | Azure |
+|---|---|:---:|:---:|
+| AWS |  |  |  |
+| GCP |  | ![ check ] | ![ check ] |
+| Azure |  | ![ check ] | ![ check ] |
+
+## How-to guides
+
+* [How to set up clusters for cross-regional async replication](/t/13895)
+* [How to integrate with a client application](/t/13896)
+* [How to remove or recover a cluster](/t/13897)
+  * [Switchover](/t/13897#switchover)
+  * [Detach](/t/13897#detach-a-cluster)
+  * [Recover](/t/13897#recover-a-cluster)
+
+<!-- BADGES -->
+[check]: https://img.shields.io/badge/%E2%9C%93-brightgreen
+[cross]: https://img.shields.io/badge/x-white
diff --git a/docs/how-to/h-rollback-minor.md b/docs/how-to/h-rollback-minor.md
@@ -1,38 +1,31 @@
-# Perform a minor rollback
-**Example**: PostgreSQL 14.9 -> PostgreSQL 14.8<br/>
-(including simple charm revision bump: from revision 43 to revision 42)
-
-[note type="caution"]
-**Warning:** Do NOT trigger `rollback` during the running `upgrade` action! It may cause an unpredictable PostgreSQL cluster state!
-[/note]
-
 [note]
 **Note**: All commands are written for `juju >= v.3.0`
 
-If you are using an earlier version, be aware that:
-
- - `juju run` replaces `juju run-action --wait` in `juju v.2.9` 
- - `juju integrate` replaces `juju relate` and `juju add-relation` in `juju v.2.9`
-
-For more information, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
 [/note]
 
-## Manual rollback
+# How to perform a minor rollback
+**Example**: PostgreSQL 14.9 -> PostgreSQL 14.8<br/>
+(including simple charm revision bump: from revision 43 to revision 42)
 
 After a `juju refresh`, if there are any version incompatibilities in charm revisions, its dependencies, or any other unexpected failure in the upgrade process, the process will be halted and enter a failure state.
 
 Even if the underlying PostgreSQL cluster continues to work, it’s important to roll back the charm to 
 a previous revision so that an update can be attempted after further inspection of the failure.
 
-## Minor rollback steps
+[note type="caution"]
+**Warning:** Do NOT trigger `rollback` during the running `upgrade` action! It may cause an unpredictable PostgreSQL cluster state!
+[/note]
+
+
+## Summary
 1. **Prepare** the Charmed PostgreSQL K8s application for the in-place rollback. 
 2. **Rollback**. Perform the first charm rollback - only the first unit. The unit with the maximal ordinal will be chosen.
 3. **Resume**. Continue rollback to all other units if the first unit rolled back successfully.
 4. **Check**. Make sure the charm and cluster are in healthy state again.
 
-To execute a rollback, we use a similar procedure to the upgrade. The difference is the charm revision to upgrade to. In this guide's example, we will refresh the charm back to revision `88`.
-
 ## Step 1: Prepare
+To execute a rollback, we use a similar procedure to the upgrade. The difference is the charm revision to upgrade to. In this guide's example, we will refresh the charm back to revision `88`.
 
 It is necessary to re-run `pre-upgrade-check` action on the leader unit to enter the upgrade recovery state:
 

diff --git a/docs/how-to/h-upgrade-minor.md b/docs/how-to/h-upgrade-minor.md
@@ -1,17 +1,32 @@
+[note]
+**Note**: All commands are written for `juju >= v.3.0`
+
+If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
 # Perform a minor upgrade
 
 **Example**: PostgreSQL 14.8 -> PostgreSQL 14.9<br/>
 (including simple charm revision bump: from revision 99 to revision 102)
 
 This guide is part of [Charmed PostgreSQL K8s Upgrades](/t/12092). Please refer to this page for more information and an overview of the content.
 
-[note]
-**Note**: All commands are written for `juju >= v.3.0`
+## Summary
 
-If you are using an earlier version, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
-[/note]
+- [**Pre-upgrade checks**](#pre-upgrade-checks): Important information to consider before starting an upgrade.
+- [**1. Collect**](#step-1-collect) all necessary pre-upgrade information. It will be necessary for a rollback, if needed. **Do not skip this step**; better to be safe than sorry!
+- [**2. (Optional) Scale up**](#step-2-scale-up-optional). The new unit will be the first one to be updated, and it will simplify the rollback procedure a lot in case of an upgrade failure.
+- [**3. Prepare**](#step-3-prepare) your Charmed PostgreSQL K8s application for the in-place upgrade. See the step details for all technical details executed by charm here.
+- [**4. Upgrade** - phase 1](#step-4-upgrade). Once started, only one unit in a cluster will be upgraded. In case of failure, the rollback is simple: remove the pod that was recently added in [Step 2: Scale up](#step-2-scale-up-optional).
+- [**5. Resume upgrade** - phase 2](#step-5-resume). If the new pod is OK after the refresh, the upgrade can be resumed for all other units in the cluster. All units in a cluster will be executed sequentially: from biggest ordinal to the lowest one.
+- [**4. (Optional) Consider a rollback**](#step-6-rollback-optional) in case of disaster. 
+  - Please [inform us](/t/11852) about your case scenario troubleshooting to trace the source of the issue and prevent it in the future. 
+- [**7. (optional) Scale back**](#step-7-scale-back-optional). Remove no longer necessary K8s pods created in [Step 2: Scale up](#step-2-scale-up-optional) (if any).
+- [**Post-upgrade check**](#step-5-post-upgrade-check). Make sure all units are in their proper state and the cluster is healthy.
 
-## Before upgrading
+---
+
+## Pre-upgrade checks
 Before performing a minor PostgreSQL upgrade, there are some important considerations to take into account:
 * Concurrency with other operations during the upgrade
 * Backing up your data
@@ -38,18 +53,6 @@ Guides on how to configure backups with S3-compatible storage can be found [here
 
 This will ensure minimal service disruption, if any.
 
-## Minor upgrade steps
-Here is a summary of the steps to perform a minor upgrade.:
-
-1. **Collect** all necessary pre-upgrade information. It will be necessary for a rollback, if needed. Do NOT skip this step, it is better to be safe than sorry!
-2. (optional) **Scale up**. The new unit will be the first one to be updated, and it will simplify the rollback procedure a lot in case of an upgrade failure.
-3. **Prepare** your Charmed PostgreSQL Juju application for the in-place upgrade. See the step description below for all technical details executed by charm here.
-4. **Upgrade** - phase 1. Once started, only one unit in a cluster will be upgraded. In case of failure, the rollback is simple: remove the pod that was recently added in Step 2: **Scale up**.
-5. **Resume** upgrade - phase 2. If the new pod is OK after the refresh, the upgrade can be resumed for all other units in the cluster. All units in a cluster will be executed sequentially: from biggest ordinal to the lowest one.
-6. (optional) Consider [**rolling back**](/t/12096) in case of disaster. Please inform and include us in your case scenario troubleshooting to trace the source of the issue and prevent it in the future. [Contact us](/t/11852)!
-7. (optional) **Scale back**. Remove no longer necessary K8s pod created in step 2 (if any).
-8. Do a post-upgrade **check**. Make sure all units are in the proper state and the cluster is healthy.
-
 ## Step 1: Collect
 [note]
 This step is only valid when deploying from [charmhub](https://charmhub.io/). 
@@ -183,7 +186,7 @@ If the application scale was changed for the upgrade procedure, it is now safe t
 juju scale-application postgresql-k8s <unit_count>
 ```
 
-## Step 8: Check
+## Post-upgrade check
 
 Future [improvements are planned](https://warthogs.atlassian.net/browse/DPE-2620) to check the state of a pod/cluster on a low level. 
 

diff --git a/docs/overview.md b/docs/overview.md
@@ -83,7 +83,7 @@ PostgreSQL is a trademark or registered trademark of PostgreSQL Global Developme
 | 3 | h-integrate-db-with-your-charm | [Integrate a database with your charm](/t/11853) |
 | 3 | h-migrate-pgdump | [Migrate data via pg_dump](/t/12162) |
 | 3 | h-migrate-backup-restore | [Migrate data via backup/restore](/t/12161) |
-| 2 | h-async | [Cross-regional async replication]() |
+| 2 | h-async | [Cross-regional async replication](/t/15413) |
 | 3 | h-async-set-up | [Set up clusters](/t/13895) |
 | 3 | h-async-integrate | [Integrate with a client app](/t/13896) |
 | 3 | h-async-remove-recover | [Remove or recover a cluster](/t/13897) |
@@ -92,6 +92,7 @@ PostgreSQL is a trademark or registered trademark of PostgreSQL Global Developme
 | 2 | r-overview | [Overview](/t/13977) |
 | 2 | r-releases | [Release Notes]() |
 | 3 | r-all-releases | [All releases](/t/11872) |
+| 3 | r-revision-381-382 | [Revision 381/382](/t/15442) |
 | 3 | r-revision-280-281 | [Revision 280/281](/t/14068) |
 | 3 | r-revision-193 | [Revision 193](/t/13208) |
 | 3 | r-revision-177 | [Revision 177](/t/12668) |

diff --git a/docs/reference/r-all-releases.md b/docs/reference/r-all-releases.md
@@ -8,14 +8,16 @@ To see  **all** charm revisions, check the [Charmed PostgreSQL K8s Releases page
 
 The table below is a high-level overview of the architectures and integrations that are supported by each charm revision. 
 
-| Revision | amd64 | arm64 | [TLS  encryption](/t/9685)* | [Monitoring (COS, Grafana)](/t/10600)  | [Tracing (Tempo K8s)](/t/14521)  |
-|:--------:|:-----:|:-----:|:--------------------:|:---------------:|:--------------------:|
-|     [281](/t/14068)  |    :white_check_mark:    | :heavy_multiplication_x: |          :white_check_mark:           |        :white_check_mark:         |         :white_check_mark:           |
-|      [280](/t/14068) |   :heavy_multiplication_x:   |    :white_check_mark:   |          :white_check_mark:            |        :white_check_mark:         |         :white_check_mark:           |
-|      [193](/t/13208) |   :white_check_mark:   |    :heavy_multiplication_x:   |          :white_check_mark:            |        :white_check_mark:        |           :heavy_multiplication_x:         |
-|      [177](/t/12668) |   :white_check_mark:    |    :heavy_multiplication_x:   |            :heavy_multiplication_x:          |        :white_check_mark:         |           :heavy_multiplication_x:         |
-|      [158](/t/11874) |   :white_check_mark:    |    :heavy_multiplication_x:   |            :heavy_multiplication_x:          |       :white_check_mark:          |           :heavy_multiplication_x:        |
-|      [73](/t/11873) |   :white_check_mark:    |    :heavy_multiplication_x:   |           :heavy_multiplication_x:          |       :heavy_multiplication_x:     |       :heavy_multiplication_x:     |
+| Revision | PostgreSQL | amd64 | arm64 | [TLS  encryption](/t/9685)* | [Monitoring (COS, Grafana)](/t/10600)  | [Tracing (Tempo K8s)](/t/14521)  |
+|:--------:|:-----:|:-----:|:-----:|:--------------------:|:---------------:|:--------------------:|
+|      [382](/t/15442) | 14.12 | :heavy_multiplication_x:   |    :white_check_mark:   |          :white_check_mark:            |        :white_check_mark:         |         :white_check_mark:           |
+|     [381](/t/15442)  | 14.12 |    :white_check_mark:    | :heavy_multiplication_x: |          :white_check_mark:           |        :white_check_mark:         |         :white_check_mark:           |
+|     [281](/t/14068)  | 14.11 |    :white_check_mark:    | :heavy_multiplication_x: |          :white_check_mark:           |        :white_check_mark:         |         :white_check_mark:           |
+|      [280](/t/14068) | 14.11 |  :heavy_multiplication_x:   |    :white_check_mark:   |          :white_check_mark:            |        :white_check_mark:         |         :white_check_mark:           |
+|      [193](/t/13208) | 14.10 |   :white_check_mark:   |    :heavy_multiplication_x:   |          :white_check_mark:            |        :white_check_mark:        |           :heavy_multiplication_x:         |
+|      [177](/t/12668) |  14.9 |  :white_check_mark:    |    :heavy_multiplication_x:   |            :heavy_multiplication_x:          |        :white_check_mark:         |           :heavy_multiplication_x:         |
+|      [158](/t/11874) |  14.9 |  :white_check_mark:    |    :heavy_multiplication_x:   |            :heavy_multiplication_x:          |       :white_check_mark:          |           :heavy_multiplication_x:        |
+|      [73](/t/11873) | 14.7 |   :white_check_mark:    |    :heavy_multiplication_x:   |           :heavy_multiplication_x:          |       :heavy_multiplication_x:     |       :heavy_multiplication_x:     |
 
 
 **TLS encryption***: Support for **`v2` or higher** of the [`tls-certificates` interface](https://charmhub.io/tls-certificates-interface/libraries/tls_certificates). This means that you can integrate with [modern TLS charms](https://charmhub.io/topics/security-with-x-509-certificates).