Sync docs from Discourse (#854)

Co-authored-by: GitHub Actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: github-actions[bot]

docs/explanation.md

@@ -0,0 +1,31 @@
+# Explanation
+
+This section contains pages with more detailed explanations that provide additional context about some of the key concepts behind the PostgreSQL charm:
+
+* [Architecture]
+* [Interfaces and endpoints]
+* [Connection pooling]
+* [Statuses]
+* [Users]
+* [Logs]
+* [Juju]
+* [Legacy charm]
+
+Charm event flowcharts:
+* [Charm]
+* [Relations]
+* [Backups]
+
+<!-- Links -->
+
+[Architecture]: /t/11856
+[Interfaces and endpoints]: /t/10252
+[Statuses]: /t/11855
+[Users]: /t/10843
+[Logs]: /t/12098
+[Juju]: /t/11986
+[Legacy charm]: /t/11013
+[Connection pooling]: /t/15799
+[Charm]: /t/9305
+[Relations]: /t/9306
+[Backups]: /t/10248

docs/explanation/e-juju-details.md

@@ -1,32 +1,32 @@
-# Juju tech details
-
+# Juju
 [Juju](https://juju.is/) is an open source orchestration engine for software operators that enables the deployment, integration and lifecycle management of applications at any scale, on any infrastructure using charms.
 
-This [charm](https://charmhub.io/postgresql-k8s) is an operator - business logic encapsulated in reusable software packages that automate every aspect of an application's life. Charms are shared via [CharmHub](https://charmhub.io/).
+> See also: [Juju client documentation](https://juju.is/docs/juju), [Juju blog](https://ubuntu.com/blog/tag/juju)
 
-See also:
+## Compatibility with PostgreSQL
+Current stable releases of this charm can still be deployed on Juju 2.9. However, newer features are not supported.
+> See the [Releases page](/t/11872) for more information about the minimum Juju version required to operate the features of each revision. 
 
-* [Juju Documentation](https://juju.is/docs/juju) and [Blog](https://ubuntu.com/blog/tag/juju)
-* [Charm SDK](https://juju.is/docs/sdk)
+Additionally, there are limitations regarding integrations with other charms. For example, integration with  [modern TLS charms](https://charmhub.io/topics/security-with-x-509-certificates) requires Juju 3.x.
 
 ## Breaking changes between Juju 2.9.x and 3.x
 
-As this charm documentation is written for Juju 3.x, users of 2.9.x will encounter noteworthy changes when following the instructions. This section explains those changes.
+As this charm's documentation is written for Juju 3.x, users of 2.9.x will encounter noteworthy changes when following the instructions. This section explains those changes.
 
 Breaking changes have been introduced in the Juju client between versions 2.9.x and 3.x. These are caused by the renaming and re-purposing of several commands - functionality and command options remain unchanged.
 
-In the context of this guide, the pertinent changes are shown here:
+In the context of this guide, the pertinent changes are as follows:
 
-|2.9.x|3.x|
+| v2.9.x | v3.x |
 | --- | --- |
-|**add-relation**|**integrate**|
-|**relate**|**integrate**|
-|**run**|**exec**|
-|**run-action --wait**|**run**|
+|`add-relation`|`integrate`|
+|`relate`|`integrate`|
+|`run`|`exec`|
+|`run-action --wait`|`run`|
 
 See the [Juju 3.0 release notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022) for the comprehensive list of changes.
 
-The response is to therefore substitute the documented command with the equivalent 2.9.x command. For example:
+Example substitutions:
 
 ### Juju 3.x:
 ```shell

docs/how-to.md

@@ -0,0 +1,99 @@
+# How-to guides
+
+The following guides cover key processes and common tasks for managing and using Charmed PostgreSQL on Kubernetes.
+
+## Deployment and setup
+
+The following guides walk you through the details of how to install different cloud services and bootstrap them to Juju:
+* [Canonical K8s]
+* [MicroK8s]
+* [GKE]
+* [EKS]
+* [AKS]
+* [Multi-availability zones (AZ)][Multi-AZ]
+
+The following guides cover some specific deployment scenarios and architectures:
+* [Terraform]
+* [Air-gapped]
+
+## Usage and maintenance
+
+* [Integrate with another application]
+* [External access]
+* [Scale replicas]
+* [Enable TLS]
+* [Enable plugins/extensions]
+
+## Backup and restore
+* [Configure S3 AWS]
+* [Configure S3 RadosGW]
+* [Create a backup]
+* [Restore a backup]
+* [Manage backup retention]
+* [Migrate a cluster]
+
+## Monitoring (COS)
+
+* [Enable monitoring]
+* [Enable alert rules]
+* [Enable tracing]
+
+## Minor upgrades
+* [Perform a minor upgrade]
+* [Perform a minor rollback]
+
+## Cross-regional (cluster-cluster) async replication
+
+* [Cross-regional async replication]
+    * [Set up clusters]
+    * [Integrate with a client app]
+    * [Remove or recover a cluster]
+    * [Enable plugins/extensions]
+
+## Development
+
+This section is aimed at charm developers looking to support PostgreSQL integrations with their charm.
+
+* [Integrate with your charm]
+* [Migrate data via pg_dump]
+* [Migrate data via backup/restore]
+
+<!--Links-->
+
+[Canonical K8s]: /t/15937
+[MicroK8s]: /t/11858
+[GKE]: /t/11237
+[EKS]: /t/12106
+[AKS]: /t/14307
+[Multi-AZ]: /t/15678
+[Terraform]: /t/14924
+[Air-gapped]: /t/15691
+
+[Integrate with another application]: /t/9594
+[External access]: /t/15701
+[Scale replicas]: /t/9592
+[Enable TLS]: /t/9593
+[Enable plugins/extensions]: /t/10907
+
+[Configure S3 AWS]: /t/9595
+[Configure S3 RadosGW]: /t/10316
+[Create a backup]: /t/9596
+[Restore a backup]: /t/9597
+[Manage backup retention]: /t/14203
+[Migrate a cluster]: /t/9598
+
+[Enable monitoring]: /t/10812
+[Enable alert rules]: /t/12982
+[Enable tracing]: /t/14786
+
+[Perform a minor upgrade]: /t/12095
+[Perform a minor rollback]: /t/12096
+
+[Cross-regional async replication]: /t/15413
+[Set up clusters]: /t/13895
+[Integrate with a client app]: /t/13896
+[Remove or recover a cluster]: /t/13897
+
+[Integrate with your charm]: /t/11853
+[Migrate data via pg_dump]: /t/12162
+[Migrate data via backup/restore]: /t/12161

docs/how-to/h-deploy-microk8s.md

@@ -0,0 +1,75 @@
+# How to deploy
+
+This page aims to provide an introduction to the PostgreSQL deployment process and lists all the related guides. It contains the following sections:
+* [General deployment instructions](#general-deployment-instructions)
+* [Clouds](#clouds)
+* [Special deployments](#special-deployments)
+
+---
+
+## General deployment instructions
+
+The basic requirements for deploying a charm are the [**Juju client**](https://juju.is/docs/juju) and a Kubernetes [**cloud**](https://juju.is/docs/juju/cloud).
+
+First, [bootstrap](https://juju.is/docs/juju/juju-bootstrap) the cloud controller and create a [model](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/model/): 
+```shell
+juju bootstrap <cloud name> <controller name>
+juju add-model <model name>
+```
+
+Then, either continue with the `juju` client **or** use the `terraform juju` client to deploy the PostgreSQL charm.
+
+To deploy with the `juju` client:
+```shell
+juju deploy postgresql-k8s --trust
+```
+> See also: [`juju deploy` command](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/juju-cli/list-of-juju-cli-commands/deploy/)
+
+To deploy with `terraform juju`, follow the guide [How to deploy using Terraform](/t/).
+> See also: [Terraform Provider for Juju documentation](https://canonical-terraform-provider-juju.readthedocs-hosted.com/en/latest/)
+
+If you are not sure where to start or would like a more guided walkthrough for setting up your environment, see the [Charmed PostgreSQL K8s tutorial][Tutorial].
+
+## Clouds
+
+The guides below go through the steps to install different cloud services and bootstrap them to Juju:
+* [Canonical K8s]
+* [Google Kubernetes Engine]
+* [Amazon Elastic Kubernetes Service]
+* [Azure Kubernetes Service]
+
+[How to deploy on multiple availability zones (AZ)] demonstrates how to deploy a cluster on a cloud using different AZs for high availability.
+
+## Special deployments
+
+These guides cover some specific deployment scenarios and architectures.
+
+### External network access 
+
+See [How to connect from outside the local network] for guidance on connecting with a client application outside PostgreSQL's Kubernetes cluster. 
+
+### Airgapped
+[How to deploy in an offline or air-gapped environment] goes over the special configuration steps for installing PostgreSQL in an airgapped environment via CharmHub and the Snap Store Proxy.
+
+### Cluster-cluster replication
+Cluster-cluster, cross-regional, or multi-server asynchronous replication focuses on disaster recovery by distributing data across different servers. 
+
+The [Cross-regional async replication] guide goes through the steps to set up clusters for cluster-cluster replication, integrate with a client, and remove or recover a failed cluster.
+
+[Tutorial]: /t/9296
+
+[How to deploy using Terraform]: /t/14924
+
+[Canonical K8s]: /t/15937
+[Google Kubernetes Engine]: /t/11237
+[Amazon Elastic Kubernetes Service]: /t/12106
+[Azure Kubernetes Service]: /t/14307
+
+[How to deploy on multiple availability zones (AZ)]: /t/15678
+
+
+[How to enable TLS]: /t/9593
+[How to connect from outside the local network]: /t/15701
+
+[How to deploy in an offline or air-gapped environment]: /t/15691
+[Cross-regional async replication]: /t/15413

docs/how-to/h-deploy.md

@@ -0,0 +1,12 @@
+# Upgrade 
+
+Currently, the charm supports PostgreSQL major version 14 only. Therefore, in-place upgrades/rollbacks are not possible for major versions. 
+
+> **Note**: Canonical is not planning to support in-place upgrades for major version change. The new PostgreSQL K8s charm will have to be installed nearby, and the data will be copied from the old to the new installation. After announcing the next PostgreSQL major version support, the appropriate documentation for data migration will be published.
+
+For instructions on carrying out **minor version upgrades**, see the following guides:
+
+* [Minor upgrade](/t/12095), e.g. PostgreSQL 14.8 -> PostgreSQL 14.9<br/>
+(including charm revision bump 42 -> 43).
+* [Minor rollback](/t/12096), e.g. PostgreSQL 14.9 -> PostgreSQL 14.8<br/>
+(including charm revision return 43 -> 42).