diff --git a/docs/explanation/e-legacy-charm.md b/docs/explanation/e-legacy-charm.md
index f99cc473c4..0f0c76cc0e 100644
--- a/docs/explanation/e-legacy-charm.md
+++ b/docs/explanation/e-legacy-charm.md
@@ -1,4 +1,4 @@
-## Charm types "legacy" vs "modern"
+## Charm types: "legacy" vs "modern"
There are [two types of charms](https://juju.is/docs/sdk/charm-taxonomy#heading--charm-types-by-generation) stored under the same charm name `postgresql`:
1. [Reactive](https://juju.is/docs/sdk/charm-taxonomy#heading--reactive) charm in the channel `latest/stable` (called `legacy`)
diff --git a/docs/explanation/e-statuses.md b/docs/explanation/e-statuses.md
index 42eb58c05f..092d4fe924 100644
--- a/docs/explanation/e-statuses.md
+++ b/docs/explanation/e-statuses.md
@@ -9,6 +9,7 @@ The charm follows [standard Juju applications statuses](https://juju.is/docs/olm
| **active** | any | Normal charm operations | No actions required |
| **waiting** | any | Charm is waiting for relations to be finished | No actions required |
| **maintenance** | any | Charm is performing the internal maintenance (e.g. cluster re-configuration, upgrade, ...) | No actions required |
+| **blocked** | the S3 repository has backups from another cluster | The bucket contains foreign backup. To avoid accident DB corruption, use clean bucket. The cluster identified by Juju app name + DB UUID. | Chose/change the new S3 [bucket](https://charmhub.io/s3-integrator/configuration#bucket)/[path](https://charmhub.io/s3-integrator/configuration#path) OR clean the current one. |
| **blocked** | failed to update cluster members on member | TODO: error/retry? | |
| **blocked** | failed to install snap packages | There are issues with the network connection and/or the Snap Store | Check your internet connection and https://status.snapcraft.io/. Remove the application and when everything is ok, deploy the charm again |
| **blocked** | failed to patch snap seccomp profile | The charm failed to patch one issue that happens when pgBackRest restores a backup (this blocked status should be removed when https://github.com/pgbackrest/pgbackrest/releases/tag/release%2F2.46 is added to the snap) | Remove the unit and add it back again |
diff --git a/docs/how-to/h-async/h-async-integrate.md b/docs/how-to/h-async-integrate.md
similarity index 72%
rename from docs/how-to/h-async/h-async-integrate.md
rename to docs/how-to/h-async-integrate.md
index 5707c5533b..327e8872b8 100644
--- a/docs/how-to/h-async/h-async-integrate.md
+++ b/docs/how-to/h-async-integrate.md
@@ -1,9 +1,4 @@
# Integrate with a client application
-[note type="caution"]
-This is an internal article. **Do not use it in production!**
-
-Contact the [Canonical Data Platform team](https://chat.charmhub.io/charmhub/channels/data-platform) if you are interested in this topic.
-[/note]
This guide will show you how to integrate a client application with a cross-regional async setup using an example PostgreSQL deployment with two servers: one in Rome and one in Lisbon.
@@ -13,13 +8,13 @@ This guide will show you how to integrate a client application with a cross-regi
* Refer to the page [How to set up clusters](/t/13991)
## Summary
-* [Configure database endpoints](#heading--configure-endpoints)
-* [Internal client](#heading--internal-client)
-* [External client](#heading--external-client)
+* [Configure database endpoints](#configure-database-endpoints)
+* [Internal client](#internal-client)
+* [External client](#external-client)
---
-
+## Configure database endpoints
To make your database available to a client application, you must first offer and consume database endpoints.
@@ -46,7 +41,7 @@ juju consume rome.db1database
juju consume lisbon.db2database
```
- Internal client
+## Internal client
If the client application is another charm, deploy them and connect them with `juju integrate`.
@@ -62,7 +57,7 @@ juju integrate postgresql-test-app:first-database pgbouncer
juju integrate pgbouncer db1database
```
- External client
+## External client
If the client application is external, they must be integrated via the [`data-integrator` charm](https://charmhub.io/data-integrator).
diff --git a/docs/how-to/h-async/h-async-remove-recover.md b/docs/how-to/h-async-remove-recover.md
similarity index 70%
rename from docs/how-to/h-async/h-async-remove-recover.md
rename to docs/how-to/h-async-remove-recover.md
index d5dc15bcb0..2766485d89 100644
--- a/docs/how-to/h-async/h-async-remove-recover.md
+++ b/docs/how-to/h-async-remove-recover.md
@@ -1,9 +1,4 @@
# Remove or recover a cluster
-[note type="caution"]
-This is an internal article. **Do not use it in production!**
-
-Contact the [Canonical Data Platform team](https://chat.charmhub.io/charmhub/channels/data-platform) if you are interested in this topic.
-[/note]
This guide will cover how to manage clusters using an example PostgreSQL deployment with two servers: one in Rome and one in Lisbon.
@@ -13,16 +8,16 @@ This guide will cover how to manage clusters using an example PostgreSQL deploym
* Refer to the page [How to set up clusters](/t/13991)
## Summary
-* [Switchover](#heading--switchover)
-* [Detach a cluster](#heading--detach)
- * [Reuse a detached cluster](#heading--reuse)
- * [Remove a detached cluster](#heading--remove)
-* [Recover a cluster](#heading--recover)
+* [Switchover](#switchover)
+* [Detach a cluster](#detach-a-cluster)
+ * [Reuse a detached cluster](#reuse-a-detached-cluster)
+ * [Remove a detached cluster](#remove-a-detached-cluster)
+* [Recover a cluster](#recover-a-cluster)
---
- Switchover
+## Switchover
If the primary cluster fails or is removed, it is necessary to appoint a new cluster as primary.
@@ -32,7 +27,7 @@ To switchover and promote `lisbon` to primary, one would run the command:
juju run -m lisbon db2/leader promote-to-primary
```
- Detach a cluster
+## Detach a cluster
Clusters in an async replica set can be detached. The detached cluster can then be either removed or reused.
@@ -44,14 +39,14 @@ juju remove-relation -m lisbon replication-offer db2:replication
The command above will move the `rome` cluster into a detached state (`blocked`) keeping all the data in place.
- Reuse a detached cluster
+### Reuse a detached cluster
The following command creates a new cluster in the replica set from the detached `rome` cluster, keeping its existing data in use:
```shell
juju run -m rome db1/leader promote-to-primary
```
- Remove a detached cluster
+### Remove a detached cluster
The following command removes the detached `rome` cluster and **destroys its stored data** with the optional `--destroy-storage` flag:
@@ -59,7 +54,7 @@ The following command removes the detached `rome` cluster and **destroys its sto
juju remove-application -m rome db1 --destroy-storage
```
- Recover a cluster
+## Recover a cluster
**If the integration between clusters was removed** and one side went into a `blocked` state, integrate both clusters again and call the `promote-cluster` action to restore async replication - similar to the "Reuse a detached cluster" step above.
diff --git a/docs/how-to/h-async-set-up.md b/docs/how-to/h-async-set-up.md
new file mode 100644
index 0000000000..f5c50262fa
--- /dev/null
+++ b/docs/how-to/h-async-set-up.md
@@ -0,0 +1,75 @@
+# Set up clusters for cross-regional async replication
+
+Cross-regional (or multi-server) asynchronous replication focuses on disaster recovery by distributing data across different servers.
+
+This guide will show you the basics of initiating a cross-regional async setup using an example PostgreSQL deployment with two servers: one in Rome and one in Lisbon.
+
+## Summary
+* [Deploy](#deploy)
+* [Offer](#offer)
+* [Consume](#consume)
+* [Promote or switchover a cluster](#promote-or-switchover-a-cluster)
+* [Scale a cluster](#scale-a-cluster)
+
+---
+
+## Deploy
+
+To deploy two clusters in different servers, create two juju models - one for the `rome` cluster, one for the `lisbon` cluster. In the example below, we use the config flag `profile=testing` to limit memory usage.
+
+```shell
+juju add-model rome
+juju add-model lisbon
+
+juju switch rome # active model must correspond to cluster
+juju deploy postgresql db1 --channel=14/edge/async-replication --config profile=testing --base ubuntu@22.04
+
+juju switch lisbon
+juju deploy postgresql db2 --channel=14/edge/async-replication --config profile=testing --base ubuntu@22.04
+```
+
+## Offer
+
+[Offer](https://juju.is/docs/juju/offer) asynchronous replication in one of the clusters.
+
+```shell
+juju switch rome
+juju offer db1:async-primary async-primary
+```
+
+## Consume
+
+Consume asynchronous replication on planned `Standby` cluster (Lisbon):
+```shell
+juju switch lisbon
+juju consume rome.async-primary
+juju integrate async-primary db2:async-replica
+```
+
+## Promote or switchover a cluster
+
+To define the primary cluster, use the `promote-cluster` action.
+
+```shell
+juju run -m rome db1/leader promote-cluster
+```
+
+To switchover and use `lisbon` as the primary instead, run
+
+```shell
+juju run -m lisbon db2/leader promote-cluster force-promotion=true
+```
+
+## Scale a cluster
+
+The two clusters work independently, which means that it’s possible to scale each cluster separately. The `-m` flag defines the target of this action, so it can be performed within any active model.
+
+For example:
+
+```shell
+juju add-unit db1 -n 2 -m rome
+juju add-unit db2 -n 2 -m lisbon
+```
+[note]
+**Note:** Scaling is possible before and after the asynchronous replication is established/created.
+[/note]
\ No newline at end of file
diff --git a/docs/how-to/h-async/h-async-set-up.md b/docs/how-to/h-async/h-async-set-up.md
deleted file mode 100644
index 0b7c2db2a3..0000000000
--- a/docs/how-to/h-async/h-async-set-up.md
+++ /dev/null
@@ -1,82 +0,0 @@
-# Set up clusters for cross-regional async replication
-
-[note type="caution"]
-This is an internal article. **Do not use it in production!**
-
-Contact the [Canonical Data Platform team](https://chat.charmhub.io/charmhub/channels/data-platform) if you are interested in this topic.
-[/note]
-
-Cross-regional (or multi-server) asynchronous replication focuses on disaster recovery by distributing data across different servers.
-
-This guide will show you the basics of initiating a cross-regional async setup using an example PostgreSQL deployment with two servers: one in Rome and one in Lisbon.
-
-## Summary
-* [Deploy](#heading--deploy)
-* [Offer](#heading--offer)
-* [Consume](#heading--consume)
-* [Promote or switchover](#heading--promote-switchover)
-* [Scale](#heading--scale)
-
-
----
-
- Deploy
-
-To deploy two clusters in different servers, create two juju models - one for the `rome` cluster, one for the `lisbon` cluster. In the example below, we use the config flag `profile=testing` to limit memory usage.
-
-```shell
-juju add-model rome
-juju add-model lisbon
-
-juju switch rome # active model must correspond to cluster
-juju deploy postgresql db1 --channel=14/edge --config profile=testing --base ubuntu@22.04
-
-juju switch lisbon
-juju deploy postgresql db2 --channel=14/edge --config profile=testing --base ubuntu@22.04
-```
-
- Offer
-
-[Offer](https://juju.is/docs/juju/offer) asynchronous replication in one of the clusters.
-
-```shell
-juju switch rome
-juju offer db1:replication-offer replication-offer
-```
-
- Consume
-
-Consume asynchronous replication on planned `Standby` cluster (Lisbon):
-```shell
-juju switch lisbon
-juju consume rome.replication-offer
-juju integrate replication-offer db2:replication
-```
-
-
-
-To define the primary cluster, use the `create-replication` action.
-
-```shell
-juju run -m rome db1/leader create-replication
-```
-
-To switchover and use `lisbon` as the primary instead, run
-
-```shell
-juju run -m lisbon db2/leader promote-to-primary
-```
-
- Scale a cluster
-
-The two clusters work independently, which means that it’s possible to scale each cluster separately. The `-m` flag defines the target of this action, so it can be performed with any active model.
-
-For example:
-
-```shell
-juju add-unit db1 -n 2 -m rome
-juju add-unit db2 -n 2 -m lisbon
-```
-[note]
-Scaling is possible before and after the asynchronous replication is established/created.
-[/note]
\ No newline at end of file
diff --git a/docs/how-to/h-backups/h-configure-s3-aws.md b/docs/how-to/h-configure-s3-aws.md
similarity index 100%
rename from docs/how-to/h-backups/h-configure-s3-aws.md
rename to docs/how-to/h-configure-s3-aws.md
diff --git a/docs/how-to/h-backups/h-configure-s3-radosgw.md b/docs/how-to/h-configure-s3-radosgw.md
similarity index 100%
rename from docs/how-to/h-backups/h-configure-s3-radosgw.md
rename to docs/how-to/h-configure-s3-radosgw.md
diff --git a/docs/how-to/h-backups/h-create-backup.md b/docs/how-to/h-create-backup.md
similarity index 100%
rename from docs/how-to/h-backups/h-create-backup.md
rename to docs/how-to/h-create-backup.md
diff --git a/docs/how-to/h-set-up/h-deploy-lxd.md b/docs/how-to/h-deploy-lxd.md
similarity index 100%
rename from docs/how-to/h-set-up/h-deploy-lxd.md
rename to docs/how-to/h-deploy-lxd.md
diff --git a/docs/how-to/h-set-up/h-deploy-maas.md b/docs/how-to/h-deploy-maas.md
similarity index 100%
rename from docs/how-to/h-set-up/h-deploy-maas.md
rename to docs/how-to/h-deploy-maas.md
diff --git a/docs/how-to/h-set-up/h-deploy-terraform.md b/docs/how-to/h-deploy-terraform.md
similarity index 65%
rename from docs/how-to/h-set-up/h-deploy-terraform.md
rename to docs/how-to/h-deploy-terraform.md
index ef8bb662ad..e16facef69 100644
--- a/docs/how-to/h-set-up/h-deploy-terraform.md
+++ b/docs/how-to/h-deploy-terraform.md
@@ -2,30 +2,34 @@
[Terraform](https://www.terraform.io/) is an infrastructure automation tool to provision and manage resources in clouds or data centers. To deploy Charmed PostgreSQL using Terraform and Juju, you can use the [Juju Terraform Provider](https://registry.terraform.io/providers/juju/juju/latest).
-The easiest way is to start from [these examples of terraform modules](https://github.com/canonical/terraform-modules) prepared by Canonical. This page will guide you through a deployment using an example module for PostgreSQL.
+The easiest way is to start from [these examples of terraform modules](https://github.com/canonical/terraform-modules) prepared by Canonical. This page will guide you through a deployment using an example module for PostgreSQL on machines.
For an in-depth introduction to the Juju Terraform Provider, read [this Discourse post](https://discourse.charmhub.io/t/6939).
+[note]
+**Note**: Storage support was added in [Juju Terraform Provider version 0.13+](https://github.com/juju/terraform-provider-juju/releases/tag/v0.13.0).
+[/note]
+
## Summary
-* [Install Terraform and Juju tooling](#install-terraform-and-juju-tooling)
+* [Install Terraform tooling](#install-terraform-tooling)
+* [Verify the deployment](#verify-the-deployment)
* [Apply the deployment](#apply-the-deployment)
* [Check deployment status](#check-deployment-status)
-* [Terraform module contents](#terraform-module-contents)
* [Clean up](#clean-up)
---
-## Install Terraform and Juju tooling
+## Install Terraform tooling
-This guide assumes Juju is installed. For more information, check the [Set up the environment](/t/9709) tutorial page.
+This guide assumes Juju is installed and you have an LXD controller already bootstrapped. For more information, check the [Set up the environment](/t/9709) tutorial page.
-Let's install Terraform Provider and example modules:
+First, install Terraform Provider and example modules:
```shell
sudo snap install terraform --classic
```
-Switch to the LXD provider and create new model:
+Switch to the LXD provider and create a new model:
```shell
juju switch lxd
-juju add-model mymodel
+juju add-model my-model
```
Clone examples and navigate to the PostgreSQL machine module:
```shell
@@ -38,15 +42,41 @@ Initialise the Juju Terraform Provider:
terraform init
```
-## Apply the deployment
+## Verify the deployment
+
+Open the `main.tf` file to see the brief contents of the Terraform module:
+
+```tf
+resource "juju_application" "machine_postgresql" {
+ name = "postgresql"
+ model = "my-model"
+
+ charm {
+ name = "postgresql"
+ channel = "14/stable"
+ }
+
+ config = {
+ plugin_hstore_enable = true
+ plugin_pg_trgm_enable = true
+ }
+
+ units = 1
+}
+```
+
+Run `terraform plan` to get a preview of the changes that will be made:
-Let's verify and apply the deployment. First, run `terraform plan` and check the output
```shell
-terraform plan -var "juju_model_name=mymodel"
+terraform plan -var "juju_model_name=my-model"
```
-Then, deploy the resources (skip the approval):
+
+## Apply the deployment
+
+If everything looks correct, deploy the resources (skip the approval):
+
```shell
-terraform apply -auto-approve -var "juju_model_name=mymodel"
+terraform apply -auto-approve -var "juju_model_name=my-model"
```
## Check deployment status
@@ -54,14 +84,14 @@ terraform apply -auto-approve -var "juju_model_name=mymodel"
Check the deployment status with
```shell
-juju status --model lxd:mymodel
+juju status --model lxd:my-model --watch 1s
```
Sample output:
```shell
-Model Controller Cloud/Region Version SLA Timestamp
-mymodel lxd localhost/localhost 3.5.2 unsupported 14:04:26+02:00
+Model Controller Cloud/Region Version SLA Timestamp
+my-model lxd localhost/localhost 3.5.2 unsupported 14:04:26+02:00
App Version Status Scale Charm Channel Rev Exposed Message
postgresql 14.11 active 1 postgresql 14/stable 429 no
@@ -75,45 +105,16 @@ Machine State Address Inst id Base AZ Message
Continue to operate the charm as usual from here or apply further Terraform changes.
-[note type="caution"]
-**Important**: Juju Storage support was added in [Juju Terraform Provider version 0.13+](https://github.com/juju/terraform-provider-juju/releases/tag/v0.13.0).
-[/note]
-
-## Terraform module contents
-
-See the contents of the `main.tf` file to note the simplicity of Terraform modules that use the [Terraform Juju Provider](https://registry.terraform.io/providers/juju/juju/latest/docs):
-
-```tf
-resource "juju_application" "machine_postgresql" {
- name = "postgresql"
- model = "mymodel"
-
- charm {
- name = "postgresql"
- channel = "14/stable"
- }
-
- config = {
- plugin_hstore_enable = true
- plugin_pg_trgm_enable = true
- }
-
- units = 1
-}
-```
-
-For more VM examples, including PostgreSQL HA and PostgreSQL + PgBouncer, see the other directories in the [`terraform-modules` repository](https://github.com/canonical/terraform-modules/tree/main/modules/machine).
-
## Clean up
To keep the house clean, remove the newly deployed Charmed PostgreSQL by running
```shell
-terraform destroy -var "juju_model_name=mymodel"
+terraform destroy -var "juju_model_name=my-model"
```
Sample output:
```shell
-juju_application.machine_postgresql: Refreshing state... [id=mymodel:postgresql]
+juju_application.machine_postgresql: Refreshing state... [id=my-model:postgresql]
Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
- destroy
@@ -127,8 +128,8 @@ Terraform will perform the following actions:
- "plugin_pg_trgm_enable" = "true"
} -> null
- constraints = "arch=amd64" -> null
- - id = "mymodel:postgresql" -> null
- - model = "mymodel" -> null
+ - id = "my-model:postgresql" -> null
+ - model = "my-model" -> null
- name = "postgresql" -> null
- placement = "0" -> null
- storage = [
@@ -162,10 +163,14 @@ Do you really want to destroy all resources?
Enter a value: yes
-juju_application.machine_postgresql: Destroying... [id=mymodel:postgresql]
+juju_application.machine_postgresql: Destroying... [id=my-model:postgresql]
juju_application.machine_postgresql: Destruction complete after 1s
Destroy complete! Resources: 1 destroyed.
```
+---
+[note]
+For more examples of Terraform modules for VM, including PostgreSQL HA and PostgreSQL + PgBouncer, see the other directories in the [`terraform-modules` repository](https://github.com/canonical/terraform-modules/tree/main/modules/machine).
+[/note]
-Feel free to [contact us](https:///t/11863) if you have any question and [collaborate with us on GitHub](https://github.com/canonical/terraform-modules)!
\ No newline at end of file
+Feel free to [contact us](/t/11863) if you have any question and [collaborate with us on GitHub](https://github.com/canonical/terraform-modules)!
\ No newline at end of file
diff --git a/docs/how-to/h-monitor/h-enable-alert-rules.md b/docs/how-to/h-enable-alert-rules.md
similarity index 100%
rename from docs/how-to/h-monitor/h-enable-alert-rules.md
rename to docs/how-to/h-enable-alert-rules.md
diff --git a/docs/how-to/h-monitor/h-enable-monitoring.md b/docs/how-to/h-enable-monitoring.md
similarity index 95%
rename from docs/how-to/h-monitor/h-enable-monitoring.md
rename to docs/how-to/h-enable-monitoring.md
index 83e63b8334..26eae39bc7 100644
--- a/docs/how-to/h-monitor/h-enable-monitoring.md
+++ b/docs/how-to/h-enable-monitoring.md
@@ -7,9 +7,8 @@ If you are using an earlier version, check the [Juju 3.0 Release Notes](https://
# How to enable monitoring (COS)
## Prerequisites
-Enable monitoring requires that you:
-* A deployed [Charmed PostgreSQL VM operator](/t/charmed-postgresql-tutorial-deploy-postgresql/9697?channel=14/edge)
-* A deployed [`cos-lite` bundle in a Kubernetes environment](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)
+* Charmed PostgreSQL [Revision 336 or greater](/t/11875)
+* [`cos-lite` bundle](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s) deployed in a Kubernetes environment
---
diff --git a/docs/how-to/h-set-up/h-enable-tls.md b/docs/how-to/h-enable-tls.md
similarity index 100%
rename from docs/how-to/h-set-up/h-enable-tls.md
rename to docs/how-to/h-enable-tls.md
diff --git a/docs/how-to/h-monitor/h-enable-tracing.md b/docs/how-to/h-enable-tracing.md
similarity index 100%
rename from docs/how-to/h-monitor/h-enable-tracing.md
rename to docs/how-to/h-enable-tracing.md
diff --git a/docs/how-to/h-connect-your-charm/h-integrate-with-your-charm.md b/docs/how-to/h-integrate-db-with-your-charm.md
similarity index 100%
rename from docs/how-to/h-connect-your-charm/h-integrate-with-your-charm.md
rename to docs/how-to/h-integrate-db-with-your-charm.md
diff --git a/docs/how-to/h-connect-your-charm/h-connect-migrate-backup-restore.md b/docs/how-to/h-integrate-migrate-backup-restore.md
similarity index 100%
rename from docs/how-to/h-connect-your-charm/h-connect-migrate-backup-restore.md
rename to docs/how-to/h-integrate-migrate-backup-restore.md
diff --git a/docs/how-to/h-connect-your-charm/h-connect-migrate-pgdump.md b/docs/how-to/h-integrate-migrate-pgdump.md
similarity index 100%
rename from docs/how-to/h-connect-your-charm/h-connect-migrate-pgdump.md
rename to docs/how-to/h-integrate-migrate-pgdump.md
diff --git a/docs/how-to/h-backups/h-manage-backup-retention.md b/docs/how-to/h-manage-backup-retention.md
similarity index 100%
rename from docs/how-to/h-backups/h-manage-backup-retention.md
rename to docs/how-to/h-manage-backup-retention.md
diff --git a/docs/how-to/h-set-up/h-manage-client.md b/docs/how-to/h-manage-client.md
similarity index 100%
rename from docs/how-to/h-set-up/h-manage-client.md
rename to docs/how-to/h-manage-client.md
diff --git a/docs/how-to/h-backups/h-migrate-cluster.md b/docs/how-to/h-migrate-cluster.md
similarity index 100%
rename from docs/how-to/h-backups/h-migrate-cluster.md
rename to docs/how-to/h-migrate-cluster.md
diff --git a/docs/how-to/h-backups/h-restore-backup.md b/docs/how-to/h-restore-backup.md
similarity index 100%
rename from docs/how-to/h-backups/h-restore-backup.md
rename to docs/how-to/h-restore-backup.md
diff --git a/docs/how-to/h-upgrade/h-rollback-major.md b/docs/how-to/h-rollback-major.md
similarity index 100%
rename from docs/how-to/h-upgrade/h-rollback-major.md
rename to docs/how-to/h-rollback-major.md
diff --git a/docs/how-to/h-upgrade/h-rollback-minor.md b/docs/how-to/h-rollback-minor.md
similarity index 100%
rename from docs/how-to/h-upgrade/h-rollback-minor.md
rename to docs/how-to/h-rollback-minor.md
diff --git a/docs/how-to/h-set-up/h-scale.md b/docs/how-to/h-scale.md
similarity index 100%
rename from docs/how-to/h-set-up/h-scale.md
rename to docs/how-to/h-scale.md
diff --git a/docs/reference/h-troubleshooting.md b/docs/how-to/h-troubleshooting.md
similarity index 100%
rename from docs/reference/h-troubleshooting.md
rename to docs/how-to/h-troubleshooting.md
diff --git a/docs/how-to/h-upgrade/h-upgrade-intro.md b/docs/how-to/h-upgrade-intro.md
similarity index 100%
rename from docs/how-to/h-upgrade/h-upgrade-intro.md
rename to docs/how-to/h-upgrade-intro.md
diff --git a/docs/how-to/h-upgrade/h-upgrade-major.md b/docs/how-to/h-upgrade-major.md
similarity index 100%
rename from docs/how-to/h-upgrade/h-upgrade-major.md
rename to docs/how-to/h-upgrade-major.md
diff --git a/docs/how-to/h-upgrade/h-upgrade-minor.md b/docs/how-to/h-upgrade-minor.md
similarity index 100%
rename from docs/how-to/h-upgrade/h-upgrade-minor.md
rename to docs/how-to/h-upgrade-minor.md
diff --git a/docs/index.md b/docs/index.md
deleted file mode 100644
index 97107aef97..0000000000
--- a/docs/index.md
+++ /dev/null
@@ -1,109 +0,0 @@
-# Charmed PostgreSQL Documentation
-
-Charmed PostgreSQL is an open-source software operator designed to deploy and operate object-relational databases on IAAS/VM. It packages the powerful database management system [PostgreSQL](https://www.postgresql.org/) into a charmed operator for deployment with [Juju](https://juju.is/docs/juju).
-
-This charm offers automated operations management from day 0 to day 2. It is equipped with several features to securely store and scale complicated data workloads, including TLS encryption, backups, monitoring, password rotation, and easy integration with client applications.
-
-Charmed PostgreSQL meets the need of deploying PostgreSQL in a structured and consistent manner while providing flexibility in configuration. It simplifies deployment, scaling, configuration and management of relational databases in large-scale production environments reliably.
-
-This charmed operator is made for anyone looking for a comprehensive database management interface, whether for operating a complex production environment or simply as a playground to learn more about databases and charms.
-
-[note type="positive"]
-This operator is built for **IAAS/VM**.
-
-For deployments in **Kubernetes** environments, see [Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s).
-[/note]
-
-
-
-## In this documentation
-
-| | |
-|--|--|
-| [**Tutorials**](/t/9707) [Get started](/t/9707) - a hands-on introduction to using Charmed PostgreSQL operator for new users | [**How-to guides**](/t/9689) Step-by-step guides covering key operations such as [scaling](/t/9689), [encryption](/t/9685), and [restoring backups](/t/9693) |
-| [**Reference**](/t/13976) Technical information such as [requirements](/t/11743), [release notes](/t/11875), and [plugins](/t/10946) | [**Explanation**](/t/10251) Concepts - discussion and clarification of key topics such as [architecture](/t/11857), [users](/t/10798), and [legacy charms](/t/10690)|
-## Project and community
-
-Charmed PostgreSQL is an official distribution of PostgreSQL. It’s an open-source project that welcomes community contributions, suggestions, fixes and constructive feedback.
-- [Read our Code of Conduct](https://ubuntu.com/community/code-of-conduct)
-- [Join the Discourse forum](https://discourse.charmhub.io/tag/postgresql)
-- [Contribute](https://github.com/canonical/postgresql-operator/blob/main/CONTRIBUTING.md) to the code or report an [issue](https://github.com/canonical/postgresql-operator/issues/new/choose)
-- Explore [Canonical Data Fabric solutions](https://canonical.com/data)
-- [Contacts us](/t/11863) for all further questions
-
-## Licencing & Trademark
-The Charmed PostgreSQL Operator is distributed under the [Apache Software Licence version 2.0](https://github.com/canonical/postgresql-operator/blob/main/LICENSE). It depends on [PostgreSQL](https://www.postgresql.org/ftp/source/), which is licensed under the [PostgreSQL License](https://www.postgresql.org/about/licence/) - a liberal open-source licence similar to the BSD or MIT licences.
-
-PostgreSQL is a trademark or registered trademark of PostgreSQL Global Development Group. Other trademarks are the property of their respective owners.
-
-# Contents
-
-1. [Tutorial](tutorial)
- 1. [Overview](tutorial/t-overview.md)
- 1. [1. Set up the environment](tutorial/t-set-up.md)
- 1. [2. Deploy PostgreSQL](tutorial/t-deploy.md)
- 1. [3. Scale replicas](tutorial/t-scale.md)
- 1. [4. Manage passwords](tutorial/t-passwords.md)
- 1. [5. Integrate with other applications](tutorial/t-integrate.md)
- 1. [6. Enable TLS](tutorial/t-enable-tls.md)
- 1. [7. Clean up environment](tutorial/t-clean-up.md)
-1. [How-to guides](how-to)
- 1. [Set up](how-to/h-set-up)
- 1. [Deploy on LXD](how-to/h-set-up/h-deploy-lxd.md)
- 1. [Deploy on MAAS](how-to/h-set-up/h-deploy-maas.md)
- 1. [Deploy via Terraform](how-to/h-set-up/h-deploy-terraform.md)
- 1. [Scale units](how-to/h-set-up/h-scale.md)
- 1. [Enable TLS](how-to/h-set-up/h-enable-tls.md)
- 1. [Manage client applications](how-to/h-set-up/h-manage-client.md)
- 1. [Back up and restore](how-to/h-backups)
- 1. [Configure S3 AWS](how-to/h-backups/h-configure-s3-aws.md)
- 1. [Configure S3 RadosGW](how-to/h-backups/h-configure-s3-radosgw.md)
- 1. [Create a backup](how-to/h-backups/h-create-backup.md)
- 1. [Restore a backup](how-to/h-backups/h-restore-backup.md)
- 1. [Manage backup retention](how-to/h-backups/h-manage-backup-retention.md)
- 1. [Migrate a cluster](how-to/h-backups/h-migrate-cluster.md)
- 1. [Monitor (COS)](how-to/h-monitor)
- 1. [Enable Monitoring](how-to/h-monitor/h-enable-monitoring.md)
- 1. [Enable Alert Rules](how-to/h-monitor/h-enable-alert-rules.md)
- 1. [Enable Tracing](how-to/h-monitor/h-enable-tracing.md)
- 1. [Upgrade](how-to/h-upgrade)
- 1. [Overview](how-to/h-upgrade/h-upgrade-intro.md)
- 1. [Perform a major upgrade](how-to/h-upgrade/h-upgrade-major.md)
- 1. [Perform a major rollback](how-to/h-upgrade/h-rollback-major.md)
- 1. [Perform a minor upgrade](how-to/h-upgrade/h-upgrade-minor.md)
- 1. [Perform a minor rollback](how-to/h-upgrade/h-rollback-minor.md)
- 1. [Connect your charm](how-to/h-connect-your-charm)
- 1. [Integrate a database with your charm](how-to/h-connect-your-charm/h-integrate-with-your-charm.md)
- 1. [Migrate data via pg_dump](how-to/h-connect-your-charm/h-connect-migrate-pgdump.md)
- 1. [Migrate data via backup/restore](how-to/h-connect-your-charm/h-connect-migrate-backup-restore.md)
- 1. [Cross-regional async replication](how-to/h-async)
- 1. [Set up clusters](how-to/h-async/h-async-set-up.md)
- 1. [Integrate with a client app](how-to/h-async/h-async-integrate.md)
- 1. [Remove or recover a cluster](how-to/h-async/h-async-remove-recover.md)
- 1. [Enable plugins/extensions](how-to/h-enable-plugins-extensions.md)
-1. [Reference](reference)
- 1. [Overview](reference/r-overview.md)
- 1. [Release Notes](reference/r-releases-group)
- 1. [All releases](reference/r-releases-group/r-releases.md)
- 1. [Revision 429/430](reference/r-releases-group/r-revision-429.md)
- 1. [Revision 363](reference/r-releases-group/r-revision-363.md)
- 1. [Revision 351](reference/r-releases-group/r-revision-351.md)
- 1. [Revision 336](reference/r-releases-group/r-revision-336.md)
- 1. [Revision 288](reference/r-releases-group/r-revision-288.md)
- 1. [System requirements](reference/r-system-requirements.md)
- 1. [Software testing](reference/r-software-testing.md)
- 1. [Performance and resource allocation](reference/r-performance.md)
- 1. [Troubleshooting](reference/h-troubleshooting.md)
- 1. [Plugins/extensions](reference/r-plugins-extensions.md)
- 1. [Contacts](reference/r-contacts.md)
-1. [Explanation](explanation)
- 1. [Architecture](explanation/e-architecture.md)
- 1. [Interfaces and endpoints](explanation/e-interfaces-endpoints.md)
- 1. [Statuses](explanation/e-statuses.md)
- 1. [Users](explanation/e-users.md)
- 1. [Logs](explanation/e-logs.md)
- 1. [Juju](explanation/e-juju-details.md)
- 1. [Legacy charm](explanation/e-legacy-charm.md)
-1. [Search](https://canonical.com/data/docs/postgresql/iaas)
\ No newline at end of file
diff --git a/docs/overview.md b/docs/overview.md
new file mode 100644
index 0000000000..e715f14e02
--- /dev/null
+++ b/docs/overview.md
@@ -0,0 +1,121 @@
+# Charmed PostgreSQL Documentation
+
+Charmed PostgreSQL is an open-source software operator designed to deploy and operate object-relational databases on IAAS/VM. It packages the powerful database management system [PostgreSQL](https://www.postgresql.org/) into a charmed operator for deployment with [Juju](https://juju.is/docs/juju).
+
+This charm offers automated operations management from day 0 to day 2. It is equipped with several features to securely store and scale complicated data workloads, including TLS encryption, backups, monitoring, password rotation, and easy integration with client applications.
+
+Charmed PostgreSQL meets the need of deploying PostgreSQL in a structured and consistent manner while providing flexibility in configuration. It simplifies deployment, scaling, configuration and management of relational databases in large-scale production environments reliably.
+
+This charmed operator is made for anyone looking for a comprehensive database management interface, whether for operating a complex production environment or simply as a playground to learn more about databases and charms.
+
+[note type="positive"]
+This operator is built for **IAAS/VM**.
+
+For deployments in **Kubernetes** environments, see [Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s).
+[/note]
+
+
+
+## In this documentation
+
+| | |
+|--|--|
+| [**Tutorials**](/t/9707) [Get started](/t/9707) - a hands-on introduction to using Charmed PostgreSQL operator for new users | [**How-to guides**](/t/9689) Step-by-step guides covering key operations such as [scaling](/t/9689), [encryption](/t/9685), and [restoring backups](/t/9693) |
+| [**Reference**](/t/13976) Technical information such as [requirements](/t/11743), [release notes](/t/11875), and [plugins](/t/10946) | [**Explanation**](/t/10251) Concepts - discussion and clarification of key topics such as [architecture](/t/11857), [users](/t/10798), and [legacy charms](/t/10690)|
+## Project and community
+
+Charmed PostgreSQL is an official distribution of PostgreSQL. It’s an open-source project that welcomes community contributions, suggestions, fixes and constructive feedback.
+- [Read our Code of Conduct](https://ubuntu.com/community/code-of-conduct)
+- [Join the Discourse forum](https://discourse.charmhub.io/tag/postgresql)
+- [Contribute](https://github.com/canonical/postgresql-operator/blob/main/CONTRIBUTING.md) to the code or report an [issue](https://github.com/canonical/postgresql-operator/issues/new/choose)
+- Explore [Canonical Data Fabric solutions](https://canonical.com/data)
+- [Contacts us](/t/11863) for all further questions
+
+## Licencing & Trademark
+The Charmed PostgreSQL Operator is distributed under the [Apache Software Licence version 2.0](https://github.com/canonical/postgresql-operator/blob/main/LICENSE). It depends on [PostgreSQL](https://www.postgresql.org/ftp/source/), which is licensed under the [PostgreSQL License](https://www.postgresql.org/about/licence/) - a liberal open-source licence similar to the BSD or MIT licences.
+
+PostgreSQL is a trademark or registered trademark of PostgreSQL Global Development Group. Other trademarks are the property of their respective owners.
+
+
+# Navigation
+
+[details=Navigation]
+
+| Level | Path | Navlink |
+|--------|--------|-------------|
+| 1 | tutorial | [Tutorial]() |
+| 2 | t-overview | [Overview](/t/9707) |
+| 2 | t-set-up | [1. Set up the environment](/t/9709) |
+| 2 | t-deploy | [2. Deploy PostgreSQL](/t/9697) |
+| 2 | t-scale | [3. Scale replicas](/t/9705) |
+| 2 | t-passwords | [4. Manage passwords](/t/9703) |
+| 2 | t-integrate | [5. Integrate with other applications](/t/9701) |
+| 2 | t-enable-tls | [6. Enable TLS](/t/9699) |
+| 2 | t-clean-up | [7. Clean up environment](/t/9695) |
+| 1 | how-to | [How-to guides]() |
+| 2 | h-set-up | [Set up]() |
+| 3 | h-deploy-lxd | [Deploy on LXD](/t/11861) |
+| 3 | h-deploy-maas | [Deploy on MAAS](/t/14293) |
+| 3 | h-deploy-terraform | [Deploy via Terraform](/t/14916) |
+| 3 | h-scale | [Scale units](/t/9689) |
+| 3 | h-enable-tls | [Enable TLS](/t/9685) |
+| 3 | h-manage-client | [Manage client applications](/t/9687) |
+| 2 | h-backups | [Back up and restore]() |
+| 3 | h-configure-s3-aws | [Configure S3 AWS](/t/9681) |
+| 3 | h-configure-s3-radosgw | [Configure S3 RadosGW](/t/10313) |
+| 3 | h-create-backup | [Create a backup](/t/9683) |
+| 3 | h-restore-backup | [Restore a backup](/t/9693) |
+| 3 | h-manage-backup-retention | [Manage backup retention](/t/14249) |
+| 3 | h-migrate-cluster | [Migrate a cluster](/t/9691) |
+| 2 | h-monitor | [Monitor (COS)]() |
+| 3 | h-enable-monitoring | [Enable monitoring](/t/10600) |
+| 3 | h-enable-alert-rules | [Enable Alert Rules](/t/13084) |
+| 3 | h-enable-tracing | [Enable tracing](/t/14521) |
+| 2 | h-upgrade | [Upgrade]() |
+| 3 | h-upgrade-intro | [Overview](/t/12086) |
+| 3 | h-upgrade-major | [Perform a major upgrade](/t/12087) |
+| 3 | h-rollback-major | [Perform a major rollback](/t/12088) |
+| 3 | h-upgrade-minor | [Perform a minor upgrade](/t/12089) |
+| 3 | h-rollback-minor | [Perform a minor rollback](/t/12090) |
+| 2 | h-integrate-your-charm | [Integrate with your charm]() |Mig
+| 3 | h-integrate-db-with-your-charm | [Integrate a database with your charm](/t/11865) |
+| 3 | h-integrate-migrate-pgdump | [Migrate data via pg_dump](/t/12163) |
+| 3 | h-integrate-migrate-backup-restore | [Migrate data via backup/restore](/t/12164) |
+| 2 | h-async | [Cross-regional async replication]() |
+| 3 | h-async-set-up | [Set up clusters](/t/13991) |
+| 3 | h-async-integrate | [Integrate with a client app](/t/13992) |
+| 3 | h-async-remove-recover | [Remove or recover a cluster](/t/13994) |
+| 2 | h-enable-plugins-extensions | [Enable plugins/extensions](/t/10906) |
+| 1 | reference | [Reference]() |
+| 2 | r-overview | [Overview](/t/13976) |
+| 2 | r-releases-group | [Release Notes]() |
+| 3 | r-releases | [All releases](/t/11875) |
+| 3 | r-revision-429 | [Revision 429/430](/t/14067) |
+| 3 | r-revision-363 | [Revision 363](/t/13124) |
+| 3 | r-revision-351 | [Revision 351](/t/12823) |
+| 3 | r-revision-336 | [Revision 336](/t/11877) |
+| 3 | r-revision-288 | [Revision 288](/t/11876) |
+| 2 | r-system-requirements | [System requirements](/t/11743) |
+| 2 | r-software-testing | [Software testing](/t/11773) |
+| 2 | r-performance | [Performance and resources](/t/11974) |
+| 2 | h-troubleshooting | [Troubleshooting](/t/11864) |
+| 2 | r-plugins-extensions | [Plugins/extensions](/t/10946) |
+| 2 | r-contacts | [Contacts](/t/11863) |
+| 1 | explanation | [Explanation]() |
+| 2 | e-architecture | [Architecture](/t/11857) |
+| 2 | e-interfaces-endpoints | [Interfaces and endpoints](/t/10251) |
+| 2 | e-statuses | [Statuses](/t/10844) |
+| 2 | e-users | [Users](/t/10798) |
+| 2 | e-logs | [Logs](/t/12099) |
+| 2 | e-juju-details | [Juju](/t/11985) |
+| 2 | e-legacy-charm | [Legacy charm](/t/10690) |
+| 1 | search | [Search](https://canonical.com/data/docs/postgresql/iaas) |
+[/details]
+# Redirects
+
+[details=Mapping table]
+| Path | Location |
+| ---- | -------- |
+[/details]
\ No newline at end of file
diff --git a/docs/reference/r-releases-group/r-releases.md b/docs/reference/r-releases-group/r-releases.md
deleted file mode 100644
index 1b02dc7247..0000000000
--- a/docs/reference/r-releases-group/r-releases.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# Release Notes
-
-Here you will find release notes for the main revisions of this charm that are available in Charmhub [channels](https://juju.is/docs/sdk/channel):
-
-* **`stable`**: production-ready releases
-* **`candidate`, `beta`, `edge`** : [risk channels](https://juju.is/docs/sdk/channel#heading--risk) - new and experimental features. Not recommended for production.
-
-## Revisions:
-
-| Channel | amd64 | arm64 |
-|---------:|:-----:|:-----:|
-| `14/stable` | [429](/t/14067) | [430](/t/14067) |
-| | [363](/t/13124) | - |
-| | [351](/t/12823) | - |
-| | [336](/t/11877) | - |
-| | [288](/t/11876) | - |
\ No newline at end of file
diff --git a/docs/reference/r-releases-group/r-revision-429.md b/docs/reference/r-releases-group/r-revision-429.md
deleted file mode 100644
index 2bf0e0e3fa..0000000000
--- a/docs/reference/r-releases-group/r-revision-429.md
+++ /dev/null
@@ -1,88 +0,0 @@
->Reference > Release Notes > [All revisions](t/11875) > Revision 429/430
-
-# Revision 429/430
-
-June 28, 2024
-
-Dear community,
-
-We'd like to announce that Canonical's newest Charmed PostgreSQL operator has been published in the 14/stable [channel](https://charmhub.io/postgresql?channel=14/stable) :tada: :
-
-| |AMD64|ARM64|
-|---:|:---:|:---:|
-| Revisions: | 429 | 430 |
-
-[note]
-If you are jumping over several stable revisions, make sure to check [previous release notes](/t/11875) before upgrading to this revision.
-[/note]
-
-## Features you can start using today
-
-* [PostgreSQL upgrade 14.10 → 14.11](https://www.postgresql.org/docs/release/14.11/) [[PR#432](https://github.com/canonical/postgresql-operator/pull/432)]
- * [check official PostgreSQL release notes!](https://www.postgresql.org/docs/release/14.11/)
-* [New ARM support!](https://charmhub.io/postgresql/docs/r-requirements) [[PR#381](https://github.com/canonical/postgresql-operator/pull/381)]
-* [Add cross-region async replication!](https://charmhub.io/postgresql/docs/h-async-setup) [[PR#452](https://github.com/canonical/postgresql-operator/pull/452)][[DPE-2953](https://warthogs.atlassian.net/browse/DPE-2953)]
-* [Add timescaledb plugin/extension](https://charmhub.io/postgresql/configuration?channel=14/candidate#plugin_timescaledb_enable) [[PR#470](https://github.com/canonical/postgresql-operator/pull/470)]
-* [Add Incremental+Differential backup support](/t/9683) [[PR#479](https://github.com/canonical/postgresql-operator/pull/479)][[DPE-4462](https://warthogs.atlassian.net/browse/DPE-4462)]
-* [Easy performance testing with sysbench](https://charmhub.io/sysbench)
-* [Add COS Tempo tracing support](/t/14521) [[PR#485](https://github.com/canonical/postgresql-operator/pull/485)][DPE-4616](https://warthogs.atlassian.net/browse/DPE-4616)]
-* Internal disable operator mode [[PR#412](https://github.com/canonical/postgresql-operator/pull/412)][[DPE-2469](https://warthogs.atlassian.net/browse/DPE-2469)]
-* Support for subordination with `ubuntu-advantage` [[PR#397](https://github.com/canonical/postgresql-operator/pull/397)][[DPE-3644](https://warthogs.atlassian.net/browse/DPE-3644)]
-* Support for subordination with `landscape-client` [[PR#388](https://github.com/canonical/postgresql-operator/pull/388)][[DPE-3644](https://warthogs.atlassian.net/browse/DPE-3644)]
-* Add retention time for backups [[PR#474](https://github.com/canonical/postgresql-operator/pull/474)][[DPE-4401](https://warthogs.atlassian.net/browse/DPE-4401)]
-* Add `experimental_max_connections` charm config option [[PR#472](https://github.com/canonical/postgresql-operator/pull/472)]
-* All the functionality from [previous revisions](https://charmhub.io/postgresql/docs/r-releases)
-
-## Bugfixes
-
-* [DPE-3882] Speed up charm bootstrap 2-3 times in [PR#413](https://github.com/canonical/postgresql-operator/pull/413)
-* [DPE-3544] Fixed large objects ownership in [PR#349](https://github.com/canonical/postgresql-operator/pull/349)
-* [DPE-3257] Fixed network cut tests in [PR#346](https://github.com/canonical/postgresql-operator/pull/346)
-* [DPE-3202] Architecture-specific snap revision in [PR#345](https://github.com/canonical/postgresql-operator/pull/345)
-* [DPE-3380] Handle S3 relation in primary non-leader unit in [PR#340](https://github.com/canonical/postgresql-operator/pull/340)
-* [DPE-3559] Stabilise restore cluster test in [PR#351](https://github.com/canonical/postgresql-operator/pull/351)
-* [DPE-3591] Fixed shared buffers validation in [PR#361](https://github.com/canonical/postgresql-operator/pull/361)
-* [DPE-4068] Finished test migration from unittest to pytest + reenable secrets [PR#451](https://github.com/canonical/postgresql-operator/pull/451)
-* [DPE-4106] Test legacy and modern endpoints simultaneously in [PR#396](https://github.com/canonical/postgresql-operator/pull/396)
-* [DPE-2674] Convert `test_charm.py` to pytest style testing instead of unit test in [PR#425](https://github.com/canonical/postgresql-operator/pull/425)
-* [DPE-3895] Handle get patroni health exception in [PR#421](https://github.com/canonical/postgresql-operator/pull/421)
-* [DPE-3593] Only check config values against the DB in `on_config_changed` in [PR#395](https://github.com/canonical/postgresql-operator/pull/395)
-* [DPE-3422] Switch to self-signed certificates in [PR#336](https://github.com/canonical/postgresql-operator/pull/336)
-* [DPE-4336] Reset active status when removing extensions dependency block in [PR#467](https://github.com/canonical/postgresql-operator/pull/467)
-* [DPE-4416] Fixed secrets crash for "certificates-relation-changed" after the refresh in [PR#475](https://github.com/canonical/postgresql-operator/pull/475)
-* [DPE-4416] Fetch charm libs to the latest LIBPATCH (dp-libs v36) in [PR#475](https://github.com/canonical/postgresql-operator/pull/475)
-* [DPE-4412] Use TLS CA chain for backups in [PR#484](https://github.com/canonical/postgresql-operator/pull/484)
-* [DPE-4032] Stop exposing passwords on postgresql SQL queries logging in [PR#495](https://github.com/canonical/postgresql-operator/pull/495)
-* [DPE-4453] Fix scale up with S3 and TLS relations in [PR#480](https://github.com/canonical/postgresql-operator/pull/480)
-* [DPE-4598] Handle upgrade of top of the stack Juju leader in [PR#492](https://github.com/canonical/postgresql-operator/pull/492)
-* [DPE-4416] Update rolling-ops lib to version 0.7 in [PR#478](https://github.com/canonical/postgresql-operator/pull/478)
-* [MISC] Suppress oversee users in standby clusters in [PR#507](https://github.com/canonical/postgresql-operator/pull/507)
-* [MISC] Updated snap, charm libs and switch away from psycopg2-binary in [PR#372](https://github.com/canonical/postgresql-operator/pull/372)
-* Added check for replicas encrypted connection in [PR#437](https://github.com/canonical/postgresql-operator/pull/437)
-* Updated `test_landscape_scalable_bundle_db` test in [PR#378](https://github.com/canonical/postgresql-operator/pull/378)
-
-Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.net/jira/software/c/projects/DPE/issues/) and [GitHub](https://github.com/canonical/postgresql-operator/issues) platforms.
-[GitHub Releases](https://github.com/canonical/postgresql-operator/releases) provide a detailed list of bugfixes, PRs, and commits for each revision.
-
-## Inside the charms
-
-* Charmed PostgreSQL ships the latest PostgreSQL `14.11-0ubuntu0.22.04.1`
-* PostgreSQL cluster manager Patroni updated to `3.1.2`
-* Backup tools pgBackRest updated to `2.48`
-* The Prometheus postgres-exporter is `0.12.1-0ubuntu0.22.04.1~ppa1`
-* VM charms based on [Charmed PostgreSQL](https://snapcraft.io/charmed-postgresql) SNAP (Ubuntu LTS `22.04.4`) revision `113`
-* Principal charms supports the latest LTS series 22.04 only
-
-## Technical notes
-
-* Upgrade via `juju refresh` is possible from revision 336+
-* Use this operator together with the modern [Charmed PgBouncer operator](https://charmhub.io/pgbouncer?channel=1/stable)
-* Please check [previously posted restrictions](https://charmhub.io/postgresql/docs/r-releases)
-* Ensure [the charm requirements](/t/11743) met
-
-## Contact us
-
-Charmed PostgreSQL is an open source project that warmly welcomes community contributions, suggestions, fixes, and constructive feedback.
-* Raise software issues or feature requests on [**GitHub**](https://github.com/canonical/postgresql-operator/issues)
-* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File)
-* Contact the Canonical Data Platform team through our [Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) channel.
\ No newline at end of file
diff --git a/docs/reference/r-releases.md b/docs/reference/r-releases.md
new file mode 100644
index 0000000000..7362525216
--- /dev/null
+++ b/docs/reference/r-releases.md
@@ -0,0 +1,27 @@
+# Release Notes
+Here you will find release notes for major revisions of this charm that are available in the [Charmhub `stable` channel](https://juju.is/docs/juju/channel#heading--risk).
+
+To see **all** charm revisions, check the [Charmed PostgreSQL Releases page](https://github.com/canonical/postgresql-operator/releases) on GitHub.
+
+## At a glance
+
+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) |
+|:--------:|:-----:|:-----:|:--------------------:|:---------------:|:--------------------:|
+| [430](/t/14067) | :heavy_multiplication_x: |:white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
+| [429](/t/14067) | :white_check_mark: | :heavy_multiplication_x: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
+| [363](/t/13124) | :white_check_mark: | :heavy_multiplication_x: | :white_check_mark: | :white_check_mark: | :heavy_multiplication_x: |
+| [351](/t/12823) | :white_check_mark: | :heavy_multiplication_x: | :heavy_multiplication_x: | :white_check_mark: | :heavy_multiplication_x: |
+| [336](/t/11877) | :white_check_mark: | :heavy_multiplication_x: | :heavy_multiplication_x: | :white_check_mark: | :heavy_multiplication_x: |
+| [288](/t/11876) | :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).
+
+For more details about a particular revision, refer to its dedicated Release Notes page.
+For more details about each feature/interface, refer to their dedicated How-To guide.
+
+### Plugins/extensions
+
+For a list of all plugins supported for each revision, see the reference page [Plugins/extensions](/t/10946).
\ No newline at end of file
diff --git a/docs/reference/r-releases-group/r-revision-288.md b/docs/reference/r-revision-288.md
similarity index 100%
rename from docs/reference/r-releases-group/r-revision-288.md
rename to docs/reference/r-revision-288.md
diff --git a/docs/reference/r-releases-group/r-revision-336.md b/docs/reference/r-revision-336.md
similarity index 100%
rename from docs/reference/r-releases-group/r-revision-336.md
rename to docs/reference/r-revision-336.md
diff --git a/docs/reference/r-releases-group/r-revision-351.md b/docs/reference/r-revision-351.md
similarity index 100%
rename from docs/reference/r-releases-group/r-revision-351.md
rename to docs/reference/r-revision-351.md
diff --git a/docs/reference/r-releases-group/r-revision-363.md b/docs/reference/r-revision-363.md
similarity index 100%
rename from docs/reference/r-releases-group/r-revision-363.md
rename to docs/reference/r-revision-363.md
diff --git a/docs/reference/r-revision-429.md b/docs/reference/r-revision-429.md
new file mode 100644
index 0000000000..a8ad5bd988
--- /dev/null
+++ b/docs/reference/r-revision-429.md
@@ -0,0 +1,100 @@
+>Reference > Release Notes > [All revisions](t/11875) > Revision 429/430
+
+# Revision 429/430
+
+June 28, 2024
+
+Dear community,
+
+Canonical's newest Charmed PostgreSQL operator has been published in the 14/stable [channel](https://charmhub.io/postgresql?channel=14/stable) :tada:
+
+Due to the newly added support for `arm64` architecture, the PostgreSQL charm now releases two revisions simultaneously:
+* Revision 429 is built for `amd64`
+* Revision 430 is built for for `arm64`
+
+To make sure you deploy for the right architecture, we recommend setting an [architecture constraint](https://juju.is/docs/juju/constraint#heading--arch) for your entire juju model.
+
+Otherwise, it can be done at deploy time with the `--constraints` flag:
+```shell
+juju deploy postgresql --constraints arch=
+```
+where `` can be `amd64` or `arm64`.
+
+[note]
+If you are jumping over several stable revisions, check [previous release notes](/t/11875) before upgrading.
+[/note]
+
+---
+
+## Highlights
+Below are the major highlights of this release. To see all changes since the previous stable release, check the [release notes on GitHub](https://github.com/canonical/postgresql-operator/releases/tag/rev430).
+
+* Upgraded PostgreSQL from v.14.10 → v.14.11 ([PR #432](https://github.com/canonical/postgresql-operator/pull/432))
+ * Check the official [PostgreSQL release notes](https://www.postgresql.org/docs/release/14.11/)
+* Added support for ARM64 architecture ([PR #381](https://github.com/canonical/postgresql-operator/pull/381))
+* Added support for cross-regional asynchronous replication ([PR #452](https://github.com/canonical/postgresql-operator/pull/452)) ([DPE-2953](https://warthogs.atlassian.net/browse/DPE-2953))
+ * This feature focuses on disaster recovery by distributing data across different servers. Check our [new how-to guides](https://charmhub.io/postgresql/docs/h-async-set-up) for a walkthrough of the cross-model setup, promotion, switchover, and other details.
+* Added support for tracing with Tempo K8s ([PR #485](https://github.com/canonical/postgresql-operator/pull/485)) ([DPE-4616](https://warthogs.atlassian.net/browse/DPE-4616))
+ * Check our new guide: [How to enable tracing](https://charmhub.io/postgresql/docs/h-enable-tracing)
+* Released new [Charmed Sysbench operator](https://charmhub.io/sysbench) for easy performance testing
+
+### Enhancements
+* Added timescaledb plugin/extension ([PR#470](https://github.com/canonical/postgresql-operator/pull/470))
+ * See the [Configuration tab]((https://charmhub.io/postgresql/configuration?channel=14/candidate#plugin_timescaledb_enable)) for a full list of supported plugins/extensions
+* Added incremental and differential backup support ([PR #479](https://github.com/canonical/postgresql-operator/pull/479)) ([DPE-4462](https://warthogs.atlassian.net/browse/DPE-4462))
+ * Check our guide: [How to create and list backups](https://charmhub.io/postgresql/docs/h-create-backup)
+* Added support for disabling the operator ([PR#412](https://github.com/canonical/postgresql-operator/pull/412)) ([DPE-2469](https://warthogs.atlassian.net/browse/DPE-2469))
+* Added support for subordination with:
+ * `ubuntu-advantage` ([PR#397](https://github.com/canonical/postgresql-operator/pull/397)) ([DPE-3644](https://warthogs.atlassian.net/browse/DPE-3644))
+ * `landscape-client` ([PR#388](https://github.com/canonical/postgresql-operator/pull/388)) ([DPE-3644](https://warthogs.atlassian.net/browse/DPE-3644))
+* Added configuration option for backup retention time ([PR#474](https://github.com/canonical/postgresql-operator/pull/474))([DPE-4401](https://warthogs.atlassian.net/browse/DPE-4401))
+* Added `experimental_max_connections` config option ([PR#472](https://github.com/canonical/postgresql-operator/pull/472))
+* Added check for replicas encrypted connection ([PR#437](https://github.com/canonical/postgresql-operator/pull/437))
+
+### Bugfixes
+* Fixed slow charm bootstrap time ([PR#413](https://github.com/canonical/postgresql-operator/pull/413))
+* Fixed large objects ownership ([PR#349](https://github.com/canonical/postgresql-operator/pull/349))
+* Fixed secrets crash for "certificates-relation-changed" after the refresh ([PR#475](https://github.com/canonical/postgresql-operator/pull/475))
+* Fixed network cut tests ([PR#346](https://github.com/canonical/postgresql-operator/pull/346)) ([DPE-3257](https://warthogs.atlassian.net/browse/DPE-3257))
+
+Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.net/jira/software/c/projects/DPE/issues/) and [GitHub](https://github.com/canonical/postgresql-operator/issues).
+
+For a full list of all changes in this revision, see the [GitHub Release](https://github.com/canonical/postgresql-operator/releases/tag/rev430).
+
+## Technical details
+This section contains some technical details about the charm's contents and dependencies. Make sure to also check the [system requirements](/t/11743).
+
+### Packaging
+This charm is based on the [`charmed-postgresql` snap](https://snapcraft.io/charmed-postgresql) (pinned revision 113). It packages:
+* postgresql `v.14.11`
+ * [`14.11-0ubuntu0.22.04.1`](https://launchpad.net/ubuntu/+source/postgresql-14/14.11-0ubuntu0.22.04.1)
+* pgbouncer `v.1.21`
+ * [`1.21.0-0ubuntu0.22.04.1~ppa1`](https://launchpad.net/~data-platform/+archive/ubuntu/pgbouncer)
+* patroni `v.3.1.2 `
+ * [`3.1.2-0ubuntu0.22.04.1~ppa2`](https://launchpad.net/~data-platform/+archive/ubuntu/patroni)
+* pgBackRest `v.2.48`
+ * [`2.48-0ubuntu0.22.04.1~ppa1`](https://launchpad.net/~data-platform/+archive/ubuntu/pgbackrest)
+* prometheus-postgres-exporter `v.0.12.1`
+
+### Libraries and interfaces
+This charm revision imports the following libraries:
+
+* **grafana_agent `v0`** for integration with Grafana
+ * Implements `cos_agent` interface
+* **rolling_ops `v0`** for rolling operations across units
+ * Implements `rolling_op` interface
+* **tempo_k8s `v1`, `v2`** for integration with Tempo charm
+ * Implements `tracing` interface
+* **tls_certificates_interface `v2`** for integration with TLS charms
+ * Implements `tls-certificates` interface
+
+See the [`/lib/charms` directory on GitHub](https://github.com/canonical/postgresql-operator/tree/main/lib/charms) for more details about all supported libraries.
+
+See the [`metadata.yaml` file on GitHub](https://github.com/canonical/postgresql-operator/blob/main/metadata.yaml) for a full list of supported interfaces
+
+## Contact us
+
+Charmed PostgreSQL is an open source project that warmly welcomes community contributions, suggestions, fixes, and constructive feedback.
+* Raise software issues or feature requests on [**GitHub**](https://github.com/canonical/postgresql-operator/issues)
+* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File)
+* Contact the Canonical Data Platform team through our [Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) channel.
\ No newline at end of file