'new: docs/how-to/h-upgrade/h-rollback-minor.md,docs/how-to/h-setup/h…

…-deploy-microk8s.md,docs/reference/r-releases-group/r-releases.md,docs/how-to/h-enable-monitoring.md,docs/explanation/e-interfaces.md,docs/how-to/h-upgrade/h-upgrade-minor.md,docs/how-to/h-upgrade/h-upgrade-major.md,docs/how-to/h-upgrade/h-rollback-major.md,docs/reference/r-releases-group/r-releases-rev144.md,docs/tutorial/t-managing-units.md,docs/tutorial/t-overview.md,docs/reference/r-releases-group/r-releases-rev81.md,docs/explanation/e-juju-details.md,docs/reference/r-releases-group/r-releases-rev103.md,docs/tutorial/t-cleanup-environment.md,docs/tutorial/t-setup-environment.md,docs/reference/r-requirements.md,docs/reference/r-testing.md,docs/how-to/h-setup/h-manage-units.md,docs/how-to/h-upgrade/h-upgrade-intro.md,docs/index.md,docs/reference/r-releases-group/r-releases-rev76.md,docs/tutorial/t-deploy-charm.md,docs/tutorial/t-enable-security.md,docs/reference/r-contacts.md,docs/how-to/h-setup/h-manage-app.md,docs/how-to/h-setup/h-enable-encryption.md,docs/explanation/e-statuses.md' (#336)

Co-authored-by: discourse-gatekeeper-docs-bot <discourse-gatekeeper-bot@users.noreply.github.com>

docs/explanation/e-interfaces.md

