Sync docs from Discourse (#748)

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

Author: github-actions[bot]

docs/explanation.md

@@ -0,0 +1,21 @@
+# 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]
+* [Users]
+* [Logs]
+* [Juju]
+* [Legacy charm]
+
+<!-- Links -->
+
+[Architecture]: /t/11857
+[Interfaces and endpoints]: /t/10251
+[Users]: /t/10798
+[Logs]: /t/12099
+[Juju]: /t/11985
+[Legacy charm]: /t/10690
+[Connection pooling]: /t/15777

docs/explanation/e-cryptography.md

@@ -0,0 +1,61 @@
+# Cryptography
+
+This document describes the cryptography used by Charmed PostgreSQL.
+
+## Resource checksums
+
+Charmed PostgreSQL and Charmed PgBouncer operators use pinned versions of the respective snaps to provide reproducible and secure environments.
+
+The snaps package their workloads along with the necessary dependencies and utilities required for the operators’ lifecycle. For more details, see the snaps content in the `snapcraft.yaml` file for [PostgreSQL](https://github.com/canonical/charmed-postgresql-snap/blob/14/edge/snap/snapcraft.yaml) and [PgBouncer](https://github.com/canonical/charmed-pgbouncer-snap/blob/1/edge/snap/snapcraft.yaml).
+
+Every artifact bundled into a snap is verified against its MD5, SHA256, or SHA512 checksum after download. The installation of certified snap into the rock is ensured by snap primitives that verify their squashfs filesystems images GPG signature. For more information on the snap verification process, refer to the [snapcraft.io documentation](https://snapcraft.io/docs/assertions).
+
+## Sources verification
+
+PostgreSQL and its extra components are built by Canonical from upstream source codes on [Launchpad](https://launchpad.net/ubuntu/+source/postgresql-common). PostgreSQL and PgBouncer are built as deb packages, other components - as PPAs.
+
+Charmed PostgreSQL and Charmed PgBouncer charms and snaps are published and released programmatically using release pipelines implemented via GitHub Actions in their respective repositories.
+
+All repositories in GitHub are set up with branch protection rules, requiring:
+
+* new commits to be merged to main branches via pull request with at least 2 approvals from repository maintainers
+* new commits to be signed (e.g. using GPG keys)
+* developers to sign the [Canonical Contributor License Agreement (CLA)](https://ubuntu.com/legal/contributors)
+
+## Encryption
+
+Charmed PostgreSQL can be used to deploy a secure PostgreSQL cluster that provides encryption-in-transit capabilities out of the box for:
+
+* Cluster internal communications
+* PgBouncer connections
+* External clients connections
+
+To set up a secure connection Charmed PostgreSQL and Charmed PgBouncer need to be integrated with TLS Certificate Provider charms, e.g. self-signed-certificates operator. Certificate Signing Requests (CSRs) are generated for every unit using the tls_certificates_interface library that uses the cryptography Python library to create X.509 compatible certificates. The CSR is signed by the TLS Certificate Provider, returned to the units, and stored in Juju secret. The relation also provides the CA certificate, which is loaded into Juju secret.
+
+Encryption at rest is currently not supported, although it can be provided by the substrate (cloud or on-premises).
+
+## Authentication
+
+In Charmed PostgreSQL, authentication layers can be enabled for:
+
+1. PgBouncer authentication to PostgreSQL
+2. PostgreSQL cluster authentication
+3. Clients authentication to PostgreSQL
+
+### PgBouncer authentication to PostgreSQL
+
+Authentication of PgBouncer to PostgreSQL is based on the password-based `scram-sha-256` authentication method. See the [PostgreSQL official documentation](https://www.postgresql.org/docs/14/auth-password.html) for more details.
+
+Credentials are exchanged via [Juju secrets](https://canonical-juju.readthedocs-hosted.com/en/latest/user/howto/manage-secrets/).
+
+### PostgreSQL cluster authentication
+
+Authentication among members of a PostgreSQL cluster is based on the password-based `scram-sha-256` authentication method.
+
+An internal user is used for this authentication with its hashed password stored in a system metadata database. These credentials are also stored as a plain text file on the disk of each unit for the Patroni HA service.
+
+### Clients authentication to PostgreSQL
+
+Authentication of clients to PostgreSQL is based on the password-based `scram-sha-256` authentication method. See the [PostgreSQL official documentation](https://www.postgresql.org/docs/14/auth-password.html) for more details.
+
+Credentials are exchanged via [Juju secrets](https://canonical-juju.readthedocs-hosted.com/en/latest/user/howto/manage-secrets/).

docs/explanation/e-juju-details.md

@@ -1,32 +1,34 @@
-# 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) 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
 
-* [Juju Documentation](https://juju.is/docs/juju) and [Blog](https://ubuntu.com/blog/tag/juju)
-* [Charm SDK](https://juju.is/docs/sdk)
+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/11875) for more information about the minimum Juju version required to operate the features of each revision. 
+
+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.
 
 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/explanation/e-security.md

@@ -0,0 +1,92 @@
+# Security hardening guide
+
+This document provides an overview of security features and guidance for hardening the security of [Charmed PostgreSQL](https://charmhub.io/postgresql) deployments, including setting up and managing a secure environment.
+
+## Environment
+
+The environment where Charmed PostgreSQL operates can be divided into two components:
+
+1. Cloud
+2. Juju
+
+### Cloud
+
+Charmed PostgreSQL can be deployed on top of several clouds and virtualization layers:
+
+|Cloud|Security guides|
+| --- | --- |
+|OpenStack|[OpenStack Security Guide](https://docs.openstack.org/security-guide/)|
+|AWS|[Best Practices for Security, Identity and Compliance](https://aws.amazon.com/architecture/security-identity-compliance), [AWS security credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html#access-keys-and-secret-access-keys)|
+|Azure|[Azure security best practices and patterns](https://learn.microsoft.com/en-us/azure/security/fundamentals/best-practices-and-patterns), [Managed identities for Azure resource](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/)|
+|GCP|[Google security overview](https://cloud.google.com/docs/security)|
+
+### Juju
+
+Juju is the component responsible for orchestrating the entire lifecycle, from deployment to Day 2 operations. For more information on Juju security hardening, see the [Juju security page](https://canonical-juju.readthedocs-hosted.com/en/latest/user/explanation/juju-security/) and the [How to harden your deployment](https://juju.is/docs/juju/harden-your-deployment) guide.
+
+#### Cloud credentials
+
+When configuring cloud credentials to be used with Juju, ensure that users have correct permissions to operate at the required level. Juju superusers responsible for bootstrapping and managing controllers require elevated permissions to manage several kinds of resources, such as virtual machines, networks, storages, etc. Please refer to the links below for more information on the policies required to be used depending on the cloud.
+
+|Cloud|Cloud user policies|
+| --- | --- |
+|OpenStack|N/A|
+|AWS|[Juju AWS Permission](/t/juju-aws-permissions/5307), [AWS Instance Profiles](/t/using-aws-instance-profiles-with-juju-2-9/5185), [Juju on AWS](https://juju.is/docs/juju/amazon-ec2)|
+|Azure|[Juju Azure Permission](https://juju.is/docs/juju/microsoft-azure), [How to use Juju with Microsoft Azure](/t/how-to-use-juju-with-microsoft-azure/15219)|
+|GCP|[Google Cloud's Identity and Access Management](https://cloud.google.com/iam/docs/overview), [GCE role recommendations](https://cloud.google.com/policy-intelligence/docs/role-recommendations-overview), [Google GCE cloud and Juju](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/cloud/list-of-supported-clouds/the-google-gce-cloud-and-juju/)|
+
+#### Juju users
+
+It is very important that Juju users are set up with minimal permissions depending on the scope of their operations. Please refer to the [User access levels](https://juju.is/docs/juju/user-permissions) documentation for more information on the access levels and corresponding abilities.
+
+Juju user credentials must be stored securely and rotated regularly to limit the chances of unauthorized access due to credentials leakage.
+
+## Applications
+
+In the following sections, we provide guidance on how to harden your deployment using:
+
+1. Operating system
+2. Security upgrades
+3. Encryption
+4. Authentication
+5. Monitoring and auditing
+
+### Operating system
+
+Charmed PostgreSQL and Charmed PgBouncer run on top of Ubuntu 22.04. Deploy a [Landscape Client Charm](https://charmhub.io/landscape-client?) to connect the underlying VM to a Landscape User Account to manage security upgrades and integrate [Ubuntu Pro](https://ubuntu.com/pro) subscriptions.
+
+### Security upgrades
+
+[Charmed PostgreSQL](https://charmhub.io/postgresql) and [Charmed PgBouncer](https://charmhub.io/pgbouncer) operators install pinned versions of their respective snaps to provide reproducible and secure environments.
+
+New versions (revisions) of the charmed operators can be released to update the operator's code, workloads, or both. It is important to refresh the charms regularly to make sure the workloads are as secure as possible.
+
+For more information on upgrading Charmed PostgreSQL, see the [How to upgrade PostgreSQL](https://canonical.com/data/docs/postgresql/iaas/h-upgrade) and [How to upgrade PgBouncer](https://charmhub.io/pgbouncer/docs/h-upgrade) guides, as well as the respective Release notes for [PostgreSQL](https://canonical.com/data/docs/postgresql/iaas/r-releases) and [PgBouncer](https://charmhub.io/pgbouncer/docs/r-releases).
+
+### Encryption
+
+To utilise encryption at transit for all internal and external cluster connections, integrate Charmed PostgreSQL with a TLS certificate provider. Please refer to the [Charming Security page](https://charmhub.io/topics/security-with-x-509-certificates) for more information on how to select the right certificate provider for your use case.
+
+Encryption in transit for backups is provided by the storage service (Charmed PostgreSQL is a client for an S3-compatible storage).
+
+For more information on encryption, see the [Cryptography](/t/charmed-postgresql-explanations-encryption/16853) explanation page and [How to enable encryption](https://canonical.com/data/docs/postgresql/iaas/h-enable-tls) guide.
+
+### Authentication
+
+Charmed PostgreSQL supports the password-based `scram-sha-256` authentication method for authentication between:
+
+* External connections to clients
+* Internal connections between members of cluster
+* PgBouncer connections
+
+For more implementation details, see the [PostgreSQL documentation](https://www.postgresql.org/docs/14/auth-password.html).
+
+### Monitoring and auditing
+
+Charmed PostgreSQL provides native integration with the [Canonical Observability Stack (COS)](https://charmhub.io/topics/canonical-observability-stack). To reduce the blast radius of infrastructure disruptions, the general recommendation is to deploy COS and the observed application into separate environments, isolated from one another. Refer to the [COS production deployments best practices](https://charmhub.io/topics/canonical-observability-stack/reference/best-practices) for more information or see the How to guides for PostgreSQL [monitoring](https://canonical.com/data/docs/postgresql/iaas/h-enable-monitoring), [alert rules](https://canonical.com/data/docs/postgresql/iaas/h-enable-alert-rules), and [tracing](https://canonical.com/data/docs/postgresql/iaas/h-enable-tracing) for practical instructions.
+
+PostgreSQL logs are stored in `/var/snap/charmed-postgresql/common/var/log/postgresql` within the postgresql container of each unit. It’s recommended to integrate the charm with [COS](/t/10600), from where the logs can be easily persisted and queried using [Loki](https://charmhub.io/loki-k8s)/[Grafana](https://charmhub.io/grafana).
+
+## Additional Resources
+
+For details on the cryptography used by Charmed PostgreSQL, see the [Cryptography](/t/charmed-postgresql-explanations-encryption/16853) explanation page.

docs/how-to.md

@@ -0,0 +1,102 @@
+# How-to guides
+
+The following guides cover key processes and common tasks for managing and using Charmed PostgreSQL on machines.
+
+## Deployment and setup
+
+The following guides walk you through the details of how to install different cloud services and bootstrap them to Juju:
+* [Sunbeam]
+* [LXD]
+* [MAAS]
+* [AWS EC2]
+* [GCE]
+* [Azure]
+* [Multi-availability zones (AZ)][Multi-AZ]
+
+The following guides cover some specific deployment scenarios and architectures:
+* [Terraform]
+* [Air-gapped]
+* [TLS VIP access]
+
+## 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-->
+
+[Sunbeam]: /t/15972
+[LXD]: /t/11861
+[MAAS]: /t/14293
+[AWS EC2]: /t/15703
+[GCE]: /t/15722
+[Azure]: /t/15733
+[Multi-AZ]: /t/15749
+[Terraform]: /t/14916
+[Air-gapped]: /t/15746
+[TLS VIP access]: /t/16576
+[Integrate with another application]: /t/9687
+[External access]: /t/15802
+[Scale replicas]: /t/9689
+[Enable TLS]: /t/9685
+
+[Configure S3 AWS]: /t/9681
+[Configure S3 RadosGW]: /t/10313
+[Create a backup]: /t/9683
+[Restore a backup]: /t/9693
+[Manage backup retention]: /t/14249
+[Migrate a cluster]: /t/9691
+
+[Enable monitoring]: /t/10600
+[Enable alert rules]: /t/13084
+[Enable tracing]: /t/14521
+ 
+[Perform a minor upgrade]: /t/12089
+[Perform a minor rollback]: /t/12090
+
+[Cross-regional async replication]: /t/15412
+[Set up clusters]: /t/13991
+[Integrate with a client app]: /t/13992
+[Remove or recover a cluster]: /t/13994
+[Enable plugins/extensions]: /t/10906
+
+[Integrate with your charm]: /t/11865
+[Migrate data via pg_dump]: /t/12163
+[Migrate data via backup/restore]: /t/12164