Sync docs from Discourse

Author: github-actions[bot]

Diff for: 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.

Diff for: 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.

Diff for: 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/)
 

Diff for: 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 `[email protected]`.
+[/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 `[email protected]`, 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 `[email protected]`, 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)

Diff for: 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
 ```

Diff for: 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) |

Diff for: docs/tutorial/t-enable-tls.md

@@ -55,7 +55,7 @@ Machine  State    Address       Inst id        Series  AZ  Message
 
 To enable TLS on Charmed PostgreSQL VM, integrate the two applications:
 ```shell
-juju integrate postgresql self-signed-certificates
+juju integrate postgresql:certificates self-signed-certificates:certificates
 ```
 PostgreSQL is now using TLS certificate generated by the `self-signed-certificates` charm.
 
@@ -72,7 +72,7 @@ verify error:num=19:self-signed certificate in certificate chain
 <a href="#heading--remove-tls"><h2 id="heading--remove-tls"> Remove TLS certificate</h2></a> 
 To remove the external TLS, remove the integration:
 ```shell
-juju remove-relation postgresql self-signed-certificates
+juju remove-relation postgresql:certificates self-signed-certificates:certificates
 ```
 
 If you once again check the TLS certificates in use via the OpenSSL client, you will see something similar to the output below:

Diff for: docs/tutorial/t-set-up.md

@@ -1,4 +1,4 @@
-> [Charmed PostgreSQL K8s Tutorial](/t/9707) >  1. Set up the environment
+> [Charmed PostgreSQL VM Tutorial](/t/9707) >  1. Set up the environment
 
 # Set up the environment