@@ -0,0 +1,31 @@
+# Interfaces/endpoints
+
+PgBouncer K8s supports modern ['postgresql_client'](https://github.com/canonical/charm-relation-interfaces) interface. Applications can easily connect PgBouncer using ['data_interfaces'](https://charmhub.io/data-platform-libs/libraries/data_interfaces) library from ['data-platform-libs'](https://github.com/canonical/data-platform-libs/).
+
+### Modern `postgresql_client` interface (`database` endpoint):
+
+Adding a relation is accomplished with `juju relate` (or `juju integrate` for Juju 3.x) via endpoint `database`. Read more about [Juju relations (integrations)](https://juju.is/docs/olm/relations). Example:
+
+```shell
+# Deploy Charmed PostgreSQL K8s and PgBouncer K8s clusters with 3 nodes each
+juju deploy postgresql-k8s -n 3 --trust --channel 14/stable
+juju deploy pgbouncer-k8s -n 3 --trust --channel 1/stable
+
+# Deploy the relevant charms, e.g. postgresql-test-app
+juju deploy postgresql-test-app
+
+# Relate all applications
+juju integrate postgresql-k8s pgbouncer-k8s
+juju integrate pgbouncer-k8s postgresql-test-app:first-database
+
+# Check established relation (using postgresql_client interface):
+juju status --relations
+
+# Example of the properly established relation:
+# > Integration provider         Requirer                              Interface              Type     Message
+# > pgbouncer-k8s:database       postgresql-test-app:first-database    postgresql_client      regular  
+# > postgresql-k8s:database      pgbouncer-k8s:backend-database        postgresql_client      regular  
+# > ...
+```
+
+See all the charm interfaces [here](https://charmhub.io/pgbouncer-k8s/integrations).

docs/explanation/e-juju-details.md

@@ -0,0 +1,43 @@
+# Juju tech details
+
+[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/pgbouncer-k8s) 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 Documentation](https://juju.is/docs/juju) and [Blog](https://ubuntu.com/blog/tag/juju)
+* [Charm SDK](https://juju.is/docs/sdk)
+
+## 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:
+
+|2.9.x|3.x|
+| --- | --- |
+|**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:
+
+### Juju 3.x:
+```shell
+juju integrate pgbouncer-k8s:database postgresql-test-app
+
+juju run postgresql-k8s/leader get-password 
+```
+### Juju 2.9.x:
+```shell
+juju relate pgbouncer-k8s:database postgresql-test-app
+
+juju run-action --wait postgresql-k8s/leader get-password
+```
+> :tipping_hand_man: [The document based on OpenStack guide.](https://docs.openstack.org/charm-guide/latest/project/support-notes.html#breaking-changes-between-juju-2-9-x-and-3-x)

docs/explanation/e-statuses.md

@@ -0,0 +1,16 @@
+# Charm Statuses
+
+> :warning: **WARNING** : it is an work-in-progress article. Do NOT use it in production! Contact [Canonical Data Platform team](https://chat.charmhub.io/charmhub/channels/data-platform) if you are interested in the topic.
+
+The charm follows [standard Juju applications statuses](https://juju.is/docs/olm/status-values#heading--application-status). Here you can find the expected end-users reaction on different statuses:
+
+| Juju Status | Message | Expectations | Actions |
+|-------|-------|-------|-------|
+| **active** | any | Normal charm operations | No actions required |
+| **waiting** | any | Charm is waiting for relations to be finished | No actions required |
+| **maintenance** | any | Charm is performing the internal maintenance (e.g. re-configuration) | No actions required |
+| **blocked** | any | The manual user activity is required! | Follow the message hints (see below) |
+| **blocked** | waiting for backend database relation to initialise  | Normal behavior, charm needs all relations to work. | Follow the hint to establish a proper relation. |
+| **error** | any | An unhanded internal error happened | Read the message hint. Execute `juju resolve <error_unit/0>` after addressing the root of the error state |
+| **terminated** | any | The unit is gone and will be cleaned by Juju soon | No actions possible |
+| **unknown** | any | Juju doesn't know the charm app/unit status. Possible reason: K8s charm termination in progress. | Manual investigation required if status is permanent |

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

@@ -0,0 +1,93 @@
+# How to enable monitoring
+
+Enable monitoring requires that you:
+* [Have a PgBouncer K8s deployed](/t/12253)
+* [Deploy `cos-lite` bundle in a Kubernetes environment](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)
+* [COS configured for Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s/docs/h-enable-monitoring)
+
+Switch to COS K8s environment and offer COS interfaces to be cross-model related with PgBouncer K8s model:
+```shell
+# Switch to Kubernetes controller, for the cos model.
+juju switch <k8s_cos_controller>:<cos_model_name>
+
+juju offer grafana:grafana-dashboard
+juju offer loki:logging
+juju offer prometheus:receive-remote-write
+```
+
+Switch to PgBouncer K8s model, find offers and consume them:
+```shell
+# We are on the Kubernetes controller, for the cos model. Switch to postgresql model
+juju switch <k8s_db_controller>:<postgresql_model_name>
+
+juju find-offers <k8s_cos_controller>: # Do not miss ':' here!
+```
+
+A similar output should appear, if `k8s` is the k8s controller name and `cos` the model where `cos-lite` has been deployed:
+```shell
+Store  URL                    Access  Interfaces
+k8s    admin/cos:grafana      admin   grafana:grafana-dashboard
+k8s    admin/cos.loki         admin   loki:logging
+k8s    admin/cos.prometheus   admin   prometheus:receive-remote-write
+...
+```
+
+Consume offers to be reachable in the current model:
+```shell
+juju consume <k8s_cos_controller>:admin/cos.grafana
+juju consume <k8s_cos_controller>:admin/cos.loki
+juju consume <k8s_cos_controller>:admin/cos.prometheus
+```
+
+Now, deploy '[grafana-agent-k8s](https://charmhub.io/grafana-agent-k8s)' (as `pgbouncer-cos-agent`) and integrate (relate) it with PgBouncer K8s, later integrate (relate) `pgbouncer-cos-agent` with consumed COS offers:
+```shell
+juju deploy grafana-agent-k8s pgbouncer-cos-agent --trust
+
+juju relate pgbouncer-cos-agent grafana
+juju relate pgbouncer-cos-agent loki
+juju relate pgbouncer-cos-agent prometheus
+
+juju relate pgbouncer-cos-agent pgbouncer-k8s:grafana-dashboard
+juju relate pgbouncer-cos-agent pgbouncer-k8s:logging
+juju relate pgbouncer-cos-agent pgbouncer-k8s:metrics-endpoint
+```
+
+After this is complete, Grafana will show the new dashboards: `PgBouncer Exporter` and allows access for PgBouncer logs on Loki.
+
+The example of `juju status` for Charmed PostgreSQL K8s + PgBouncer K8s model:
+```shell
+TODO
+```
+
+The example of `juju status` on COS K8s model:
+```shell
+Model  Controller  Cloud/Region        Version  SLA          Timestamp
+cos    microk8s    microk8s/localhost  3.1.6    unsupported  00:21:19+02:00
+
+App           Version  Status  Scale  Charm             Channel  Rev  Address         Exposed  Message
+alertmanager  0.25.0   active      1  alertmanager-k8s  edge      91  10.152.183.215  no       
+catalogue              active      1  catalogue-k8s     edge      27  10.152.183.187  no       
+grafana       9.2.1    active      1  grafana-k8s       edge      92  10.152.183.95   no       
+loki          2.7.4    active      1  loki-k8s          edge      99  10.152.183.28   no       
+prometheus    2.46.0   active      1  prometheus-k8s    edge     149  10.152.183.232  no       
+traefik       2.10.4   active      1  traefik-k8s       edge     155  10.76.203.228   no       
+
+Unit             Workload  Agent  Address       Ports  Message
+alertmanager/0*  active    idle   10.1.142.186         
+catalogue/0*     active    idle   10.1.142.176         
+grafana/0*       active    idle   10.1.142.189         
+loki/0*          active    idle   10.1.142.187         
+prometheus/0*    active    idle   10.1.142.188         
+traefik/0*       active    idle   10.1.142.185         
+
+Offer       Application  Charm           Rev  Connected  Endpoint              Interface                Role
+grafana     grafana      grafana-k8s     92   1/1        grafana-dashboard     grafana_dashboard        requirer
+loki        loki         loki-k8s        99   1/1        logging               loki_push_api            provider
+prometheus  prometheus   prometheus-k8s  149  1/1        receive-remote-write  prometheus_remote_write  provider
+
+```
+
+To connect Grafana WEB interface, follow the COS section "[Browse dashboards](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)":
+```shell
+juju run grafana/leader get-admin-password --model <k8s_cos_controller>:<cos_model_name>
+```

docs/how-to/h-setup/h-deploy-microk8s.md

@@ -0,0 +1,35 @@
+# Deploy PgBouncer K8s
+
+Please follow the [PgBouncer K8s Tutorial](/t/12251) for technical details and explanations.
+
+Short story for your Ubuntu 22.04 LTS:
+```shell
+sudo snap install multipass
+multipass launch --cpus 4 --memory 8G --disk 30G --name my-vm charm-dev # tune CPU/RAM/HDD accordingly to your needs
+multipass shell my-vm
+
+juju add-model demo
+juju deploy postgresql-k8s --channel 14/stable --trust # --config profile=testing
+juju deploy pgbouncer-k8s --channel 1/stable --trust
+
+juju integrate postgresql-k8s pgbouncer-k8s
+
+juju status --watch 1s
+```
+
+The expected result:
+```shell 
+Model  Controller  Cloud/Region        Version  SLA          Timestamp
+demo   microk8s    microk8s/localhost  3.1.6    unsupported  22:42:26+02:00
+
+App             Version  Status  Scale  Charm           Channel    Rev  Address         Exposed  Message
+pgbouncer-k8s   1.18.0   active      1  pgbouncer-k8s   1/stable    76  10.152.183.128  no       backend-database relation initialised.
+postgresql-k8s  14.9     active      1  postgresql-k8s  14/stable  158  10.152.183.110  no       
+
+Unit               Workload  Agent      Address     Ports  Message
+pgbouncer-k8s/0*   active    executing  10.1.12.36         backend-database relation initialised.
+postgresql-k8s/0*  active    idle       10.1.12.22
+```
+The charm PgBouncer K8s is now waiting for relations with a client application, e.g. [postgresql-test-app](https://charmhub.io/postgresql-test-app), [mattermost](https://charmhub.io/mattermost-k8s), ...
+
+Check the [Testing](/t/12272) reference to test your deployment.

docs/how-to/h-setup/h-enable-encryption.md

@@ -0,0 +1,52 @@
+# How to enable encryption
+
+PgBouncer will enable encrypted connections by default with self generated certificates. Though also by default, connecting clients can disable encryption by setting the connection ssl-mode as disabled.
+When related with the `tls-certificates-operator` the charmed operator for PgBouncer will require that every client connection (new and running connections) use encryption, rendering an error when attempting to establish an unencrypted connection.
+
+> **Note**: The TLS settings here are for self-signed-certificates which are not recommended for production clusters, the `tls-certificates-operator` charm offers a variety of configurations, read more on the TLS charm [here](https://charmhub.io/tls-certificates-operator)
+
+## Enable TLS
+
+```shell
+# deploy the TLS charm
+juju deploy tls-certificates-operator --channel legacy/stable
+
+# add the necessary configurations for TLS
+juju config tls-certificates-operator generate-self-signed-certificates="true" ca-common-name="Test CA"
+
+# to enable TLS relate the two applications
+juju relate tls-certificates-operator pgbouncer-k8s
+```
+
+## Manage keys
+
+Updates to private keys for certificate signing requests (CSR) can be made via the `set-tls-private-key` action. Note passing keys to external/internal keys should *only be done with* `base64 -w0` *not* `cat`. With three routers this schema should be followed:
+
+* Generate a shared internal (private) key:
+
+```shell
+openssl genrsa -out internal-key.pem 3072
+```
+
+* apply newly generated internal key on each unit:
+
+```
+juju run pgbouncer-k8s/0 set-tls-private-key "internal-key=$(base64 -w0 internal-key.pem)"
+juju run pgbouncer-k8s/1 set-tls-private-key "internal-key=$(base64 -w0 internal-key.pem)"
+juju run pgbouncer-k8s/2 set-tls-private-key "internal-key=$(base64 -w0 internal-key.pem)"
+```
+
+* updates can also be done with auto-generated keys with:
+
+```
+juju run pgbouncer-k8s/0 set-tls-private-key
+juju run pgbouncer-k8s/1 set-tls-private-key
+juju run pgbouncer-k8s/2 set-tls-private-key
+```
+
+## Disable TLS
+
+To disable TLS, remove the relation:
+```shell
+juju remove-relation tls-certificates-operator pgbouncer-k8s
+```

docs/how-to/h-setup/h-manage-app.md

@@ -0,0 +1,42 @@
+# How to manage related applications
+
+## Modern `postgresql_client` interface:
+
+Relations to new applications are supported via the "[postgresql_client](https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/postgresql_client/v0/README.md)" interface. To create a relation:
+
+```shell
+juju integrate pgbouncer-k8s application
+```
+
+To remove a relation:
+
+```shell
+juju remove-relation pgbouncer-k8s application
+```
+
+All listed on CharmHub applications are available [here](https://charmhub.io/pgbouncer-k8s/integrations), e.g.:
+ * [postgresql-test-app](https://charmhub.io/postgresql-test-app)
+ * [mattermost-k8s](https://charmhub.io/mattermost-k8s)
+
+## Legacy `pgsql` interface:
+
+This charm also supports the legacy relation via the `pgsql` interface. Please note that these interface is deprecated.
+
+ ```shell
+juju relate pgbouncer-k8s:db myapplication-k8s
+```
+
+Also extended permissions can be requested using `db-admin` endpoint:
+```shell
+juju relate pgbouncer-k8s:db-admin myapplication-k8s
+```
+
+## Internal operator user
+
+To rotate the internal router passwords, the relation with backend-database should be removed and related again. That process will generate a new user and password for the application, while retaining the requested database and data.
+
+```shell
+juju remove-relation postgresql-k8s pgbouncer-k8s
+
+juju integrate postgresql-k8s pgbouncer-k8s
+```

docs/how-to/h-setup/h-manage-units.md

@@ -0,0 +1,22 @@
+# How to deploy and manage units
+
+## Basic Usage
+
+To deploy a single unit of PgBouncer using its default configuration
+```shell
+juju deploy pgbouncer-k8s --trust --channel 1/stable
+```
+
+It is customary to use PgBouncer in HA setup. Hence usually more than one unit (preferably an odd number to prohibit a "split-brain" scenario) is deployed. To deploy PgBOuncer in HA mode, specify the number of desired units with the `-n` option.
+```shell
+juju deploy pgbouncer-k8s --trust --channel 1/stable -n <number_of_replicas>
+```
+
+## Scaling
+
+Both scaling-up and scaling-down operations are performed using `juju scale-application`:
+```shell
+juju scale-application pgbouncer-k8s <desired_num_of_units>
+```
+
+> :tipping_hand_man: **Tip**: scaling-down to zero units is supported to safe K8s resources!

docs/how-to/h-upgrade/h-rollback-major.md

@@ -0,0 +1,5 @@
+# Major Rollback
+
+> :information_source: **Example**: PgBouncer 2 -> PgBouncer 1
+
+Currently, the charm supports PgBouncer major version 1 only; therefore, minor rollbacks are only possible. Canonical is NOT planning to support in-place rollbacks for the major PgBouncer version change as the old PostgreSQL cluster with the old PgBouncer installation will stay nearby and can be reused for the rollback.