Skip to content

Commit

Permalink
Sync docs from Discourse
Browse files Browse the repository at this point in the history
  • Loading branch information
github-actions[bot] committed Feb 12, 2025
1 parent a2d5e85 commit 395ddc2
Show file tree
Hide file tree
Showing 6 changed files with 144 additions and 12 deletions.
4 changes: 3 additions & 1 deletion docs/explanation/e-legacy-charm.md
Original file line number Diff line number Diff line change
Expand Up @@ -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!

Expand Down
18 changes: 15 additions & 3 deletions docs/how-to/h-external-access.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down
3 changes: 2 additions & 1 deletion docs/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ This PgBouncer charm is an official distribution of PgBouncer. It’s an open-so
| 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-enable-security | [5. Enable TLS](/t/12292) |
| 2 | t-cleanup-environment | [6. Cleanup environment](/t/12293) |
| 1 | how-to | [How To]() |
| 2 | h-setup | [Setup]() |
Expand All @@ -57,6 +57,7 @@ This PgBouncer charm is an official distribution of PgBouncer. It’s an open-so
| 3 | h-rollback-minor | [Minor rollback](/t/12316) |
| 1 | reference | [Reference]() |
| 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) |
Expand Down
24 changes: 18 additions & 6 deletions docs/reference/r-releases.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -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]
Expand Down Expand Up @@ -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
Expand Down
105 changes: 105 additions & 0 deletions docs/reference/r-revision-639-642.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
>Reference > Release Notes > [All revisions] > Revision 639-642
# Revision 639/640/641/642
February 4, 2025

Dear community,

Canonical's newest Charmed PgBouncer operator has been published in the [1/stable channel]:
* Revision 639 is built for `amd64` on Ubuntu 22.04 LTS
* Revision 640 is built for `amd64` on Ubuntu 20.04 LTS
* Revision 642 is built for `arm64` on Ubuntu 22.04 LTS
* Revision 641 is built for `arm64` on Ubuntu 20.04 LTS

If you are jumping over several stable revisions, check [previous release notes][All revisions] before upgrading.

---

## Highlights

