Sync docs from Discourse (canonical#703)

* Sync docs from Discourse * Update sync_docs.yaml --------- Co-authored-by: GitHub Actions <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Andreia Velasco <[email protected]>
Zvirovyi · Sep 25, 2024 · 612240e · 612240e
1 parent a4deb82
commit 612240e
Show file tree

Hide file tree

Showing 6 changed files with 167 additions and 63 deletions.
diff --git a/.github/workflows/sync_docs.yaml b/.github/workflows/sync_docs.yaml
@@ -12,7 +12,7 @@ jobs:
     name: Sync docs from Discourse
     uses: canonical/data-platform-workflows/.github/workflows/[email protected]
     with:
-      reviewers: a-velasco,izmalk
+      reviewers: a-velasco
     permissions:
       contents: write  # Needed to push branch & tag
       pull-requests: write  # Needed to create PR
diff --git a/docs/how-to/h-restore-backup.md b/docs/how-to/h-restore-backup.md
@@ -10,12 +10,19 @@ This is a guide on how to restore a locally made backup.
 
 To restore a backup that was made from a *different* cluster, (i.e. cluster migration via restore), see [How to migrate cluster using backups](/t/charmed-postgresql-k8s-how-to-migrate-clusters/9598?channel=14/stable).
 
-
 ## Prerequisites
 - Deployments have been [scaled-down](/t/charmed-postgresql-k8s-how-to-manage-units/9592?channel=14/stable) to a single PostgreSQL unit (scale it up after the backup is restored)
 - Access to S3 storage
 - [Configured settings for S3 storage](/t/charmed-postgresql-k8s-how-to-configure-s3/9595?channel=14/stable)
 - [Existing backups in your S3-storage](/t/charmed-postgresql-k8s-how-to-create-and-list-backups/9596?channel=14/stable)
+- [Point-in-time recovery](#point-in-time-recovery) requires the following PostgreSQL charm revisions:
+   - 435+ for `arm64`
+  -  436+ for `amd64`
+
+## Summary
+* [List backups](#list-backups)
+* [Point-in-time recovery](#point-in-time-recovery)
+* [Restore backup](#restore-backup)
 
 ---
 
@@ -27,15 +34,46 @@ juju run postgresql-k8s/leader list-backups
 
 This should show your available backups like in the sample output below:
 ```shell
-    backups: |-
-      backup-id             | backup-type  | backup-status
-      ----------------------------------------------------
-      YYYY-MM-DDTHH:MM:SSZ  | physical     | finished
+list-backups: |-
+  Storage bucket name: canonical-postgres
+  Backups base path: /test/backup/
+
+  backup-id            | action             | ... | timeline
+  ---------------------------------------------------------------------------
+  2024-07-22T13:11:56Z | full backup        | ... | 1
+  2024-07-22T14:12:45Z | incremental backup | ... | 1
+  2024-07-22T15:34:24Z | restore            | ... | 2
+  2024-07-22T16:26:48Z | incremental backup | ... | 2
+  2024-07-22T17:17:59Z | full               | ... | 2
+  2024-07-22T18:05:32Z | restore            | ... | 3
 ```
+
+Below is a complete list of parameters shown for each backup/restore operation:
+* `backup-id`: unique identifier of the backup.
+* `action`: indicates the action performed by the user through one of the charm action; can be any of full backup, incremental backup, differential backup or restore.
+* `status`: either finished (successfully) or failed.
+* `reference-backup-id` 
+* `LSN start/stop`: a database specific number (or timestamp) to identify its state.
+* `start-time`: records start of the backup operation.
+* `finish-time`: records end of the backup operation.
+* `backup-path`: path of the backup related files in the S3 repository.
+* `timeline`: number which identifies different branches in the database transactions history; every time a restore or PITR is made, this number is incremented by 1.
+
+## Point-in-time recovery
+Point-in-time recovery (PITR) is a PostgreSQL feature that enables restorations to the database state at specific points in time.
+
+After performing a PITR in a PostgreSQL cluster, a new timeline is created to track from the point to where the database was restored. They can be tracked via the `timeline` parameter in the `list-backups` output.
+
 ## Restore backup
-To restore a backup from that list, run the `restore` command and pass the corresponding `backup-id`:
+To restore a backup from that list, run the `restore` command and pass the parameter corresponding to the backup type.
+
+When the user needs to restore a specific backup that was made, they can use the `backup-id` that is listed in the `list-backups` output. 
  ```shell
 juju run postgresql-k8s/leader restore backup-id=YYYY-MM-DDTHH:MM:SSZ
 ```
+However, if the user needs to restore to a specific point in time between different backups (e.g. to restore only specific transactions made between those backups), they can use the `restore-to-time` parameter to pass a timestamp related to the moment they want to restore.
+ ```shell
+juju run postgresql-k8s/leader restore restore-to-time="YYYY-MM-DDTHH:MM:SSZ"
+```
 
 Your restore will then be in progress.
diff --git a/docs/overview.md b/docs/overview.md
@@ -90,8 +90,7 @@ PostgreSQL is a trademark or registered trademark of PostgreSQL Global Developme
 | 2 | h-enable-plugins-extensions | [Enable plugins/extensions](/t/10907) |
 | 1 | reference | [Reference]() |
 | 2 | r-overview | [Overview](/t/13977) |
-| 2 | r-releases | [Release Notes]() |
-| 3 | r-all-releases | [All releases](/t/11872) |
+| 2 | r-releases | [Release Notes](/t/11872) |
 | 3 | r-revision-381-382 | [Revision 381/382](/t/15442) |
 | 3 | r-revision-280-281 | [Revision 280/281](/t/14068) |
 | 3 | r-revision-193 | [Revision 193](/t/13208) |

diff --git a/docs/reference/r-all-releases.md b/docs/reference/r-all-releases.md
diff --git a/docs/reference/r-releases.md b/docs/reference/r-releases.md
@@ -0,0 +1,65 @@
+# Release Notes
+
+This page provides high-level overviews of the dependencies and features that are supported by each revision in every stable release.
+
+To learn more about the different release tracks and channels, see the [Juju documentation about channels](https://juju.is/docs/juju/channel#heading--risk).
+
+To see all releases and commits, check the [Charmed PostgreSQL Releases page on GitHub](https://github.com/canonical/postgresql-k8s-operator/releases).
+
+## Dependencies and supported features
+
+For a given release, this table shows:
+* The PostgreSQL version packaged inside
+* The minimum Juju version required to reliably operate **all** features of the release
+   > This charm still supports older versions of Juju down to 2.9. See the [Juju section of the system requirements](/t/) for more details
+* Support for specific features
+
+| Revision | PostgreSQL version | Juju version | [TLS encryption](/t/9685)* | [COS monitoring](/t/10600) | [Minor version upgrades](/t/) | [Cross-regional async replication](/t/) | [Point-in-time recovery](/t/)
+|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| [381], [382] | 14.12 | `3.4.5+` | ![check] | ![check] | ![check] | ![check] | ![check] |
+| [280], [281] | 14.11 | `3.1.8+` | ![check] | ![check] | ![check] | ![check] |
+| [193] | 14.10 | `3.1.7+` | ![check] | ![check] | ![check] | ![check] |
+| [177] | 14.9 | `3.1.6+` |  | ![check] | ![check] |
+| [158] | 14.9 | `3.1.5+` |  | ![check] | ![check] |
+| [73]  | 14.7 | `2.9.32+` |  |  |
+
+
+**TLS encryption***: Support for **`v2` or higher** of the [`tls-certificates` interface](https://charmhub.io/tls-certificates-interface/libraries/tls_certificates). This means that you can integrate with [modern TLS charms](https://charmhub.io/topics/security-with-x-509-certificates).
+
+For more details about a particular revision, refer to its dedicated Release Notes page.
+For more details about each feature/interface, refer to their dedicated How-To guide.
+
+## Architecture and base
+One release may come with more than one revision. This is because each revision is built for a specific combination of hardware architecture and base (Ubuntu version).
+
+| Release | amd64 | arm64 | Ubuntu 22.04 LTS
+|:--------:|:-----:|:-----:|:-----:|
+|[382] | | ![check] | ![check]  |
+|[381] | ![check] | | ![check] |
+|[281] |![check]| | ![check]   |
+|[280] |  | ![check]| ![check] |
+|[193] | ![check]| | ![check]  |
+|[177] |![check]| | ![check]   |
+|[158] |![check]| | ![check]   |
+|[73] |![check]| | ![check]   |
+
+## Plugins/extensions
+
+For a list of all plugins supported for each revision, see the reference page [Plugins/extensions](/t/10945).
+
+[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/charmed-postgresql-reference-release-notes/11875).
+[/note]
+
+<!-- LINKS -->
+[382]: /t/15442
+[381]: /t/15442
+[281]: /t/14068
+[280]: /t/14068
+[193]: /t/13208
+[177]: /t/12668
+[158]: /t/11874
+[73]: /t/11873
+
+<!--BADGES-->
+[check]: https://img.icons8.com/color/20/checkmark--v1.png
diff --git a/docs/reference/r-revision-381-382.md b/docs/reference/r-revision-381-382.md
@@ -11,7 +11,6 @@ Due to the newly added support for `arm64` architecture, the PostgreSQL K8s char
 * Revision 381 is built for `amd64` on Ubuntu 22.04 LTS
 * Revision 382 is built for `arm64` on Ubuntu 22.04 LTS
 
-
 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:
@@ -74,20 +73,44 @@ where `<arch>` can be `amd64` or `arm64`.
 
 If you are jumping over several stable revisions, check [previous release notes][All revisions] before upgrading.
 
+## Requirements and compatibility
+This charm revision features the following changes in dependencies:
+* (increased) The minimum Juju version required to reliably operate **all** features of the release is `v3.4.5`
+  > You can upgrade to this revision on Juju  `v2.9.50+`, but it will not support newer features like cross-regional asynchronous replication, point-in-time recovery, and modern TLS certificate charm integrations.
+* (increased) PostgreSQL version 14.12
+
 See the [system requirements] for more details about Juju versions and other software and hardware prerequisites.
 
-## Dependencies
-This revision was explicitly tested with the following dependencies:
-* `microk8s v.1.31` - Channel `strict/stable`
-* `data-integrator` - Revision 41
-* `indico` - Revision 213
-* `discourse-k8s` - Revision 124
-* `postgresql-test-app` - Revision 239
-* `s3-integrator` - Revision 31
+### Integration tests
+Below are the charm integrations tested with this revision on different Juju environments and architectures:
 * Juju `v.2.9.50` on `amd64`
-  * `tls-certificates-operator` - Channel `legacy/stable`, Revision 22
-* Juju `v.3.4.5` on `amd64` and `arm64`
-  * `self-signed-certificates` - Channel `latest/stable`, Revision 155
+* Juju  `v.3.4.5` on `amd64` and `arm64`
+
+#### Juju `v.2.9.50` on `amd64`
+
+| Software | Version |
+|-----|-----|
+| [tls-certificates-operator] | `rev 22`, `legacy/stable` | 
+
+#### Juju  `v.3.4.5` on `amd64` and `arm64`
+
+| Software | Version | 
+|-----|-----|
+| [self-signed-certificates] | `rev 155`, `latest/stable` | 
+
+####  All
+| Software | Version | 
+|-----|-----|
+| [microk8s] | `v.1.31`, `strict/stable` | 
+| [indico] | `rev 213` | 
+| [discourse-k8s] | `rev 124` | 
+| [data-integrator] | `rev 41` | 
+| [s3-integrator] | `rev 31` | 
+| [postgresql-test-app] | `rev 239` | 
+
+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.
 
 ## Packaging
 
@@ -98,12 +121,8 @@ This charm is based on the Charmed PostgreSQL K8s [rock image]. It packages:
 * [pgBackRest `v.2.48`]
 * [prometheus-postgres-exporter `v.0.12.1`]
 
-See the [`/lib/charms` directory on GitHub] for more details about all supported libraries.<br/>
-See the [`metadata.yaml` file on GitHub] for a full list of supported interfaces.
-
 ## Dependencies and automations
-
-This section contains some technical details about the charm's contents and dependencies. 
+[details=This section contains a list of updates to libs, dependencies, actions, and workflows.] 
 
 * Updated canonical/charming-actions action to v2.6.3 ([PR #673](https://github.com/canonical/postgresql-k8s-operator/pull/673))
 * Updated data-platform-workflows to v21.0.1 ([PR #660](https://github.com/canonical/postgresql-k8s-operator/pull/660))
@@ -120,21 +139,21 @@ This section contains some technical details about the charm's contents and depe
 * Updated postgresql lib ([PR #546](https://github.com/canonical/postgresql-k8s-operator/pull/546))
 * Bumped coverage ([PR #623](https://github.com/canonical/postgresql-k8s-operator/pull/623))
 * Test service patch lib update ([PR #624](https://github.com/canonical/postgresql-k8s-operator/pull/624))
+[/details]
 
-<!-- Topics -->
+<!-- DISCOURSE TOPICS-->
 [All revisions]: /t/11872
 [system requirements]: /t/11744
 
-<!-- GitHub -->
+<!-- CHARM GITHUB -->
 [`/lib/charms` directory on GitHub]: https://github.com/canonical/postgresql-k8s-operator/tree/main/lib/charms
 [`metadata.yaml` file on GitHub]: https://github.com/canonical/postgresql-k8s-operator/blob/main/metadata.yaml
 
-<!-- Charmhub -->
+<!-- CHARMHUB -->
 [14/stable channel]: https://charmhub.io/postgresql?channel=14/stable
 
-<!-- Snap/Rock -->
+<!-- SNAP/ROCK-->
 [`charmed-postgresql` packaging]: https://github.com/canonical/charmed-postgresql-rock
-
 [rock image]: ghcr.io/canonical/charmed-postgresql@sha256:7ef86a352c94e2a664f621a1cc683d7a983fd86e923d98c32b863f717cb1c173 
 
 [postgresql `v.14.12`]: https://launchpad.net/ubuntu/+source/postgresql-14/14.12-0ubuntu0.22.04.1
@@ -143,7 +162,20 @@ This section contains some technical details about the charm's contents and depe
 [pgBackRest `v.2.48`]: https://launchpad.net/~data-platform/+archive/ubuntu/pgbackrest
 [prometheus-postgres-exporter `v.0.12.1`]: https://launchpad.net/~data-platform/+archive/ubuntu/postgres-exporter
 
-
-<!-- Badges -->
+<!-- EXTERNAL LINKS -->
+[juju]: https://juju.is/docs/juju/
+[lxd]: https://documentation.ubuntu.com/lxd/en/latest/
+[nextcloud]: https://charmhub.io/nextcloud
+[mailman3-core]: https://charmhub.io/mailman3-core
+[data-integrator]: https://charmhub.io/data-integrator
+[s3-integrator]: https://charmhub.io/s3-integrator
+[postgresql-test-app]: https://charmhub.io/postgresql-test-app
+[discourse-k8s]: https://charmhub.io/discourse-k8s
+[indico]: https://charmhub.io/indico
+[microk8s]: https://charmhub.io/microk8s
+[tls-certificates-operator]: https://charmhub.io/tls-certificates-operator
+[self-signed-certificates]: https://charmhub.io/self-signed-certificates
+
+<!-- BADGES (unused) -->
 [amd64]: https://img.shields.io/badge/amd64-darkgreen
 [arm64]: https://img.shields.io/badge/arm64-blue