Sync docs from Discourse (#439)

Co-authored-by: GitHub Actions <41898282+github-actions[bot]@users.noreply.github.com>
canonical · Feb 25, 2025 · 000f9c8 · 000f9c8
1 parent 5ad8f9f
commit 000f9c8
Show file tree

Hide file tree

Showing 16 changed files with 291 additions and 96 deletions.
diff --git a/docs/explanation.md b/docs/explanation.md
@@ -0,0 +1,14 @@
+# Explanation
+
+This section contains pages with more detailed explanations that provide additional context about some of the key concepts behind the PgBouncer charm:
+
+* [Juju]
+* [Interfaces/endpoints]
+* [Statuses]
+* [Legacy charm]
+
+<!-- Links -->
+[Juju]: /t/12302
+[Interfaces/endpoints]: /t/12304
+[Statuses]: /t/12303
+[Legacy charm]: /t/13944
diff --git a/docs/explanation/e-legacy-charm.md b/docs/explanation/e-legacy-charm.md
@@ -27,7 +27,9 @@ The legacy charm was a [**principal charm**](https://juju.is/docs/sdk/charm-taxo
 
 The legacy charm provided SQL endpoints `db` and `db-admin` (for the interface `pgsql`). The modern charm provides those old endpoints and a new endpoint `database` (for the interface `postgresql_client`). Read more details about the available endpoints and interfaces [here](https://charmhub.io/pgbouncer/docs/e-interfaces?channel=1/stable).
 
-Non-SQL legacy charm interfaces (e.g. `hacluster`, `pgbouncer-extra-config`, `nrpe-external-master`) are currently NOT supported by the modern charm. [Contact us](/t/12307) with your use cases for those interfaces!
+The interface `hacluster` [supported](/t/15741) on both legacy and modern charms.
+
+Non-SQL legacy charm interfaces (e.g. `pgbouncer-extra-config`, `nrpe-external-master`) are currently NOT supported by the modern charm. [Contact us](/t/12307) with your use cases for those interfaces!
 
 **Note**: Please choose one endpoint to use. No need to relate all of them simultaneously!
 

diff --git a/docs/how-to.md b/docs/how-to.md
@@ -0,0 +1,40 @@
+# How-to guides
+
+The following guides cover key processes and common tasks for managing and using Charmed PgBouncer on machines.
+
+## Deployment
+
+* [How to deploy][Deploy]
+
+## Usage and maintenance
+
+* [Manage units]
+* [Manage integrations]
+* [Enable TLS]
+* [External network access]
+
+## Monitoring (COS)
+
+* [Enable monitoring]
+* [Enable tracing]
+
+## Upgrades and rollbacks
+
+* [Upgrade]
+    * [Perform a minor upgrade]
+    * [Perform a minor rollback]
+
+<!-- Links -->
+
+[Deploy]: /t/12312
+[Manage units]: /t/12309
+[Enable TLS]: /t/12310
+[Manage integrations]: /t/12311
+[External network access]: /t/15741
+
+[Enable monitoring]: /t/12308
+[Enable tracing]: /t/14788
+
+[Upgrade]: /t/12313
+[Perform a minor upgrade]: /t/12317
+[Perform a minor rollback]: /t/12316
diff --git a/docs/how-to/h-external-access.md b/docs/how-to/h-external-access.md
@@ -1,8 +1,20 @@
-# Optimal PgBouncer Setup
+# How to connect from outside the local network
 
-For optimal performance, it is recommended that [PgBouncer](https://www.pgbouncer.org/) is run alongside your application. Co-locating PgBouncer with your application results in increased network performance since an additional network hop from your application to PgBouncer is avoided. Furthermore, it can also lead increased security since traffic is not routed externally through potentially untrusted machines. 
+This page goes over the set-up and operation of PgBouncer when an external application must connect to a PostgreSQL database from outside the local area network.
 
-When your application implements the modern (preferred) interface in  [PgBouncer's supported interfaces](https://discourse.charmhub.io/t/pgbouncer-how-to-manage-app/12311) , the PgBouncer charm is deployed as a subordinate of your application charm and your application.
+[note]
+For optimal performance, it is recommended that PgBouncer is run alongside your application, as it avoids an additional network hop from your application to PgBouncer. 
+
+This also increases security, since traffic is not routed externally through potentially untrusted machines.
+[/note]
+
+<!--When your application implements the modern (preferred) interface in  [PgBouncer's supported interfaces](https://discourse.charmhub.io/t/pgbouncer-how-to-manage-app/12311), the PgBouncer charm is deployed as a subordinate of your application charm and your application.-->
+
+## Summary
+* [Accessing PgBouncer outside of Juju](#accessing-pgbouncer-outside-of-juju)
+* [Using a Virtual IP to connect to PgBouncer](#using-a-virtual-ip-to-connect-to-pgbouncer)
+
+---
 
 ## Accessing PgBouncer outside of Juju
 

diff --git a/docs/how-to/h-manage-units.md b/docs/how-to/h-manage-units.md
@@ -1,17 +1,16 @@
-# How to deploy and manage units
-
-## Basic Usage
+# How manage units
 
 To deploy a single unit of PgBouncer using its default configuration:
 ```shell
 juju deploy pgbouncer --channel 1/stable
 ```
 
-## Scaling
+## Scale units
+
+PgBouncer is a subordinated charm, both scaling-up and scaling-down operations are performed via the principal charm using `juju add-unit`:
 
-PgBouncer is a subordinated charm, both scaling-up and scaling-down operations are performed via principal application using `juju add-unit`:
 ```shell
-juju add-unit application -n <desired_num_of_units>
+juju add-unit <principal_charm> -n <desired_num_of_units>
 ```
 
-The subordinated application will be scaled automatically, following the principal application.
+The subordinated charm will be scaled automatically, following the principal charm.
diff --git a/docs/how-to/h-rollback-major.md b/docs/how-to/h-rollback-major.md
diff --git a/docs/how-to/h-upgrade-intro.md b/docs/how-to/h-upgrade-intro.md
diff --git a/docs/how-to/h-upgrade-major.md b/docs/how-to/h-upgrade-major.md
diff --git a/docs/how-to/h-upgrade.md b/docs/how-to/h-upgrade.md
@@ -0,0 +1,12 @@
+# Upgrade
+
+Currently, the charm supports PgBouncer major version 1 only. Therefore, in-place upgrades/rollbacks are not possible for major versions. 
+
+> **Note**: Canonical is not planning to support in-place upgrades for major version change. The new PgBouncer charm will have to be installed nearby, and the data will be copied from the old to the new installation. After announcing the next PostgreSQL + PgBouncer major version support, the appropriate documentation for data migration will be published.
+
+For instructions on carrying out **minor version upgrades**, see the following guides:
+
+* [Minor upgrade](/t/12317?channel=1/stable), e.g. PgBouncer 1.18 -> PgBouncer 1.19<br/>
+(including charm revision bump 99 -> 102).
+* [Minor rollback](/t/12316?channel=1/stable), e.g. PgBouncer 1.19 -> PgBouncer 1.18<br/>
+(including charm revision return 102 -> 99).
diff --git a/docs/overview.md b/docs/overview.md
@@ -1,6 +1,8 @@
-# PgBouncer Documentation
+# PgBouncer documentation
 
-The PgBouncer Operator delivers automated operations management from day 0 to day 2 on the [PgBouncer](http://www.pgbouncer.org/) - the  lightweight connection pooler for PostgreSQL. It is an open source, end-to-end, production-ready data platform on top of [Juju](https://juju.is/).
+This charmed operator packages [PgBouncer](http://www.pgbouncer.org/), the lightweight connection pooler for PostgreSQL. It is an open source, end-to-end, production-ready data platform on top of [Juju](https://juju.is/).
+
+> **Note**: The default channel is now `1/stable`. 
 
 ![image|690x423](https://assets.ubuntu.com/v1/6c2781e9-psql_diagram.png)
 
@@ -32,50 +34,49 @@ This PgBouncer charm is an official distribution of PgBouncer. It’s an open-so
 
 | Level | Path | Navlink |
 |---------|---------|-------------|
-| 1 | tutorial | [Tutorial]() |
-| 2 | t-overview | [1. Introduction](/t/12288) |
-| 2 | t-setup-environment | [2. Set up the environment](/t/12289) |
-| 2 | t-deploy-charm | [3. Deploy PgBouncer](/t/12290) |
-| 2 | t-managing-units | [4. Manage units](/t/12291) |
-| 2 | t-enable-security | [5. Enable security](/t/12292) |
-| 2 | t-cleanup-environment | [6. Cleanup environment](/t/12293) |
-| 1 | how-to | [How To]() |
-| 2 | h-setup | [Setup]() |
-| 3 | h-deploy-lxd | [Deploy on LXD](/t/12312) |
-| 3 | h-manage-units | [Manage units](/t/12309) |
-| 3 | h-enable-encryption | [Enable encryption](/t/12310) |
-| 3 | h-manage-app | [Manage applications](/t/12311) |
-| 3 | h-external-access | [External access](/t/15741) |
-| 2 | h-monitoring | [Monitoring]() |
-| 3 | h-enable-monitoring | [Monitor (COS)](/t/12308) |
-| 3 | h-enable-tracing | [Tracing (COS)](/t/14788) |
-| 2 | h-upgrade | [Upgrade]() |
-| 3 | h-upgrade-intro | [Intro](/t/12313) |
-| 3 | h-upgrade-major | [Major upgrade](/t/12314) |
-| 3 | h-rollback-major | [Major rollback](/t/12315) |
-| 3 | h-upgrade-minor | [Minor upgrade](/t/12317) |
-| 3 | h-rollback-minor | [Minor rollback](/t/12316) |
-| 1 | reference | [Reference]() |
+| 1 | tutorial | [Tutorial](/t/12288) |
+| 2 | t-setup-environment | [1. Set up the environment](/t/12289) |
+| 2 | t-deploy-charm | [2. Deploy PgBouncer](/t/12290) |
+| 2 | t-managing-units | [3. Manage units](/t/12291) |
+| 2 | t-enable-security | [4. Enable TLS](/t/12292) |
+| 2 | t-cleanup-environment | [5. Clean up the environment](/t/12293) |
+| 1 | how-to | [How-to guides](/t/16791) |
+| 2 | h-deploy-lxd | [Deploy](/t/12312) |
+| 2 | h-manage-units | [Manage units](/t/12309) |
+| 2 | h-manage-app | [Manage integrations](/t/12311) |
+| 2 | h-enable-encryption | [Enable TLS](/t/12310) |
+| 2 | h-external-access | [External network access](/t/15741) |
+| 2 | h-monitoring | [Monitoring (COS)]() |
+| 3 | h-enable-monitoring | [Enable monitoring](/t/12308) |
+| 3 | h-enable-tracing | [Enable tracing](/t/14788) |
+| 2 | h-upgrade | [Upgrade](/t/12313) |
+| 3 | h-upgrade-minor | [Perform a minor upgrade](/t/12317) |
+| 3 | h-rollback-minor | [Perform a minor rollback](/t/12316) |
+| 1 | reference | [Reference](/t/16794) |
 | 2 | r-releases | [Release Notes](/t/12285) |
+| 3 | r-revision-639-642 | [Revision 639-642](/t/16135) |
 | 3 | r-revision-394-397 | [Revision 394-397](/t/15379) |
 | 3 | r-revision-278-281 | [Revision 278-281](/t/14853) |
 | 3 | r-revision-254-257 | [Revision 254-257](/t/14666) |
 | 3 | r-revision-173-176 | [Revision 173-176](/t/14069) |
 | 3 | r-revision-89 | [Revision 89](/t/13126) |
 | 3 | r-revision-81 | [Revision 81](/t/12766) |
 | 3 | r-revision-77 | [Revision 77](/t/12286) |
-| 2 | r-requirements | [Requirements](/t/12307) |
-| 2 | r-contributing | [Contributing](https://github.com/canonical/pgbouncer-operator/blob/main/CONTRIBUTING.md) |
-| 2 | r-testing | [Testing](/t/12306) |
+| 2 | r-requirements | [System requirements](/t/12307) |
+| 2 | r-testing | [Software testing](/t/12306) |
 | 2 | r-contacts | [Contacts](/t/12305) |
-| 1 | explanation | [Explanation]() |
+| 1 | explanation | [Explanation](/t/16796) |
+| 2 | e-juju-details | [Juju](/t/12302) |
 | 2 | e-interfaces | [Interfaces/endpoints](/t/12304) |
 | 2 | e-statuses | [Statuses](/t/12303) |
-| 2 | e-juju-details | [Juju](/t/12302) |
 | 2 | e-legacy-charm | [Legacy charm](/t/13944) |
 
 [/details]
 
+<!-- Archived
+| 3 | h-upgrade-major | [Major upgrade](/t/12314) |
+| 3 | h-rollback-major | [Major rollback](/t/12315) |
+-->
 # Redirects
 
 [details=Mapping table]

diff --git a/docs/reference.md b/docs/reference.md
@@ -0,0 +1,24 @@
+# Reference
+
+The Reference section contains pages for technical specifications, APIs, release notes, and other reference material for fast lookup.
+
+* [Release Notes]: Release notes for major revisions of this charm
+* [System requirements]: Software and hardware requirements 
+* [Software testing]: Software tests (e.g. smoke, unit, performance...)
+* [Contacts]
+
+Additionally, you can find automatically generated metadata in the following tabs on Charmhub:
+* [Integrations]
+* [Configurations]
+* [Actions]
+
+
+<!-- Links -->
+[Release Notes]: /t/12285
+[System requirements]: /t/12307
+[Software testing]: /t/12306
+[Contacts]: /t/12305
+
+[Integrations]: https://charmhub.io/pgbouncer/integrations?channel=1/stable
+[Configurations]: https://charmhub.io/pgbouncer/configurations?channel=1/stable
+[Actions]: https://charmhub.io/pgbouncer/actions?channel=1/stable
diff --git a/docs/reference/r-releases.md b/docs/reference/r-releases.md
@@ -15,6 +15,7 @@ For each release, this table shows:
 
 | Release| PgBouncer version | Juju version | [TLS encryption](/t/12310) | [COS monitoring](/t/12308) | [Minor version upgrades](/t/12317) |
 |:---:|:---:|:---:|:---:|:---:|:---:|
+|[639], [640], [641], [642] | `1.21.0` | `3.6.1+` | ![check] | ![check] | ![check]
 |[394], [395], [396], [397]| `1.21.0` | `3.4.5+` | ![check] | ![check] | ![check]
 |[278], [279], [280], [281]| `1.21.0` | `3.4.5+` | ![check] | ![check] | ![check]
 |[254], [255], [256], [257]| `1.21.0` | `3.1.8+` | ![check] | ![check] | ![check]
@@ -28,26 +29,34 @@ For each release, this table shows:
 Due to the [subordinate](https://juju.is/docs/sdk/charm-taxonomy#heading--subordinate-charms) nature of this charm, several [revisions](https://juju.is/docs/sdk/revision) are released simultaneously for different [bases/series](https://juju.is/docs/juju/base) using the same charm code. In other words, one release contains multiple revisions.
 
 > If you do not specify a revision on deploy time, Juju will automatically choose the revision that matches your base and architecture.
+> 
+> See: [`juju info`](https://juju.is/docs/juju/juju-info).
 
-> If you deploy a specific revision, **you must make sure it matches your base and architecture** via the tables below or with [`juju info`](https://juju.is/docs/juju/juju-info).
+### Release 639-642
+| Revision | `amd64` | `arm64` | Ubuntu 20.04 (focal) | Ubuntu 22.04 (jammy)
+|:-----:|:--------:|:--------:|:-----:|:-----:|
+| [639] | ![check] |  |  | ![check] |
+| [640] | ![check] |  | ![check] |          |
+| [641] |  | ![check] | ![check] | |
+| [642] |  | ![check] | | ![check] |
 
-### Release 394-397 (`1/stable`)
+[details=Release 394-397]
+### Release 394-397
 | Revision | `amd64` | `arm64` | Ubuntu 20.04 (focal) | Ubuntu 22.04 (jammy)
 |:-----:|:--------:|:--------:|:-----:|:-----:|
 | [394] |          | ![check] | ![check] |          |
 | [395] | ![check] |          | ![check] |          |
 | [396] | ![check] |          |          | ![check] |
 | [397] |          | ![check] |          | ![check] |
+[/details]
 
 [details=Release 278-281]
-
 | Revision | `amd64` | `arm64` | Ubuntu 20.04 (focal) | Ubuntu 22.04 (jammy)
 |:-----:|:--------:|:--------:|:-----:|:-----:|
 | [278] | ![check] |          |          | ![check] |
 | [279] | ![check] |          | ![check] |          |
 | [280] |          | ![check] |          | ![check] |
 | [281] |          | ![check] | ![check] |          |
-
 [/details]
 
 [details=Release 254-257]
@@ -101,11 +110,14 @@ Due to the [subordinate](https://juju.is/docs/sdk/charm-taxonomy#heading--subord
 
 <br>
 
-[note]
+> **Note**:
  Our release notes are an ongoing work in progress. If there is any additional information about releases that you would like to see or suggestions for other improvements, don't hesitate to contact us on [Matrix ](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) or [leave a comment](https://discourse.charmhub.io/t/pgbouncer-reference-release-notes/12285).
-[/note]
 
 <!--LINKS-->
+[639]: /t/16135
+[640]: /t/16135
+[641]: /t/16135
+[642]: /t/16135
 [394]: /t/15379
 [395]: /t/15379
 [396]: /t/15379