* Updated juju 2 version to `v2.9.51` ([PR #375](https://github.com/canonical/pgbouncer-operator/pull/375))
* Updated juju 3 version to `v3.6.1+` ([PR#449](https://github.com/canonical/pgbouncer-operator/pull/449)), ([PR #377](https://github.com/canonical/pgbouncer-operator/pull/377))

## Features and improvements

* Retrieve charm tracing libs from `tempo_coordinator_k8s` ([PR #386](https://github.com/canonical/pgbouncer-operator/pull/386))
* Relay traces traffic through `grafana-agent` and test integration with Tempo HA ([PR #397](https://github.com/canonical/pgbouncer-operator/pull/397))
* Enable round-robin connections to read-only backend nodes ([PR #393](https://github.com/canonical/pgbouncer-operator/pull/393)) ([DPE-5613](https://warthogs.atlassian.net/browse/DPE-5613))

## Bugfixes and maintenance

* General secrets resetting fix for Juju 3.6+ ([PR#449](https://github.com/canonical/pgbouncer-operator/pull/449))[[DPE-6320](https://warthogs.atlassian.net/browse/DPE-6320)][[DPE-6325](https://warthogs.atlassian.net/browse/DPE-6325)]
* PgBouncer COS dashboard bugfixes ([PR#438](https://github.com/canonical/pgbouncer-operator/pull/438))
* Make tox commands resilient to whitespace paths ([PR #413](https://github.com/canonical/pgbouncer-operator/pull/413)) ([DPE-6042](https://warthogs.atlassian.net/browse/DPE-6042))
* Fixed missing IP errors ([PR #353](https://github.com/canonical/pgbouncer-operator/pull/353))
* Don't set secrets until db is set ([PR #373](https://github.com/canonical/pgbouncer-operator/pull/373)) ([DPE-5564](https://warthogs.atlassian.net/browse/DPE-5564))
* Increased ruff rules ([PR #390](https://github.com/canonical/pgbouncer-operator/pull/390))
* Disabled conflicting build ([PR #371](https://github.com/canonical/pgbouncer-operator/pull/371))
* Stopped tracking channel for held snaps ([PR #384](https://github.com/canonical/pgbouncer-operator/pull/384))
* Handle secret permission error ([PR #358](https://github.com/canonical/pgbouncer-operator/pull/358))

[details=Libraries, testing, and CI]

* Migrate to charmcraft 3 poetry plugin ([PR#448](https://github.com/canonical/pgbouncer-operator/pull/448))
* Attempt to run tests on juju 3.6/candidate on a nightly schedule ([PR #402](https://github.com/canonical/pgbouncer-operator/pull/402)) ([DPE-5622](https://warthogs.atlassian.net/browse/DPE-5622))
* Re-enable cached builds ([PR #406](https://github.com/canonical/pgbouncer-operator/pull/406))
* Use the same build job in release and ci workflows ([PR #403](https://github.com/canonical/pgbouncer-operator/pull/403))
* Switch to team reviewer ([PR #351](https://github.com/canonical/pgbouncer-operator/pull/351))
* Disable cached builds ([PR #369](https://github.com/canonical/pgbouncer-operator/pull/369))
* Run juju 3.6 nightly tests against 3.6/stable ([PR #417](https://github.com/canonical/pgbouncer-operator/pull/417))
* Lock file maintenance Python dependencies ([PR #423](https://github.com/canonical/pgbouncer-operator/pull/423))
* Migrate config .github/renovate.json5 ([PR #407](https://github.com/canonical/pgbouncer-operator/pull/407))
* Switch from tox build wrapper to charmcraft.yaml overrides ([PR #370](https://github.com/canonical/pgbouncer-operator/pull/370))
* Update canonical/charming-actions action to v2.6.3 ([PR #354](https://github.com/canonical/pgbouncer-operator/pull/354))
* Update codecov/codecov-action action to v5 ([PR #408](https://github.com/canonical/pgbouncer-operator/pull/408))
* Update data-platform-workflows to v23.1.0 ([PR #418](https://github.com/canonical/pgbouncer-operator/pull/418))
* Split python dependency for cryptography v44 compatibility ([PR #421](https://github.com/canonical/pgbouncer-operator/pull/421))
[/details]

<!-- Did not include these
* Disabled self hosted packing and integration tests ([PR #414](https://github.com/canonical/pgbouncer-operator/pull/414))
* Use self-hosted runners when packing the charm ([PR #396](https://github.com/canonical/pgbouncer-operator/pull/396)) ([DPE-5642](https://warthogs.atlassian.net/browse/DPE-5642))
* Use self-hosted runners for integration tests ([PR #412](https://github.com/canonical/pgbouncer-operator/pull/412))
-->

## Requirements and compatibility
<!--TODO: workload, juju, or other important version changes -->

See the [system requirements] for more details about Juju versions and other software and hardware prerequisites.

### Packaging

This charm is based on the Charmed PgBouncer [snap] . It packages:
* [pgbouncer] `v.1.21`
* [prometheus-pgbouncer-exporter] `v.0.7.0`

See the [`/lib/charms` directory on GitHub] for more details about all supported libraries.

See the [`metadata.yaml` file on GitHub] for a full list of supported interfaces.


<!-- Topics -->
[All revisions]: /t/12285
[system requirements]: /t/12307

<!-- GitHub -->
[`/lib/charms` directory on GitHub]: https://github.com/canonical/pgbouncer-operator/tree/main/lib/charms
[`metadata.yaml` file on GitHub]: https://github.com/canonical/pgbouncer-operator/blob/main/metadata.yaml

<!-- Charmhub -->
[1/stable channel]: https://charmhub.io/pgbouncer?channel=1/stable

<!-- Snap/Rock -->
[`charmed-pgbouncer` packaging]: https://github.com/canonical/charmed-pgbouncer-snap

[snap]: https://github.com/canonical/charmed-pgbouncer-snap/
[rock image]: https://github.com/orgs/canonical/packages?repo_name=charmed-pgbouncer-rock

[pgbouncer]: https://launchpad.net/~data-platform/+archive/ubuntu/pgbouncer
[prometheus-pgbouncer-exporter]: https://launchpad.net/~data-platform/+archive/ubuntu/pgbouncer-exporter


<!-- Badges -->
[juju-2_amd64]: https://img.shields.io/badge/Juju_2.9.51-amd64-darkgreen?labelColor=ea7d56
[juju-3_amd64]: https://img.shields.io/badge/Juju_3.4.6-amd64-darkgreen?labelColor=E95420
[juju-3_arm64]: https://img.shields.io/badge/Juju_3.4.6-arm64-blue?labelColor=E95420
2 changes: 1 addition & 1 deletion docs/tutorial/t-setup-environment.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ multipass shell my-vm
```
*Note: if at any point you'd like to leave Multipass VM, enter `Ctrl+d` or type `exit`*.

All the parts have been pre-installed inside VM already, like LXD and Juju (the files '/var/log/cloud-init.log' and '/var/log/cloud-init-output.log' contain all low-level installation details). Let's bootstrap Juju to use local LXD:
All the parts have been pre-installed inside VM already, like LXD and Juju (the files '/var/log/cloud-init.log' and '/var/log/cloud-init-output.log' contain all low-level installation details). Let's bootstrap Juju to use local LXD. We will call it “overlord”, but you can give it any name you’d like:
```shell
juju bootstrap localhost overlord
```
Expand Down

0 comments on commit 395ddc2

Please # to comment.