Sync docs from Discourse (#385)

Co-authored-by: GitHub Actions <41898282+github-actions[bot]@users.noreply.github.com>
canonical · Aug 20, 2024 · 3e876da · 3e876da
1 parent 78d557f
commit 3e876da
Show file tree

Hide file tree

Showing 20 changed files with 147 additions and 58 deletions.
diff --git a/docs/how-to/h-setup/h-deploy-microk8s.md → docs/how-to/h-deploy-microk8s.md b/docs/how-to/h-setup/h-deploy-microk8s.md → docs/how-to/h-deploy-microk8s.md
diff --git a/docs/how-to/h-setup/h-enable-encryption.md → docs/how-to/h-enable-encryption.md b/docs/how-to/h-setup/h-enable-encryption.md → docs/how-to/h-enable-encryption.md
diff --git a/...ow-to/h-monitoring/h-enable-monitoring.md → docs/how-to/h-enable-monitoring.md b/...ow-to/h-monitoring/h-enable-monitoring.md → docs/how-to/h-enable-monitoring.md
diff --git a/docs/how-to/h-monitoring/h-enable-tracing.md → docs/how-to/h-enable-tracing.md b/docs/how-to/h-monitoring/h-enable-tracing.md → docs/how-to/h-enable-tracing.md
@@ -49,7 +49,7 @@ Integrate `tempo-k8s` with the COS charms as follows:
 ```shell
 juju integrate tempo-k8s:grafana-dashboard grafana:grafana-dashboard
 juju integrate tempo-k8s:grafana-source grafana:grafana-source
-juju integrate tempo-k8s:ingress traefik:traefik
+juju integrate tempo-k8s:ingress traefik:traefik-route
 juju integrate tempo-k8s:metrics-endpoint prometheus:metrics-endpoint
 juju integrate tempo-k8s:logging loki:logging
 ```

diff --git a/docs/how-to/h-setup/h-manage-app.md → docs/how-to/h-manage-app.md b/docs/how-to/h-setup/h-manage-app.md → docs/how-to/h-manage-app.md
diff --git a/docs/how-to/h-setup/h-manage-units.md → docs/how-to/h-manage-units.md b/docs/how-to/h-setup/h-manage-units.md → docs/how-to/h-manage-units.md
diff --git a/docs/how-to/h-upgrade/h-rollback-major.md → docs/how-to/h-rollback-major.md b/docs/how-to/h-upgrade/h-rollback-major.md → docs/how-to/h-rollback-major.md
diff --git a/docs/how-to/h-upgrade/h-rollback-minor.md → docs/how-to/h-rollback-minor.md b/docs/how-to/h-upgrade/h-rollback-minor.md → docs/how-to/h-rollback-minor.md
diff --git a/docs/how-to/h-upgrade/h-upgrade-intro.md → docs/how-to/h-upgrade-intro.md b/docs/how-to/h-upgrade/h-upgrade-intro.md → docs/how-to/h-upgrade-intro.md
diff --git a/docs/how-to/h-upgrade/h-upgrade-major.md → docs/how-to/h-upgrade-major.md b/docs/how-to/h-upgrade/h-upgrade-major.md → docs/how-to/h-upgrade-major.md
diff --git a/docs/how-to/h-upgrade/h-upgrade-minor.md → docs/how-to/h-upgrade-minor.md b/docs/how-to/h-upgrade/h-upgrade-minor.md → docs/how-to/h-upgrade-minor.md
diff --git a/docs/index.md → docs/overview.md b/docs/index.md → docs/overview.md
@@ -24,42 +24,56 @@ This PgBouncer K8s charm is an official distribution of PgBouncer. It’s an ope
 |  [Tutorials](/t/12251)</br>  Get started - a hands-on introduction to using PgBouncer operator for new users </br> |  [How-to guides](/t/12257) </br> Step-by-step guides covering key operations and common tasks |
 | [Reference](/t/12261) </br> Technical information - specifications, APIs, architecture | [Explanation](/t/12265) </br> Concepts - discussion and clarification of key topics  |
 
-# Contents
+# Navigation
 
-1. [Tutorial](tutorial)
-  1. [1. Introduction](tutorial/t-overview.md)
-  1. [2. Set up the environment](tutorial/t-setup-environment.md)
-  1. [3. Deploy PgBouncer](tutorial/t-deploy-charm.md)
-  1. [4. Manage units](tutorial/t-managing-units.md)
-  1. [5. Enable security](tutorial/t-enable-security.md)
-  1. [6. Clean up environment](tutorial/t-cleanup-environment.md)
-1. [How To](how-to)
-  1. [Setup](how-to/h-setup)
-    1. [Deploy on MicroK8s](how-to/h-setup/h-deploy-microk8s.md)
-    1. [Manage units](how-to/h-setup/h-manage-units.md)
-    1. [Enable encryption](how-to/h-setup/h-enable-encryption.md)
-    1. [Manage applications](how-to/h-setup/h-manage-app.md)
-  1. [Upgrade](how-to/h-upgrade)
-    1. [Intro](how-to/h-upgrade/h-upgrade-intro.md)
-    1. [Major upgrade](how-to/h-upgrade/h-upgrade-major.md)
-    1. [Major rollback](how-to/h-upgrade/h-rollback-major.md)
-    1. [Minor upgrade](how-to/h-upgrade/h-upgrade-minor.md)
-    1. [Minor rollback](how-to/h-upgrade/h-rollback-minor.md)
-  1. [Monitoring](how-to/h-monitoring)
-    1. [Monitor (COS)](how-to/h-monitoring/h-enable-monitoring.md)
-    1. [Tracing (COS)](how-to/h-monitoring/h-enable-tracing.md)
-1. [Reference](reference)
-  1. [Release Notes](reference/r-releases-group)
-    1. [All releases](reference/r-releases-group/r-releases.md)
-    1. [Revision 144/145](reference/r-releases-group/r-releases-rev144.md)
-    1. [Revision 103](reference/r-releases-group/r-releases-rev103.md)
-    1. [Revision 81](reference/r-releases-group/r-releases-rev81.md)
-    1. [Revision 76](reference/r-releases-group/r-releases-rev76.md)
-  1. [Requirements](reference/r-requirements.md)
-  1. [Contributing](https://github.com/canonical/pgbouncer-k8s-operator/blob/main/CONTRIBUTING.md)
-  1. [Testing](reference/r-testing.md)
-  1. [Contacts](reference/r-contacts.md)
-1. [Explanation](explanation)
-  1. [Interfaces/endpoints](explanation/e-interfaces.md)
-  1. [Statuses](explanation/e-statuses.md)
-  1. [Juju](explanation/e-juju-details.md)
+[details=Navigation]
+
+| Level | Path | Navlink |
+|---------|---------|-------------|
+| 1 | tutorial | [Tutorial]() |
+| 2 | t-overview | [1. Introduction](/t/12251) |
+| 2 | t-setup-environment | [2. Set up the environment](/t/12252) |
+| 2 | t-deploy-charm | [3. Deploy PgBouncer](/t/12253) |
+| 2 | t-managing-units | [4. Manage units](/t/12254) |
+| 2 | t-enable-security | [5. Enable security](/t/12255) |
+| 2 | t-cleanup-environment | [6. Clean up environment](/t/12256) |
+| 1 | how-to | [How To]() |
+| 2 | h-setup | [Setup]() |
+| 3 | h-deploy-microk8s | [Deploy on MicroK8s](/t/12257) |
+| 3 | h-manage-units | [Manage units](/t/12258) |
+| 3 | h-enable-encryption | [Enable encryption](/t/12259) |
+| 3 | h-manage-app | [Manage applications](/t/12260) |
+| 2 | h-upgrade | [Upgrade]() |
+| 3 | h-upgrade-intro | [Intro](/t/12267) |
+| 3 | h-upgrade-major | [Major upgrade](/t/12268) |
+| 3 | h-rollback-major | [Major rollback](/t/12269) |
+| 3 | h-upgrade-minor | [Minor upgrade](/t/12270) |
+| 3 | h-rollback-minor | [Minor rollback](/t/12271) |
+| 2 | h-monitoring | [Monitoring]() |
+| 3 | h-enable-monitoring | [Monitor (COS)](/t/12279) |
+| 3 | h-enable-tracing | [Tracing (COS)](/t/14789) |
+| 1 | reference | [Reference]() |
+| 2 | r-releases-group | [Release Notes]() |
+| 3 | r-releases | [All releases](/t/12261) |
+| 3 | r-releases-rev228 | [Revision 228/229](/t/15090) |
+| 3 | r-releases-rev144 | [Revision 144/145](/t/14070) |
+| 3 | r-releases-rev103 | [Revision 103](/t/13297) |
+| 3 | r-releases-rev81 | [Revision 81](/t/12751) |
+| 3 | r-releases-rev76 | [Revision 76](/t/12262) |
+| 2 | r-requirements | [Requirements](/t/12263) |
+| 2 | r-contributing | [Contributing](https://github.com/canonical/pgbouncer-k8s-operator/blob/main/CONTRIBUTING.md) |
+| 2 | r-testing | [Testing](/t/12272) |
+| 2 | r-contacts | [Contacts](/t/12264) |
+| 1 | explanation | [Explanation]() |
+| 2 | e-interfaces | [Interfaces/endpoints](/t/12265) |
+| 2 | e-statuses | [Statuses](/t/12266) |
+| 2 | e-juju-details | [Juju](/t/12274) |
+
+[/details]
+
+# Redirects
+
+[details=Mapping table]
+| Path | Location |
+| ---- | -------- |
+[/details]
diff --git a/...nce/r-releases-group/r-releases-rev103.md → docs/reference/r-releases-rev103.md b/...nce/r-releases-group/r-releases-rev103.md → docs/reference/r-releases-rev103.md
diff --git a/...nce/r-releases-group/r-releases-rev144.md → docs/reference/r-releases-rev144.md b/...nce/r-releases-group/r-releases-rev144.md → docs/reference/r-releases-rev144.md
diff --git a/docs/reference/r-releases-rev228.md b/docs/reference/r-releases-rev228.md
@@ -0,0 +1,90 @@
+>Reference > Release Notes > [All revisions](/t/12261) > Revisions 228/229
+
+# Revision 228/229
+<sub>Aug 13, 2024</sub>
+
+Dear community,
+
+Canonical’s newest Charmed PgBouncer K8s operator has been published in the 1/stable [channel](https://charmhub.io/pgbouncer-k8s?channel=1/stable) :tada: 
+
+Due to its mult-architecture support, PgBouncer charm releases two revisions simultaneously: 
+* Revision 229 is built for `amd64`
+* Revision 228 is built for for `arm64`
+
+To make sure you deploy for the right architecture, we recommend setting an [architecture constraint](https://juju.is/docs/juju/constraint#heading--arch) for your entire juju model.
+
+Otherwise, it can be done at deploy time with the `--constraints` flag:
+```shell
+juju deploy pgbouncer-k8s --trust --constraints arch=<arch> 
+```
+where `<arch>` can be `amd64` or `arm64`.
+
+[note]
+If you are jumping over several stable revisions, make sure to check [previous release notes](/t/12261?channel=1/stable) before upgrading to this revision.
+[/note]  
+
+## Highlights
+
+Below are the major highlights of this release. To see all changes since the previous stable release, check the [release notes on GitHub](https://github.com/canonical/pgbouncer-k8s-operator/releases/tag/rev229)
+
+* Added support for multiple databases ([PR #324](https://github.com/canonical/pgbouncer-k8s-operator/pull/324)) ([DPE-4642](https://warthogs.atlassian.net/browse/DPE-4642))
+* Added support for tracing with Tempo K8s ([PR #296](https://github.com/canonical/pgbouncer-k8s-operator/pull/296)) ([DPE-4619](https://warthogs.atlassian.net/browse/DPE-4619))
+  * Check the new guide: [How to enable tracing](https://charmhub.io/pgbouncer-k8s/docs/h-enable-tracing)
+* Updated database ownership to allow dropping tables after re-relation ([PR #287](https://github.com/canonical/pgbouncer-k8s-operator/pull/287)) ([DPE-1454](https://warthogs.atlassian.net/browse/DPE-1454))
+* Added UX message for charm deployed without `--trust` flag in ([PR #319](https://github.com/canonical/pgbouncer-k8s-operator/pull/319)) ([DPE-4062](https://warthogs.atlassian.net/browse/DPE-4062))
+
+### Enhancements
+* Upgraded Nodeport ([PR #342](https://github.com/canonical/pgbouncer-k8s-operator/pull/342)) ([DPE-4236](https://warthogs.atlassian.net/browse/DPE-4236))
+* Added jinja2 as a dependency ([PR #332](https://github.com/canonical/pgbouncer-k8s-operator/pull/332)) ([DPE-4816](https://warthogs.atlassian.net/browse/DPE-4816))
+* Updated Juju agent to v.3.4.4 for CI ([PR #337](https://github.com/canonical/pgbouncer-k8s-operator/pull/337)) ([DPE-4811](https://warthogs.atlassian.net/browse/DPE-4811))      
+* Updated charm libs ([PR #357](https://github.com/canonical/pgbouncer-k8s-operator/pull/357))                         
+* Updated Juju dependency to v3.4.5 ([PR #359](https://github.com/canonical/pgbouncer-k8s-operator/pull/359))         
+* Added integration tests to arm64 runners ([PR #291](https://github.com/canonical/pgbouncer-k8s-operator/pull/291))                
+* Updated Python dependencies
+
+### Bugfixes
+
+* Updated old information on CONTRIBUTING ([PR #290](https://github.com/canonical/pgbouncer-k8s-operator/pull/290)) ([DPE-3991](https://warthogs.atlassian.net/browse/DPE-3991))                   
+* Increased PostgreSQL deploy timeouts ([PR #340](https://github.com/canonical/pgbouncer-k8s-operator/pull/340))        
+* Stabilized tests and CI
+
+<!-- Removed some points that don't seem too relevant/major at a glance, but feel free to re-add if you think they should be here.
+* Secrets tweaks ([PR #298](https://github.com/canonical/pgbouncer-k8s-operator/pull/298))
+* Use preset renovate configuration ([PR #316](https://github.com/canonical/pgbouncer-k8s-operator/pull/316))     
+-->
+
+Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.net/jira/software/c/projects/DPE/issues/) and [GitHub](https://github.com/canonical/pgbouncer-k8s-operator/issues). To see all commits since the previous stable release, check the [release notes on GitHub](https://github.com/canonical/pgbouncer-k8s-operator/releases/tag/rev229).
+
+
+## Technical details
+This section contains some technical details about the charm's contents and dependencies. Make sure to also check the [system requirements](https://charmhub.io/pgbouncer-k8s/docs/r-requirements).
+
+### Packaging
+This charm is based on the [ROCK OCI](https://github.com/orgs/canonical/packages?tab=packages&q=charmed) for Ubuntu LTS 22.04.4  <!--revision `TODO`-->. It packages:
+
+* pgbouncer `v.1.21`
+  *  [`1.21.0-0ubuntu0.22.04.1~ppa1`](https://launchpad.net/~data-platform/+archive/ubuntu/pgbouncer)
+* prometheus pgbouncer-exporter `v.0.7.01`
+  *  [`0.7.0-0ubuntu0.22.04.1~ppa1`](https://launchpad.net/~data-platform/+archive/ubuntu/pgbouncer-exporter)
+
+### Libraries and interfaces
+These are some of the libraries supported by the charm:
+* **grafana_k8s `v0`** for integration with Grafana 
+    * Implements  `grafana_dashboard` interface
+* **tempo_k8s `v1`, `v2`** for integration with Tempo charm
+    * Implements `tracing` interface
+* **loki_k8s `v0`** for integration with Loki
+  * Implements the `loki_push_api` interface
+* **tls_certificates_interface `v2`** for integration with TLS charms
+    * Implements `tls-certificates` interface
+
+See the [`/lib/charms` directory on GitHub](https://github.com/canonical/pgbouncer-k8s-operator/tree/main/lib/charms) for more details about all supported libraries.
+
+See the [`metadata.yaml` file on GitHub](https://github.com/canonical/pgbouncer-k8s-operator/blob/main/metadata.yaml) for a full list of supported interfaces.
+
+## Contact us
+
+Charmed PgBouncer K8s is an open source project that warmly welcomes community contributions, suggestions, fixes, and constructive feedback.  
+* Raise software issues or feature requests on [**GitHub**](https://github.com/canonical/pgbouncer-k8s-operator/issues)  
+*  Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File)  
+* Contact the Canonical Data Platform team through our [Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) channel.
diff --git a/...ence/r-releases-group/r-releases-rev76.md → docs/reference/r-releases-rev76.md b/...ence/r-releases-group/r-releases-rev76.md → docs/reference/r-releases-rev76.md
diff --git a/...ence/r-releases-group/r-releases-rev81.md → docs/reference/r-releases-rev81.md b/...ence/r-releases-group/r-releases-rev81.md → docs/reference/r-releases-rev81.md
diff --git a/.../reference/r-releases-group/r-releases.md → docs/reference/r-releases.md b/.../reference/r-releases-group/r-releases.md → docs/reference/r-releases.md
@@ -7,7 +7,8 @@ Here you will find release notes for the main revisions of this charm that are a
 
 |  Channel | amd64 | arm64 |
 |----------:|:-----:|:-----:|
-| `1/stable` | [144](/t/14070) | [145](/t/14070) |
+| `1/stable` | [229](/t/15090) | [228](/t/15090) |
+|                     | [144](/t/14070) | [145](/t/14070) |
 |                     | [103](/t/13297) | - |
 |                     | [81](/t/12751) | - |
 |                     | [76](/t/12262) | - |
diff --git a/docs/tutorial/t-deploy-charm.md b/docs/tutorial/t-deploy-charm.md
@@ -4,25 +4,12 @@ This is part of the [PgBouncer K8s Tutorial](/t/12251). Please refer to this pag
 
 In this section, you will deploy PgBouncer together with a PostgreSQL server from [Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s). 
 
-[note]
-**Note**: All commands are written for `juju >= v.3.0`
-
-If you are using an earlier version, be aware that:
-
- - `juju run` replaces `juju run-action --wait` in `juju v.2.9` 
- - `juju integrate` replaces `juju relate` and `juju add-relation` in `juju v.2.9`
-
-For more information, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022).
-[/note]
-
 ## Deploy Charmed PostgreSQL K8s + PgBouncer K8s
 
 To deploy Charmed PostgreSQL K8s + PgBouncer K8s, all you need to do is run the following commands:
 
 ```shell
 juju deploy pgbouncer-k8s --channel 1/stable --trust
-```
-```shell
 juju deploy postgresql-k8s --trust
 ```
 [note]
@@ -94,9 +81,6 @@ To retrieve these values, please run data-integrator action `get-credentials`:
 ```shell
 juju run data-integrator/leader get-credentials
 ```
-[note type="caution"]
-For versions of juju before v3.0, use `juju run-action` instead of `juju run`.
-[/note]
 
 Running the command above should output:
 ```yaml
@@ -121,7 +105,7 @@ To access the PostgreSQL database via PgBouncer, use the port 6432 and your host
 ```shell
 psql -h 10.152.183.84 -p 6432 -U relation_id_7 -W -d test123
 ```
-Inside MySQL, list DBs available on the host with  `show databases`:
+Inside PostgreSQL, list DBs available on the host with  `show databases`:
 ```shell
 Password for user relation_id_7:  VYm6tg2KkFOBj8mP3IW9O821
 psql (14.9 (Ubuntu 14.9-0ubuntu0.22.04.1))

diff --git a/docs/tutorial/t-managing-units.md b/docs/tutorial/t-managing-units.md
@@ -4,7 +4,7 @@ This is part of the [PgBouncer K8s Tutorial](/t/12251). Please refer to this pag
 
 ## Adding and Removing units
 
-Please check the explanation of scaling Charmed PostgreSQL K8s operator [here](https://charmhub.io/postgresql-k8s/docs/t-managing-units).
+Please check the explanation of scaling Charmed PostgreSQL K8s operator [here](https://charmhub.io/postgresql-k8s/docs/t-scale).
 
 ### Add more PgBouncer instances