Sync docs from Discourse

docs/explanation.md

@@ -1,14 +1,22 @@
 # Explanation
 
-This section contains pages with more detailed explanations that provide additional context about some of the key concepts behind the PostgreSQL charm:
+This section contains pages with more detailed explanations that provide additional context about key concepts behind the PostgreSQL charm.
 
+## Core concepts and design
 * [Architecture]
 * [Interfaces and endpoints]
+* [Juju]
+* [Legacy charm]
+
+## Operational concepts
 * [Connection pooling]
 * [Users]
 * [Logs]
-* [Juju]
-* [Legacy charm]
+
+## Security and hardening
+* [Security hardening guide][Security]
+  * [Cryptography]
+
 
 <!-- Links -->
 
@@ -18,4 +26,6 @@ This section contains pages with more detailed explanations that provide additio
 [Logs]: /t/12099
 [Juju]: /t/11985
 [Legacy charm]: /t/10690
-[Connection pooling]: /t/15777
+[Connection pooling]: /t/15777
+[Security]: /t/16852
+[Cryptography]: /t/16853

docs/explanation/e-architecture.md

@@ -75,6 +75,10 @@ The snap "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 only available for Kubernetes clouds, under the [GLAuth-K8s operator](https://charmhub.io/glauth-k8s) page, so a cross-controller relation is needed in order to integrate both charms.
+
 ### 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/10600) setup.

docs/explanation/e-users.md

@@ -1,9 +1,10 @@
 # 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:
@@ -72,7 +73,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):
 
@@ -99,4 +100,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/10251).
+**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/10251).
+
+<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,7 +4,7 @@ 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:
 * [Sunbeam]
 * [LXD]
 * [MAAS]
@@ -13,7 +13,7 @@ The following guides walk you through the details of how to install different cl
 * [Azure]
 * [Multi-availability zones (AZ)][Multi-AZ]
 
-The following guides cover some specific deployment scenarios and architectures:
+Specific deployment scenarios and architectures:
 * [Terraform]
 * [Air-gapped]
 * [TLS VIP access]
@@ -54,7 +54,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]

docs/how-to/h-deploy.md

