From 612240e2d3ae65fe4ecc7e9f7f0b995792fd6c36 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 26 Sep 2024 01:01:17 +0300 Subject: [PATCH] Sync docs from Discourse (#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 --- .github/workflows/sync_docs.yaml | 2 +- docs/how-to/h-restore-backup.md | 50 ++++++++++++++--- docs/overview.md | 3 +- docs/reference/r-all-releases.md | 30 ----------- docs/reference/r-releases.md | 65 ++++++++++++++++++++++ docs/reference/r-revision-381-382.md | 80 +++++++++++++++++++--------- 6 files changed, 167 insertions(+), 63 deletions(-) delete mode 100644 docs/reference/r-all-releases.md create mode 100644 docs/reference/r-releases.md diff --git a/.github/workflows/sync_docs.yaml b/.github/workflows/sync_docs.yaml index b0eebc9a98..4e48da8e3d 100644 --- 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/sync_docs.yaml@v22.0.0 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 index e22e34e2e8..8556634144 100644 --- 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. \ No newline at end of file diff --git a/docs/overview.md b/docs/overview.md index 853c6c828b..5db79d55fd 100644 --- 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 deleted file mode 100644 index 12657010b8..0000000000 --- a/docs/reference/r-all-releases.md +++ /dev/null @@ -1,30 +0,0 @@ -# Release Notes - -Here you will find release notes for major revisions of this charm that are available in the [Charmhub `stable` channel](https://juju.is/docs/juju/channel#heading--risk). - -To see **all** charm revisions, check the [Charmed PostgreSQL K8s Releases page](https://github.com/canonical/postgresql-k8s-operator/releases) on GitHub. - -## At a glance - -The table below is a high-level overview of the architectures and integrations that are supported by each charm revision. - -| Revision | PostgreSQL | amd64 | arm64 | [TLS encryption](/t/9685)* | [Monitoring (COS, Grafana)](/t/10600) | [Tracing (Tempo K8s)](/t/14521) | -|:--------:|:-----:|:-----:|:-----:|:--------------------:|:---------------:|:--------------------:| -| [382](/t/15442) | 14.12 | :heavy_multiplication_x: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| [381](/t/15442) | 14.12 | :white_check_mark: | :heavy_multiplication_x: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| [281](/t/14068) | 14.11 | :white_check_mark: | :heavy_multiplication_x: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| [280](/t/14068) | 14.11 | :heavy_multiplication_x: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| [193](/t/13208) | 14.10 | :white_check_mark: | :heavy_multiplication_x: | :white_check_mark: | :white_check_mark: | :heavy_multiplication_x: | -| [177](/t/12668) | 14.9 | :white_check_mark: | :heavy_multiplication_x: | :heavy_multiplication_x: | :white_check_mark: | :heavy_multiplication_x: | -| [158](/t/11874) | 14.9 | :white_check_mark: | :heavy_multiplication_x: | :heavy_multiplication_x: | :white_check_mark: | :heavy_multiplication_x: | -| [73](/t/11873) | 14.7 | :white_check_mark: | :heavy_multiplication_x: | :heavy_multiplication_x: | :heavy_multiplication_x: | :heavy_multiplication_x: | - - -**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. - -### Plugins/extensions - -For a list of all plugins supported for each revision, see the reference page [Plugins/extensions](/t/10945). \ No newline at end of file diff --git a/docs/reference/r-releases.md b/docs/reference/r-releases.md new file mode 100644 index 0000000000..95759d91d6 --- /dev/null +++ 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] + + +[382]: /t/15442 +[381]: /t/15442 +[281]: /t/14068 +[280]: /t/14068 +[193]: /t/13208 +[177]: /t/12668 +[158]: /t/11874 +[73]: /t/11873 + + +[check]: https://img.icons8.com/color/20/checkmark--v1.png \ No newline at end of file diff --git a/docs/reference/r-revision-381-382.md b/docs/reference/r-revision-381-382.md index 3e59304da9..5b8d325f04 100644 --- 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 `` 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.
-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] - + [All revisions]: /t/11872 [system requirements]: /t/11744 - + [`/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 - + [14/stable channel]: https://charmhub.io/postgresql?channel=14/stable - + [`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 - - + +[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 + + [amd64]: https://img.shields.io/badge/amd64-darkgreen [arm64]: https://img.shields.io/badge/arm64-blue \ No newline at end of file