Documentation Sync with Discourse (#120)

--------- Co-authored-by: Alex Lutay <1928266+taurus-forever@users.noreply.github.com>
canonical · Apr 3, 2023 · a6b8db7 · a6b8db7
1 parent 7e93866
commit a6b8db7
Show file tree

Hide file tree

Showing 22 changed files with 831 additions and 512 deletions.
diff --git a/docs/how-to/h-configure-s3.md b/docs/how-to/h-configure-s3.md
@@ -0,0 +1,23 @@
+# How to configure S3 to work with Charmed PostgreSQL 
+
+Charmed PostgreSQL backup can be stored on any S3 compatible storage. The S3 access and configurations are managed with the [s3-integrator charm](https://charmhub.io/s3-integrator). Deploy and configure the s3-integrator charm:
+```
+juju deploy s3-integrator --channel=edge
+juju run-action s3-integrator/leader sync-s3-credentials access-key=<access-key-here> secret-key=<secret-key-here> --wait
+juju config s3-integrator \
+    path="/postgresql-test" \
+    region="us-west-2" \
+    bucket="postgresql-test-bucket-1" \
+    endpoint="https://s3.amazonaws.com"
+```
+The s3-integrator charm [accepts many configurations](https://charmhub.io/s3-integrator/configure) - enter whatever configurations are necessary for your s3 storage. 
+
+To pass these configurations to Charmed PostgreSQL, relate the two applications:
+```
+juju relate s3-integrator postgresql-k8s
+```
+
+You can also update your configuration options after relating:
+```
+juju config s3-integrator endpoint=<endpoint>
+```
diff --git a/docs/how-to/h-create-and-list-backups.md b/docs/how-to/h-create-and-list-backups.md
@@ -0,0 +1,16 @@
+# How to create and list backups
+
+Creating and listing backups requires that you:
+* [Have a cluster with at least three-nodes deployed](/t/charmed-postgresql-k8s-how-to-manage-units/9592?channel=edge)
+* Access to S3 storage
+* [Have configured settings for S3 storage](/t/charmed-postgresql-k8s-how-to-configure-s3/9595?channel=edge)
+
+Once you have a three-node cluster that has configurations set for S3 storage, check that Charmed PostgreSQL is `active` and `idle` with `juju status`. Once Charmed PostgreSQL is `active` and `idle`, you can create your first backup with the `create-backup` command:
+```
+juju run-action postgresql-k8s/leader create-backup --wait
+```
+
+You can list your available, failed, and in progress backups by running the `list-backups` command:
+```
+juju run-action postgresql-k8s/leader list-backups --wait
+```
diff --git a/docs/how-to/h-enable-encryption.md b/docs/how-to/h-enable-encryption.md
@@ -0,0 +1,53 @@
+# How to enable encryption
+
+Note: The TLS settings here are for self-signed-certificates which are not recommended for production clusters, the `tls-certificates-operator` charm offers a variety of configurations, read more on the TLS charm [here](https://charmhub.io/tls-certificates-operator)
+
+## Enable TLS
+
+```shell
+# deploy the TLS charm
+juju deploy tls-certificates-operator --channel=edge
+# add the necessary configurations for TLS
+juju config tls-certificates-operator generate-self-signed-certificates="true" ca-common-name="Test CA"
+# to enable TLS relate the two applications
+juju relate tls-certificates-operator postgresql-k8s
+```
+
+## Manage keys
+
+Updates to private keys for certificate signing requests (CSR) can be made via the `set-tls-private-key` action. Note passing keys to external/internal keys should *only be done with* `base64 -w0` *not* `cat`. With three replicas this schema should be followed
+
+* Generate a shared internal key
+
+```shell
+openssl genrsa -out internal-key.pem 3072
+```
+
+* generate external keys for each unit
+
+```
+openssl genrsa -out external-key-0.pem 3072
+openssl genrsa -out external-key-1.pem 3072
+openssl genrsa -out external-key-2.pem 3072
+```
+
+* apply both private keys on each unit, shared internal key will be allied only on juju leader
+
+```
+juju run-action postgresql-k8s/0 set-tls-private-key "external-key=$(base64 -w0 external-key-0.pem)"  "internal-key=$(base64 -w0 internal-key.pem)"  --wait
+juju run-action postgresql-k8s/1 set-tls-private-key "external-key=$(base64 -w0 external-key-1.pem)"  "internal-key=$(base64 -w0 internal-key.pem)"  --wait
+juju run-action postgresql-k8s/2 set-tls-private-key "external-key=$(base64 -w0 external-key-2.pem)"  "internal-key=$(base64 -w0 internal-key.pem)"  --wait
+```
+
+* updates can also be done with auto-generated keys with
+
+```
+juju run-action postgresql-k8s/0 set-tls-private-key --wait
+juju run-action postgresql-k8s/1 set-tls-private-key --wait
+juju run-action postgresql-k8s/2 set-tls-private-key --wait
+```
+
+## Disable TLS remove the relation
+```shell
+juju remove-relation tls-certificates-operator postgresql-k8s
+```
diff --git a/docs/how-to/h-manage-app.md b/docs/how-to/h-manage-app.md
@@ -0,0 +1,54 @@
+# How to manage related applications
+
+## New `postgresql_client` interface:
+
+Relations to new applications are supported via the "[postgresql_client](https://github.com/canonical/charm-relation-interfaces/blob/main/interfaces/postgresql_client/v0/README.md)" interface. To create a relation: 
+
+```shell
+juju relate postgresql-k8s application
+```
+
+To remove a relation:
+
+```shell
+juju remove-relation postgresql-k8s application
+```
+
+## Legacy `pgsql` interface:
+
+We have also added support for the database legacy relation from the [original version](https://launchpad.net/postgresql-charm) of the charm via the `pgsql` interface. Please note that these interface is deprecated.
+
+ ```shell
+juju relate postgresql-k8s:db mattermost-k8s:db
+```
+
+Also extended permissions can be requested using `db-admin` edpoint:
+```shell
+juju relate postgresql-k8s:db-admin mattermost-k8s:db
+```
+
+
+## Rotate applications password
+
+To rotate the passwords of users created for related applications, the relation should be removed and related again. That process will generate a new user and password for the application.
+
+```shell
+juju remove-relation application postgresql-k8s
+juju add-relation application postgresql-k8s
+```
+
+### Internal operator user
+
+The operator user is used internally by the Charmed PostgreSQL Operator, the `set-password` action can be used to rotate its password.
+
+* To set a specific password for the operator user
+
+```shell
+juju run-action postgresql-k8s/leader set-password password=<password> --wait
+```
+
+* To randomly generate a password for the operator user
+
+```shell
+juju run-action postgresql-k8s/leader set-password --wait
+```
diff --git a/docs/how-to/h-manage-units.md b/docs/how-to/h-manage-units.md
@@ -0,0 +1,35 @@
+# How to deploy and manage units
+
+## Basic Usage
+
+To deploy a single unit of PostgreSQL using its default configuration
+```shell
+juju deploy postgresql-k8s --channel edge
+```
+
+It is customary to use PostgreSQL with replication. Hence usually more than one unit (preferably an odd number to prohibit a "split-brain" scenario) is deployed. To deploy PostgreSQL with multiple replicas, specify the number of desired units with the `-n` option.
+```shell
+juju deploy postgresql-k8s --channel edge -n <number_of_replicas>
+```
+
+To retrieve primary replica one can use the action `get-primary` on any of the units running postgresql-k8s
+```shell
+juju run-action postgresql-k8s/leader get-primary --wait
+```
+
+Similarly, the primary replica is displayed as a status message in `juju status`, however one should note that this hook gets called on regular time intervals and the primary may be outdated if the status hook has not been called recently. 
+
+Further we highly suggest configuring the status hook to run frequently. In addition to reporting the primary, secondaries, and other statuses, the status hook performs self healing in the case of a network cut. To change the frequency of the update status hook do:
+```shell
+juju model-config update-status-hook-interval=<time(s/m/h)>
+```
+Note that this hook executes a read query to PostgreSQL. On a production level server this should be configured to occur at a frequency that doesn't overload the server with read requests. Similarly the hook should not be configured at too quick of a frequency as this can delay other hooks from running. You can read more about status hooks [here](https://juju.is/docs/sdk/update-status-event).
+
+## Replication
+
+Both scaling-up and scaling-down operations are performed using `juju scale-application`:
+```shell
+juju scale-application postgresql-k8s <desired_num_of_units>
+```
+
+Warning: scaling-down to zero units will destroy your data!
diff --git a/docs/how-to/h-migrate-cluster-via-restore.md b/docs/how-to/h-migrate-cluster-via-restore.md
@@ -0,0 +1,37 @@
+# How to migrate cluster using backups
+
+This is a How-To for restoring a backup that was made from the a *different* cluster, (i.e. cluster migration via restore). To perform a basic restore please reference the [Restore How-To](/t/charmed-postgresql-k8s-how-to-restore-backups/9597?channel=edge)
+
+Restoring a backup from a previous cluster to a current cluster requires that you:
+- Have a single unit Charmed PostgreSQL deployed and running
+- Access to S3 storage
+- [Have configured settings for S3 storage](/t/charmed-postgresql-k8s-how-to-configure-s3/9595?channel=edge)
+- Have the backups from the previous cluster in your S3-storage
+- Have the passwords from your previous cluster
+
+When you restore a backup from an old cluster, it will restore the password from the previous cluster to your current cluster. Set the password of your current cluster to the previous cluster’s password:
+```shell
+juju run-action postgresql-k8s/leader set-password username=operator password=<previous cluster password> --wait
+juju run-action postgresql-k8s/leader set-password username=replication password=<previous cluster password> --wait
+juju run-action postgresql-k8s/leader set-password username=rewind password=<previous cluster password> --wait
+```
+
+To view the available backups to restore you can enter the command `list-backups`:
+```shell
+juju run-action postgresql-k8s/leader list-backups --wait
+```
+
+This shows a list of the available backups (it is up to you to identify which `backup-id` corresponds to the previous-cluster):
+```shell
+    backups: |-
+      backup-id             | backup-type  | backup-status
+      ----------------------------------------------------
+      YYYY-MM-DDTHH:MM:SSZ  | physical     | finished
+```
+
+To restore your current cluster to the state of the previous cluster, run the `restore` command and pass the correct `backup-id` to the command:
+ ```shell
+juju run-action postgresql-k8s/leader restore backup-id=YYYY-MM-DDTHH:MM:SSZ --wait
+```
+
+Your restore will then be in progress, once it is complete your cluster will represent the state of the previous cluster.
diff --git a/docs/how-to/h-restore-backup.md b/docs/how-to/h-restore-backup.md
@@ -0,0 +1,30 @@
+# How to restore backups 
+
+This is a How-To for performing a basic restore (restoring a locally made backup).
+To restore a backup that was made from the a *different* cluster, (i.e. cluster migration via restore), please reference the [Cluster Migration via Restore How-To](/t/charmed-postgresql-k8s-how-to-migrate-clusters/9598?channel=edge):
+
+Restoring from a backup requires that you:
+- [Scale-down to the single PostgreSQL unit (scale it up after the backup is restored)](/t/charmed-postgresql-k8s-how-to-manage-units/9592?channel=edge)
+- Access to S3 storage
+- [Have configured settings for S3 storage](/t/charmed-postgresql-k8s-how-to-configure-s3/9595?channel=edge)
+- [Have existing backups in your S3-storage](/t/charmed-postgresql-k8s-how-to-create-and-list-backups/9596?channel=edge)
+
+To view the available backups to restore you can enter the command `list-backups`:
+```shell
+juju run-action postgresql-k8s/leader list-backups --wait
+```
+
+This should show your available backups
+```shell
+    backups: |-
+      backup-id             | backup-type  | backup-status
+      ----------------------------------------------------
+      YYYY-MM-DDTHH:MM:SSZ  | physical     | finished
+```
+
+To restore a backup from that list, run the `restore` command and pass the `backup-id` to restore:
+ ```shell
+juju run-action postgresql-k8s/leader restore backup-id=YYYY-MM-DDTHH:MM:SSZ --wait
+```
+
+Your restore will then be in progress.
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,55 @@
+## Charmed PostgreSQL K8s Documentation
+
+The Charmed PostgreSQL K8s Operator delivers automated operations management from day 0 to day 2 on the [PostgreSQL Database Management System](https://www.postgresql.org/). It is an open source, end-to-end, production-ready data platform on top of [Juju](https://juju.is/).
+
+PostgreSQL is a powerful, open source object-relational database system that uses and extends the SQL language combined with many features that safely store and scale the most complicated data workloads.
+
+The Charmed PostgreSQL K8s operator comes in two flavours to deploy and operate PostgreSQL on [physical/virtual machines](https://github.com/canonical/postgresql-operator) and [Kubernetes](https://github.com/canonical/postgresql-k8s-operator). Both offer features such as replication, TLS, password rotation, and easy to use integration with applications. The Charmed PostgreSQL K8s Operator meets the need of deploying PostgreSQL in a structured and consistent manner while allowing the user flexibility in configuration. It simplifies deployment, scaling, configuration and management of PostgreSQL in production at scale in a reliable way.
+
+## Project and community
+Charmed PostgreSQL K8s is an official distribution of PostgreSQL. It’s an open-source project that welcomes community contributions, suggestions, fixes and constructive feedback.
+- [Read our Code of Conduct](https://ubuntu.com/community/code-of-conduct)
+- [Join the Discourse forum](https://discourse.charmhub.io/tag/postgresql)
+- Contribute and report bugs to [machine](https://github.com/canonical/postgresql-operator) and [K8s](https://github.com/canonical/postgresql-k8s-operator) operators
+
+## In this documentation
+| | |
+|--|--|
+|  [Tutorials -- Coming Soon]()</br>  Get started - a hands-on introduction to using Charmed PostgreSQL K8s operator for new users </br> |  [How-to guides -- Coming Soon]() </br> Step-by-step guides covering key operations and common tasks |
+| [Reference -- Coming Soon]() </br> Technical information - specifications, APIs, architecture | [Explanation -- Coming Soon]() </br> Concepts - discussion and clarification of key topics  |
+
+# Navigation
+
+| Level | Path                          | Navlink                                                                                                           |
+| ----- |-------------------------------|-------------------------------------------------------------------------------------------------------------------|
+| 1 | tutorial                      | [Tutorial]()                                                                                                      |
+| 2 | t-overview                    | [1. Introduction](/t/charmed-postgresql-k8s-tutorial-overview/9296)                                               |
+| 2 | t-setup-environment           | [2. Set up the environment](/t/charmed-postgresql-k8s-tutorial-setup-environment/9297)                            |
+| 2 | t-deploy-postgresql           | [3. Deploy PostgreSQL](/t/charmed-postgresql-k8s-tutorial-deploy/9298)                                            |
+| 2 | t-managing-units              | [4. Manage your units](/t/charmed-postgresql-k8s-tutorial-managing-units/9299)                                    |
+| 2 | t-manage-passwords            | [5. Manage passwords](/t/charmed-postgresql-k8s-tutorial-manage-passwords/9300)                                   |
+| 2 | t-integrations                | [6. Relate your PostgreSQL to other applications](/t/charmed-postgresql-k8s-tutorial-integrations/9301)           |
+| 2 | t-enable-security             | [7. Enable security](/t/charmed-postgresql-k8s-tutorial-enable-security/9302)                                     |
+| 2 | t-cleanup-environment         | [8. Cleanup your environment](/t/charmed-postgresql-k8s-tutorial-cleanup/9303)                                    |
+| 1 | how-to                        | [How To]()                                                                                                        |
+| 2 | h-manage-units                | [Manage units](/t/charmed-postgresql-k8s-how-to-manage-units/9592)                                                |
+| 2 | h-enable-encryption           | [Enable encryption](/t/charmed-postgresql-k8s-how-to-enable-encryption/9593)                                      |
+| 2 | h-manage-app                  | [Manage applications](/t/charmed-postgresql-k8s-how-to-manage-applications/9594)                                  |
+| 2 | h-configure-s3                | [Configure S3](/t/charmed-postgresql-k8s-how-to-configure-s3/9595)                                                |
+| 2 | h-create-and-list-backups     | [Create and List Backups](/t/charmed-postgresql-k8s-how-to-create-and-list-backups/9596)                          |
+| 2 | h-restore-backup              | [Restore a Backup](/t/charmed-postgresql-k8s-how-to-restore-backups/9597)                                         |
+| 2 | h-migrate-cluster-via-restore | [Cluster Migration with Restore](/t/charmed-postgresql-k8s-how-to-migrate-clusters/9598)                          |
+| 1 | reference                     | [Reference]()                                                                                                     |
+| 2 | r-requirements                | [Requirements](/t/charmed-postgresql-k8s-reference-requirements/9304)                                             |
+| 2 | r-charm                       | [Charm API](/t/charmed-postgresql-k8s-reference-charm-api/9305)                                                   |
+| 2 | r-peers                       | [Peer Relation](/t/charmed-postgresql-k8s-reference-peer-relation/9306)                                           |
+| 2 | r-actions                     | [Actions](https://charmhub.io/postgresql-k8s/actions)                                                             |
+| 2 | r-configurations              | [Configurations](https://charmhub.io/postgresql-k8s/configure)                                                    |
+| 2 | r-libraries                   | [Libraries](https://charmhub.io/postgresql-k8s/libraries/helpers)                                                 |
+
+# Redirects
+
+[details=Mapping table]
+| Path | Location |
+| ---- | -------- |
+[/details]