Sync docs from Discourse (#864)

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

Author: github-actions[bot]

docs/explanation.md

@@ -2,15 +2,22 @@
 
 This section contains pages with more detailed explanations that provide additional context about some of the key concepts behind the PostgreSQL charm:
 
+## Core concepts and design
 * [Architecture]
 * [Interfaces and endpoints]
-* [Connection pooling]
-* [Statuses]
-* [Users]
-* [Logs]
 * [Juju]
 * [Legacy charm]
 
+## Operational concepts
+* [Users]
+* [Logs]
+* [Connection pooling]
+
+## Security and hardening
+* [Security hardening guide][Security]
+  * [Cryptography]
+
+## Development
 Charm event flowcharts:
 * [Charm]
 * [Relations]
@@ -20,12 +27,13 @@ Charm event flowcharts:
 
 [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
+[Backups]: /t/10248
+[Security]: /t/16850
+[Cryptography]: /t/16851

docs/explanation/e-architecture.md

@@ -92,6 +92,10 @@ The rock "charmed-postgresql" also ships list of tools used by charm:
 
 The charm "[PostgreSQL Test App](https://charmhub.io/postgresql-test-app)" is a Canonical test application to validate the charm installation / functionality and perform the basic performance tests.
 
+### GLAuth
+
+GLAuth is a secure, easy-to-use and open-sourced LDAP server which provides capabilities to centrally manage accounts across infrastructures. The charm is available for Kubernetes clouds under the [GLAuth-K8s operator](https://charmhub.io/glauth-k8s) page.
+
 ### Grafana
 
 Grafana is an open-source visualization tools that allows to query, visualize, alert on, and visualize metrics from mixed datasources in configurable dashboards for observability. This charms is shipped with its own Grafana dashboard and supports integration with the [Grafana Operator](https://charmhub.io/grafana-k8s) to simplify observability. Please follow [COS Monitoring](/t/10812) setup.

docs/explanation/e-cryptography.md

@@ -0,0 +1,61 @@
+# Cryptography
+
+This document describes the cryptography used by Charmed PostgreSQL K8s.
+
+## Resource checksums
+
+Charmed PostgreSQL K8s and Charmed PgBouncer K8s operators use pinned versions of the respective images ([Charmed PostgreSQL rock](https://github.com/orgs/canonical/packages/container/package/charmed-postgresql) and [PgBouncer rock](https://github.com/canonical/charmed-pgbouncer-rock/pkgs/container/charmed-pgbouncer)) to provide reproducible and secure environments.
+
+The rocks are OCI images derived from the respective snaps. Snaps package their workload 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 K8s and Charmed PgBouncer K8s charms, snaps, and rocks 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 K8s can be used to deploy a secure PostgreSQL cluster on K8s 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 K8s and Charmed PgBouncer K8s 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-security.md

@@ -0,0 +1,96 @@
+# Security hardening guide
+
+This document provides an overview of security features and guidance for hardening the security of [Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s) deployments, including setting up and managing a secure environment.
+
+## Environment
+
+The environment where Charmed PostgreSQL K8s operates can be divided into two components:
+
+1. Kubernetes
+2. Juju
+
+### Kubernetes
+
+Charmed PostgreSQL K8s can be deployed on top of several Kubernetes distributions. The following table provides references for the security documentation for the main supported cloud platforms.
+
+|Cloud|Security guides|
+| --- | --- |
+|Canonical Kubernetes|[Security overview](https://ubuntu.com/kubernetes/docs/security), [How to secure a cluster](https://ubuntu.com/kubernetes/docs/how-to-security)|
+|microK8s|[CIS compliance](https://microk8s.io/docs/cis-compliance), [Cluster hardening guide](https://microk8s.io/docs/how-to-cis-harden)|
+|AWS EKS|[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), [Security in EKS](https://docs.aws.amazon.com/eks/latest/userguide/security.html)|
+|Azure AKS|[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/), [Security in AKS](https://learn.microsoft.com/en-us/azure/aks/concepts-security)|
+|GCP GKE|[Google security overview](https://cloud.google.com/kubernetes-engine/docs/concepts/security-overview), [Harden your cluster’s security](https://cloud.google.com/kubernetes-engine/docs/how-to/hardening-your-cluster)|
+
+### 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 the correct permissions to operate at the required level on the Kubernetes cluster. Juju superusers responsible for bootstrapping and managing controllers require elevated permissions to manage several kinds of resources. For this reason, the K8s user for bootstrapping and managing the deployments should have full permissions, such as:
+
+* create, delete, patch, and list:
+  * namespaces
+  * services
+  * deployments
+  * stateful sets
+  * pods
+  * PVCs
+
+In general, it is common practice to run Juju using the admin role of K8s, to have full permissions on the Kubernetes cluster.
+
+#### 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. Base images
+2. Charmed operator security upgrades
+3. Encryption
+4. Authentication
+5. Monitoring and auditing
+
+### Base images
+
+Charmed PostgreSQL K8s and Charmed PgBouncer K8s run on top of rockcraft-based images shipping the PostgreSQL and PgBouncer distribution binaries built by Canonical. These images (rocks) are available in a GitHub registry for [PostgreSQL](https://github.com/canonical/charmed-postgresql-rock/pkgs/container/charmed-postgresql) and [PgBouncer](https://github.com/orgs/canonical/packages/container/package/charmed-pgbouncer) respectively. Both images are based on Ubuntu 22.04.
+
+### Charmed operator security upgrades
+
+[Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s) operator and [Charmed PgBouncer K8s](https://charmhub.io/pgbouncer-k8s) operator install pinned versions of their respective rocks 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 K8s, see the [How to upgrade PostgreSQL K8s](https://canonical.com/data/docs/postgresql/k8s/h-upgrade) and [How to upgrade PgBouncer K8s](https://charmhub.io/pgbouncer-k8s/docs/h-upgrade) guides, as well as the respective Release notes for [PostgreSQL](https://canonical.com/data/docs/postgresql/k8s/r-releases) and [PgBouncer](https://charmhub.io/pgbouncer-k8s/docs/r-releases).
+
+### Encryption
+
+To utilise encryption at transit for all internal and external cluster connections, integrate Charmed PostgreSQL K8s and Charmed PgBouncer K8s 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 K8s is a client for an S3-compatible storage).
+
+For more information on encryption, see the [Cryptography](/t/charmed-postgresql-k8s-explanations-encryption/16851) explanation page and [How to enable encryption](https://canonical.com/data/docs/postgresql/k8s/h-enable-tls) guide.
+
+### Authentication
+
+Charmed PostgreSQL K8s 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 K8s 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/k8s/h-enable-monitoring), [alert rules](https://canonical.com/data/docs/postgresql/k8s/h-enable-alert-rules), and [tracing](https://canonical.com/data/docs/postgresql/k8s/h-enable-tracing) for practical instructions.
+
+PostgreSQL logs are stored in `/var/log/postgresql` within the postgresql container of each unit. It’s recommended to integrate the charm with [COS](https://canonical.com/data/docs/postgresql/k8s/h-enable-monitoring), 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 K8s, see the [Cryptography](/t/charmed-postgresql-k8s-explanations-encryption/16851) explanation page.

docs/explanation/e-users.md

@@ -1,10 +1,11 @@
 # Charm Users explanations
 
-There are two types of users in PostgreSQL:
+There are three types of users in PostgreSQL:
 
 * Internal users (used by charm operator)
-* Relation/integration users (used by related applications)
+* Relation users (used by related applications)
   * Extra user roles (if default permissions are not enough)
+* Identity users (used when LDAP is enabled)
 
 <a name="internal-users"></a>
 ## Internal users explanations:
@@ -75,7 +76,7 @@ unit-postgresql-1:
 **Note**: the action `set-password` must be executed on juju leader unit (to update peer relation data with new value).
 
 <a name="relation-users"></a>
-## Relation/integration users explanations:
+## Relation users explanations:
 
 The operator created a dedicated user for every application related/integrated with database. Those users are removed on the juju relation/integration removal request. However, DB data stays in place and can be reused on re-created relations (using new user credentials):
 
@@ -102,4 +103,10 @@ postgres=# \du
 
 When an application charm requests a new user through the relation/integration it can specify that the user should have the `admin` role in the `extra-user-roles` field. The `admin` role enables the new user to read and write to all databases (for the `postgres` system database it can only read data) and also to create and delete non-system databases.
 
-**Note**: `extra-user-roles` is supported by modern interface `postgresql_client` only and missing for legacy `pgsql` interface. Read more about the supported charm interfaces [here](/t/10252).
+**Note**: `extra-user-roles` is supported by modern interface `postgresql_client` only and missing for legacy `pgsql` interface. Read more about the supported charm interfaces [here](/t/10252).
+
+<a name="identity-users"></a>
+## Identity users explanations:
+The operator considers Identity users all those that are automatically created when the LDAP integration is enabled, or in other words, the [GLAuth](https://charmhub.io/glauth-k8s) charm is related/integrated.
+
+When synchronized from the LDAP server, these users do not have any permissions by default, so the LDAP group they belonged to must be mapped to a PostgreSQL pre-defined authorization role by using the `ldap_map` configuration option.

docs/how-to.md

@@ -4,15 +4,15 @@ The following guides cover key processes and common tasks for managing and using
 
 ## Deployment and setup
 
-The following guides walk you through the details of how to install different cloud services and bootstrap them to Juju:
+Installation of different cloud services with Juju:
 * [Canonical K8s]
 * [MicroK8s]
 * [GKE]
 * [EKS]
 * [AKS]
 * [Multi-availability zones (AZ)][Multi-AZ]
 
-The following guides cover some specific deployment scenarios and architectures:
+Other deployment scenarios and configurations:
 * [Terraform]
 * [Air-gapped]
 
@@ -22,6 +22,7 @@ The following guides cover some specific deployment scenarios and architectures:
 * [External access]
 * [Scale replicas]
 * [Enable TLS]
+* [Enable LDAP]
 * [Enable plugins/extensions]
 
 ## Backup and restore
@@ -34,9 +35,9 @@ The following guides cover some specific deployment scenarios and architectures:
 
 ## Monitoring (COS)
 
-* [Enable monitoring]
-* [Enable alert rules]
-* [Enable tracing]
+* [Enable monitoring] with Grafana
+* [Enable alert rules] with Prometheus
+* [Enable tracing] with Parca
 
 ## Minor upgrades
 * [Perform a minor upgrade]
@@ -52,7 +53,7 @@ The following guides cover some specific deployment scenarios and architectures:
 
 ## Development
 
-This section is aimed at charm developers looking to support PostgreSQL integrations with their charm.
+This section is for charm developers looking to support PostgreSQL integrations with their charm.
 
 * [Integrate with your charm]
 * [Migrate data via pg_dump]
@@ -73,6 +74,7 @@ This section is aimed at charm developers looking to support PostgreSQL integrat
 [External access]: /t/15701
 [Scale replicas]: /t/9592
 [Enable TLS]: /t/9593
+[Enable LDAP]: /t/17189
 [Enable plugins/extensions]: /t/10907
 
 [Configure S3 AWS]: /t/9595

docs/how-to/h-async-set-up.md

@@ -62,7 +62,7 @@ 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
+juju run -m lisbon db2/leader promote-to-primary scope=cluster
 ```
 
 ## Scale a cluster

docs/how-to/h-deploy-canonical-k8s.md

@@ -42,7 +42,7 @@ kubectl get namespaces # to test the credentials
 
 Install Juju and bootstrap the first Juju controller in K8s:
 ```shell
-sudo snap install juju --channel 3.6/candidate
+sudo snap install juju --channel 3.6/stable
 juju add-k8s ck8s --client --context-name="k8s"
 juju bootstrap ck8s
 ```

docs/how-to/h-deploy.md

@@ -25,7 +25,7 @@ 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/).
+To deploy with `terraform juju`, follow the guide [How to deploy using Terraform].
 > 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].
@@ -40,9 +40,9 @@ The guides below go through the steps to install different cloud services and bo
 
 [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
+## Special deployment scenarios
 
-These guides cover some specific deployment scenarios and architectures.
+These guides cover some specific deployment scenarios and configurations.
 
 ### External network access 
 
@@ -67,7 +67,6 @@ The [Cross-regional async replication] guide goes through the steps to set up cl
 
 [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