Sync docs from Discourse

Author: github-actions[bot]

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/h-enable-profiling.md

@@ -0,0 +1,118 @@
+[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]
+
+Please read this doc in its entirety before deploying anything. In particular, please decide what Parca backend you would like to use. You can either deploy Charmed Parca K8s or use Polar Signals Cloud.
+
+# Enable Profiling
+
+This guide contains the steps to enable profiling with [Parca](https://www.parca.dev/docs/overview/) for your PostgreSQL application.
+
+To summarize:
+* [Deploy Charmed PostgreSQL](#heading--deploy)
+* [Optional: Deploy the COS-lite bundle and Charmed Parca K8s + Offer interfaces for cross-model integrations](#heading--cos)
+* [Deploy Charmed Parca Agent and integrate with Charmed PostgreSQL](#heading--parcaagent)
+* [Integrate Charmed Parca Agent with the Parca Backend](#heading--parcabackend)
+* [View PostgreSQL machine profiles](#heading--view)
+
+<a href="#heading--deploy"><h2 id="heading--deploy"> Deploy Charmed PostgreSQL </h2></a>
+
+See [How to scale units](https://discourse.charmhub.io/t/charmed-postgresql-how-to-scale-units/9689) for reference of how you can deploy Charmed PostgreSQL in a machine model.
+
+[note]
+**Note**: 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, e.g. `juju deploy postgresql --constraints="virt-type=virtual-machine"`. 
+[/note]
+
+[note]
+**Note:** Please note the base of the Charmed PostgreSQL application.
+
+Nothing needs to be done if the base is `ubuntu@24.04` which already loads the kernel symbol table for debugging by default.
+
+If your base is `ubuntu@22.04`, you will need to ensure that your are using the `generic` flavor (see output of `uname -r` to confirm) of Linux. 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
+# only run the following if your application is deployed in an LXD model
+# rm /etc/default/grub.d/40-force-partuuid.cfg
+
+# Then open the /etc/default/grub file 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
+
+sudo update-grub
+sudo reboot
+```
+[/note]
+
+<a href="#heading--cos"><h2 id="heading--cos"> Optional: Deploy the COS-lite bundle and Charmed Parca K8s + Offer interfaces for cross-model integrations </h2></a>
+
+Please 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, please 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.
+
+Next, offer interfaces for cross-model integrations from the model where Charmed PostgreSQL is deployed.
+
+```
+juju offer <parca_k8s_application_name>:parca-store-endpoint
+```
+
+<a href="#heading--parcaagent"><h2 id="heading--parcaagent"> Deploy Charmed Parca Agent and Integrate with Charmed PostgreSQL </h2></a>
+
+Switch to the Charmed PostgreSQL model, then deploy Charmed Parca Agent and relate with Charmed PostgreSQL:
+
+```
+juju switch <machine_controller_name>:<postgresql_model_name>
+
+juju deploy parca-agent --channel latest/edge
+juju integrate postgresql parca-agent
+```
+
+<a href="#heading--parcabackend"><h2 id="heading--parcabackend"> Integrate Charmed Parca Agent with the Parca backend </h2></a>
+
+### Integrating with Parca K8s in a K8s model
+
+If you deployed Charmed Parca K8s in a Kubernetes model, consume the parca offer from a previous section and integrate with them:
+
+```
+juju switch <machine_controller_name>:<postgresql_model_name>
+
+juju find-offers <k8s_controller_name>:
+```
+
+> :exclamatin: Do not miss the ":" 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 model. Then relate Charmed Parca Agent with the consumed offer endpoint:
+
+```
+juju consume k8s:admin/cos.parca
+
+juju integrate parca-agent parca 
+```
+
+### Integrating with Polar Signals Cloud
+
+Please refer to [How to integrate with Polar Signals Cloud](https://discourse.charmhub.io/t/charmed-parca-docs-how-to-integrate-with-polar-signals-cloud/16559). We recommend configuring `parca-agent` to forward profiles to the cloud instance instead of configuring `parca-k8s` server to forward profiles to the cloud instance. This would entail deploying the `polar-signals-cloud-integrator` in the same model as Charmed PostgreSQL.
+
+<a href="#heading--view"><h2 id="heading--view"> View Profiles </h2></a>
+
+After this 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/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) |

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:

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