@@ -21,7 +21,7 @@ Then, either continue with the `juju` client **or** use the `terraform juju` cli
 
 To deploy with the `juju` client:
 ```shell
-juju deploy postgresql
+juju deploy postgresql -n <number_of_replicas>
 ```
 > See also: [`juju deploy` command](https://canonical-juju.readthedocs-hosted.com/en/latest/user/reference/juju-cli/list-of-juju-cli-commands/deploy/)
 

docs/how-to/h-enable-profiling.md

@@ -0,0 +1,174 @@
+[note]
+**Note**: All commands are written for `juju >= v3.1`
+
+If you're using `juju 2.9`, check the [`juju 3.0` Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
+[/note]
+
+# Enable profiling with Parca
+
+This guide contains the steps to enable profiling with [Parca](https://www.parca.dev/docs/overview/) for your PostgreSQL application. 
+
+## Summary
+* [Prerequisites](#prerequisites)
+* [Set up the Parca backend](#set-up-the-parca-backend)
+  * [Charmed Parca K8s](#charmed-parca-k8s)
+  * [Polar Signals Cloud](#polar-signals-cloud)
+* [View profiles](#view-profiles)
+
+---
+
+## Prerequisites
+
+[note type=caution]
+**Do not skip this section** if you are deploying PostgreSQL in an LXD model or if your base is `ubuntu@22.04`.
+[/note]
+
+
+This guide assumes you already have a juju model with Charmed PostgreSQL deployed.
+
+> See: [How to deploy PostgreSQL](/t/16811)
+
+In order for your Charmed PostgreSQL deployment to be correctly set up for integration with Parca, there are two important considerations: 
+* [LXD virtualization type](#lxd-virtualization-type)
+* [Base (Ubuntu version)](#base-ubuntu-version)
+
+### LXD virtualization type
+
+**If you are deploying Charmed PostgreSQL in a LXD model, you will need to ensure that LXD's virtualization type is set to `virtual-machine` for the Juju application.**
+
+This is because LXD does not allow `/sys/kernel/tracing` to be mounted in a system container (even in privileged mode) due to security isolation concerns. 
+
+To ensure that a virtual machine is used instead of a system container, you would need to add constraints, for example:
+```
+juju deploy postgresql --constraints="virt-type=virtual-machine"`. 
+```
+
+### Base (Ubuntu version)
+**If your base is `ubuntu@22.04`, you will need to ensure that your are using the `generic` flavor of Linux.**
+>  See the output of `uname -r` to confirm. 
+
+If you do not have the `generic` flavor, you can enable it on a unit to be profiled as follows:
+
+```
+juju ssh postgresql/0 bash
+sudo apt-get update && sudo apt-get install linux-image-virtual
+sudo apt-get autopurge linux-image-kvm
+```
+
+If your application is deployed in an LXD model, run the following command:
+```
+rm /etc/default/grub.d/40-force-partuuid.cfg
+```
+
+Open the `/etc/default/grub` file  with your editor of choice and replace the line that starts with `GRUB_DEFAULT=` with:
+```
+release=$(linux-version list | grep -e '-generic$' | sort -V | tail -n1)
+GRUB_DEFAULT="Advanced options for Ubuntu>Ubuntu, with Linux $release"
+```
+
+Exit out of the `/etc/default/grub file`, update GRUB, and reboot:
+```
+sudo update-grub
+sudo reboot
+```
+
+Nothing needs to be done if the base is `ubuntu@24.04`, which already loads the kernel symbol table for debugging by default.
+
+## Set up the Parca backend
+
+There are two potential backends:
+* [Charmed Parca K8s](#charmed-parca-k8s) (requires COS and cross-model integrations)
+* [Polar Signals Cloud](#polar-signals-cloud) (COS is optional)
+
+### Charmed Parca K8s
+
+This section goes through the steps for enabling profiling with Charmed Parca K8s as the backend.
+
+#### 1. Deploy `cos-lite` and `parca-k8s`
+
+Refer to [Getting started on MicroK8s](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s) and deploy the `cos-lite` bundle from the `latest/edge` track in a Kubernetes environment.
+
+Then, refer to [Deploy Charmed Parca on top of COS-lite](https://discourse.charmhub.io/t/how-to-deploy-charmed-parca-on-top-of-cos-lite/16579) to deploy Charmed Parca K8s in the same model as the `cos-lite` bundle.
+
+#### 2. Offer interfaces
+
+Offer interfaces for cross-model integrations:
+
+```
+juju offer <parca_k8s_application_name>:parca-store-endpoint
+```
+
+#### 3. Deploy and integrate `parca-agent` with `postgresql`
+
+Switch to the model containing the Charmed PostgreSQL deployment, deploy Charmed Parca Agent, and integrate it with Charmed PostgreSQL:
+
+```
+juju switch <machine_controller_name>:<postgresql_model_name>
+
+juju deploy parca-agent --channel latest/edge
+juju integrate postgresql parca-agent
+```
+
+#### 4. Integrate `parca-agent` with `parca-k8s`
+
+Consume the parca offer from [Step 2](#2-offer-interfaces) and integrate with them:
+
+```
+juju find-offers <k8s_controller_name>:
+```
+
+> :exclamation: Do not miss the colon "`:`" in the command above.
+
+Below is a sample output where `k8s` is the K8s controller name and `cos` is the model where `cos-lite` and `parca-k8s` are deployed:
+
+```
+Store  URL                            Access  Interfaces
+k8s    admin/cos.parca                admin   parca_store:parca-store-endpoint
+```
+
+Next, consume this offer so that is reachable from the current machine model: 
+
+```
+juju consume k8s:admin/cos.parca
+```
+
+Finally, relate Charmed Parca Agent with the consumed offer endpoint:
+```
+juju integrate parca-agent parca 
+```
+
+### Polar Signals Cloud
+
+This section goes through the steps for enabling profiling with Polar Signals Cloud (PSC) as the backend. 
+
+[note]
+With PSC, `cos-lite` and `parca-k8s` are not required. This section goes through the recommended setup, where `polar-signals-cloud-integrator` is deployed in the same model as `postgresql`, and `parca-agent` is used to relay traffic to PSC.
+
+If you would like to use `parca-k8s` to relay traffic to PSC instead, refer to [Steps 1 and 2](#1-deploy-cos-lite-and-parca-k8s) in the Charmed Parca K8s section.
+[/note]
+
+#### 1. Deploy and integrate `parca-agent` with `postgresql`
+
+In the machine model where PostgreSQL is deployed, deploy `parca-agent` and integrate it with `postgresql`:
+
+```
+juju deploy parca-agent --channel latest/edge
+juju integrate postgresql parca-agent
+```
+
+#### 2. Integrate `parca-agent` with `polar-signals-cloud-integrator`
+
+Follow the guide [How to integrate with Polar Signals Cloud](https://discourse.charmhub.io/t/charmed-parca-docs-how-to-integrate-with-polar-signals-cloud/16559).
+
+
+## View profiles 
+
+After the backend setup is complete, the profiles for the machines where the PostgreSQL units are running will be accessible from the Parca web interface. 
+
+If you are running Charmed Parca K8s, you can also access the link for Parca's web interface from COS catalogue (`juju run traefik/0 show-proxied-endpoints` in the K8s model where `cos-lite` is deployed).
+
+![Example profile with Parca Web UI690x753](upload://zFOOKY8nokrg2Q4xUVTbD8UGjD3.png)
+
+Furthermore, if you have `cos-lite` deployed, you can use Grafana to explore profiles under the `Explore` section with `parca-k8s` as the data source.
+
+![Example profile with Grafana's Parca plugin|690x383](upload://w3G5STYOxMZHCpIA48gEJHUniLi.jpeg)

docs/how-to/h-enable-tls.md

@@ -32,15 +32,9 @@ First, deploy the TLS charm:
 juju deploy self-signed-certificates
 ```
 
-To enable TLS on `postgresql`, integrate the two applications:
+To enable TLS integrate (formerly known as “relate”) the two applications:
 ```shell
-juju integrate self-signed-certificates postgresql
-```
-
-## Disable TLS
-Disable TLS by removing the integration.
-```shell
-juju remove-relation self-signed-certificates postgresql
+juju integrate postgresql:certificates self-signed-certificates:certificates
 ```
 
 ## Check certificates in use
@@ -79,4 +73,10 @@ Updates can also be done with auto-generated keys:
 juju run postgresql/0 set-tls-private-key
 juju run postgresql/1 set-tls-private-key
 juju run postgresql/2 set-tls-private-key
+```
+
+## Disable TLS
+Disable TLS by removing the integration.
+```shell
+juju remove-relation postgresql:certificates self-signed-certificates:certificates
 ```

docs/how-to/h-external-access.md

@@ -8,7 +8,7 @@ This page summarizes resources for setting up deployments where an external appl
 
 There are many possible ways to connect the Charmed PostgreSQL database from outside of the LAN where the database cluster is located. The available options are heavily dependent on the cloud/hardware/virtualization in use. 
 
-One of the possible options is to use [virtual IP addresses (VIP)](https://en.wikipedia.org/wiki/Virtual_IP_address) which the charm PgBouncer provides with assistance from the charm/interface `hacluster`. Please follow the [PgBouncer documentation](https://charmhub.io/pgbouncer/docs/h-external-access?channel=1/stable) for such configuration.
+One of the possible options is to use [virtual IP addresses (VIP)](https://en.wikipedia.org/wiki/Virtual_IP_address) which the charm PgBouncer provides with assistance from the charm/interface `hacluster`. Please follow the [PgBouncer documentation](https://charmhub.io/pgbouncer/docs/h-external-access) for such configuration.
 
 > See also: [How to deploy for external TLS VIP access](/t/16576).
 

docs/how-to/h-integrate.md

@@ -25,7 +25,9 @@ This guide shows how to integrate Charmed PostgreSQL with both charmed and non-c
 
 Integrations with charmed applications are supported via the modern [`postgresql_client`](https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/postgresql_client/v0/README.md) interface, and the legacy `psql` interface from the [original version](https://launchpad.net/postgresql-charm) of the charm.
 
-> You can see which existing charms are compatible with PostgreSQL in the [Integrations](https://charmhub.io/postgresql/integrations) tab.
+[note]
+You can see which existing charms are compatible with PostgreSQL in the [Integrations](https://charmhub.io/postgresql/integrations) tab.
+[/note]
 
 ### Modern `postgresql_client` interface
 To integrate with a charmed application that supports the `postgresql_client` interface, run
@@ -41,7 +43,7 @@ juju remove-relation postgresql <charm>
 ### Legacy `pgsql` interface
 [note type="caution"]
 Note that this interface is **deprecated**.
-See more information in [Explanation > Legacy charm](/t/10690).
+See the [legacy charm explanation page](/t/10690).
 [/note]
 
 To integrate via the legacy interface, run

docs/overview.md

@@ -77,6 +77,7 @@ PostgreSQL is a trademark or registered trademark of PostgreSQL Global Developme
 | 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) |
+| 3 | h-enable-profiling | [Enable profiling](/t/17172) |
 | 2 | h-upgrade | [Upgrade](/t/12086) |
 | 3 | h-upgrade-minor | [Perform a minor upgrade](/t/12089) |
 | 3 | h-rollback-minor | [Perform a minor rollback](/t/12090) |
@@ -94,20 +95,21 @@ PostgreSQL is a trademark or registered trademark of PostgreSQL Global Developme
 | 2 | r-software-testing | [Software testing](/t/11773) |
 | 2 | r-performance | [Performance and resources](/t/11974) |
 | 2 | r-troubleshooting | [Troubleshooting](/t/11864) |
+| 3 | r-sos-report | [SOS report](/t/17228) |
 | 2 | r-plugins-extensions | [Plugins/extensions](/t/10946) |
 | 2 | r-alert-rules | [Alert rules](/t/15841) |
 | 2 | r-statuses | [Statuses](/t/10844) |
 | 2 | r-contacts | [Contacts](/t/11863) |
 | 1 | explanation | [Explanation](/t/16768) |
 | 2 | e-architecture | [Architecture](/t/11857) |
-| 2 | e-security | [Security](/t/16852) |
-| 2 | e-cryptography | [Cryptography](/t/16853) |
 | 2 | e-interfaces-endpoints | [Interfaces and endpoints](/t/10251) |
+| 2 | e-juju-details | [Juju](/t/11985) |
+| 2 | e-legacy-charm | [Legacy charm](/t/10690) |
 | 2 | e-connection-pooling| [Connection pooling](/t/15777) |
 | 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) |
+| 2 | e-security | [Security](/t/16852) |
+| 3 | e-cryptography | [Cryptography](/t/16853) |
 | 1 | search | [Search](https://canonical.com/data/docs/postgresql/iaas) |
 
 [/details]