diff --git a/.github/workflows/sync_docs.yaml b/.github/workflows/sync_docs.yaml new file mode 100644 index 0000000000..7cf2ccfa28 --- /dev/null +++ b/.github/workflows/sync_docs.yaml @@ -0,0 +1,19 @@ +# Copyright 2024 Canonical Ltd. +# See LICENSE file for licensing details. +name: Sync docs from Discourse + +on: + workflow_dispatch: + schedule: + - cron: 00 01 * * * + +jobs: + sync-docs: + name: Sync docs from Discourse + uses: canonical/data-platform-workflows/.github/workflows/_sync_docs.yaml@main + secrets: + discourse-api-user: ${{ secrets.DISCOURSE_API_USERNAME }} + discourse-api-key: ${{ secrets.DISCOURSE_API_KEY }} + permissions: + contents: write # Needed to push branch & tag + pull-requests: write # Needed to create PR diff --git a/docs/explanation/e-interfaces.md b/docs/explanation/e-interfaces.md deleted file mode 100644 index 251298b63a..0000000000 --- a/docs/explanation/e-interfaces.md +++ /dev/null @@ -1,46 +0,0 @@ -# Interfaces/endpoints - -The charm supports modern `postgresql_client` and legacy `pgsql` interfaces (in a backward compatible mode). - -**Note:** do NOT relate both modern and legacy interfaces simultaneously! - -## Modern interfaces - -This charm provides modern ['postgresql_client' interface](https://github.com/canonical/charm-relation-interfaces). Applications can easily connect PostgreSQL using ['data_interfaces' ](https://charmhub.io/data-platform-libs/libraries/data_interfaces) library from ['data-platform-libs'](https://github.com/canonical/data-platform-libs/). - -### Modern `postgresql_client` interface (`database` endpoint): - -Adding a relation is accomplished with `juju relate` (or `juju integrate` for Juju 3.x) via endpoint `database`. Example: - -```shell -# Deploy Charmed PostgreSQL cluster with 3 nodes -juju deploy postgresql -n 3 --channel 14 - -# Deploy the relevant application charms -juju deploy mycharm - -# Relate PostgreSQL with your application -juju relate postgresql-k8s:database mycharm:database - -# Check established relation (using postgresql_client interface): -juju status --relations - -# Example of the properly established relation: -# > Relation provider Requirer Interface Type -# > postgresql:database mycharm:database postgresql_client regular -``` - -## Legacy interfaces - -**Note:** Legacy relations are deprecated and will be discontinued on future releases. Usage should be avoided. - -### Legacy `pgsql` interface (`db` and `db-admin` endpoints): - -This charm supports legacy interface `pgsql` from the previous [PostgreSQL charm](https://launchpad.net/postgresql-charm): - -```shell -juju relate postgresql:db mailman3-core -juju relate postgresql:db-admin landscape-server -``` - -**Note:** The endpoint `db-admin` provides the same legacy interface `pgsql` with PostgreSQL admin-level privileges. It is NOT recommended to use it from security point of view. \ No newline at end of file diff --git a/docs/how-to/h-configure-s3-aws.md b/docs/how-to/h-configure-s3-aws.md deleted file mode 100644 index dc49428e79..0000000000 --- a/docs/how-to/h-configure-s3-aws.md +++ /dev/null @@ -1,31 +0,0 @@ -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 for **[AWS S3](https://aws.amazon.com/s3/)** (click [here](/t/charmed-postgresql-how-to-configure-s3-for-radosgw/10313) to backup on Ceph via RadosGW): -```shell -juju deploy s3-integrator -juju run-action s3-integrator/leader sync-s3-credentials access-key=<access-key-here> secret-key=<secret-key-here> --wait -juju config s3-integrator \ - endpoint="https://s3.amazonaws.com" \ - bucket="postgresql-test-bucket-1" \ - path="/postgresql-test" \ - region="us-west-2" -``` - -To pass these configurations to Charmed PostgreSQL, relate the two applications: -```shell -juju relate s3-integrator postgresql -``` - -You can create/list/restore backups now: - -```shell -juju run-action postgresql/leader list-backups --wait -juju run-action postgresql/leader create-backup --wait -juju run-action postgresql/leader list-backups --wait -juju run-action postgresql/leader restore backup-id=<backup-id-here> --wait -``` - -You can also update your S3 configuration options after relating, using: -```shell -juju config s3-integrator <option>=<value> -``` - -The s3-integrator charm [accepts many configurations](https://charmhub.io/s3-integrator/configure) - enter whatever configurations are necessary for your S3 storage. \ No newline at end of file diff --git a/docs/how-to/h-configure-s3-radosgw.md b/docs/how-to/h-configure-s3-radosgw.md deleted file mode 100644 index e5b4fae5e5..0000000000 --- a/docs/how-to/h-configure-s3-radosgw.md +++ /dev/null @@ -1,36 +0,0 @@ -Charmed PostgreSQL backup can be stored on any S3 compatible storage, e.g. on [Ceph](https://ceph.com/en/) via [RadosGW](https://docs.ceph.com/en/latest/man/8/radosgw/). The S3 access and configurations are managed with the [s3-integrator charm](https://charmhub.io/s3-integrator). Deploy and configure the s3-integrator charm for **RadosGW** (click [here](/t/charmed-postgresql-how-to-configure-s3/9681) to backup on AWS S3): -```shell -# Install MinIO client and create a bucket: -mc config host add dest https://radosgw.mycompany.fqdn <access-key> <secret-key> --api S3v4 --lookup path -mc mb dest/backups-bucket - -juju deploy s3-integrator -juju run-action s3-integrator/leader sync-s3-credentials access-key=<access-key> secret-key=<secret-key> --wait -juju config s3-integrator \ - endpoint="https://radosgw.mycompany.fqdn" \ - bucket="backups-bucket" \ - path="/postgresql" \ - region="" \ - s3-api-version="" \ - s3-uri-style="path" -``` - -To pass these configurations to Charmed PostgreSQL, relate the two applications: -```shell -juju relate s3-integrator postgresql -``` - -You can create/list/restore backups now: - -```shell -juju run-action postgresql/leader list-backups --wait -juju run-action postgresql/leader create-backup --wait -juju run-action postgresql/leader list-backups --wait -juju run-action postgresql/leader restore backup-id=<backup-id-here> --wait -``` - -You can also update your S3 configuration options after relating, using: -```shell -juju config s3-integrator <option>=<value> -``` -The s3-integrator charm [accepts many configurations](https://charmhub.io/s3-integrator/configure) - enter whatever configurations are necessary for your S3 storage. \ No newline at end of file diff --git a/docs/how-to/h-create-and-list-backups.md b/docs/how-to/h-create-and-list-backups.md deleted file mode 100644 index bc8e30c4e2..0000000000 --- a/docs/how-to/h-create-and-list-backups.md +++ /dev/null @@ -1,14 +0,0 @@ -Creating and listing backups requires that you: -* [Have a cluster with at least three-nodes deployed](/t/charmed-postgresql-how-to-manage-units/9689?channel=14/stable) -* Access to S3 storage -* [Have configured settings for S3 storage](/t/charmed-postgresql-how-to-configure-s3/9681?channel=14/stable) - -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/leader create-backup --wait -``` - -You can list your available, failed, and in progress backups by running the `list-backups` command: -``` -juju run-action postgresql/leader list-backups --wait -``` \ No newline at end of file diff --git a/docs/how-to/h-enable-encryption.md b/docs/how-to/h-enable-encryption.md deleted file mode 100644 index 15cd58a583..0000000000 --- a/docs/how-to/h-enable-encryption.md +++ /dev/null @@ -1,55 +0,0 @@ -# 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 - -# 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 -``` - -## 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/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/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/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/0 set-tls-private-key --wait -juju run-action postgresql/1 set-tls-private-key --wait -juju run-action postgresql/2 set-tls-private-key --wait -``` - -## Disable TLS remove the relation -```shell -juju remove-relation tls-certificates-operator postgresql -``` \ No newline at end of file diff --git a/docs/how-to/h-enable-monitoring.md b/docs/how-to/h-enable-monitoring.md deleted file mode 100644 index 2c18aa5c6a..0000000000 --- a/docs/how-to/h-enable-monitoring.md +++ /dev/null @@ -1,106 +0,0 @@ -# How to enable monitoring - -[note type="positive"] -**Warning:** The feature is currently being developed and will be available in the `14/stable` channel soon. -Please contact Canonical Data team to test it from your side as experimental feature. -[/note] - -Creating and listing backups requires that you: -* [Have a Charmed Postgresql deployed](/t/charmed-postgresql-tutorial-deploy-postgresql/9697?channel=14/edge) -* [Deploy `cos-lite` bundle in a Kubernetes environment](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s) - -Switch to COS K8s environment and offer COS interfaces to be cross-model related with Charmed Postgresql VM model: -```shell -# Switch to Kubernetes controller, for the cos model. -juju switch <k8s_controller>:<cos_model_name> - -juju offer grafana.grafana-dashboards grafana-dashboards -juju offer loki:logging loki-logging -juju offer prometheus:receive-remote-write prometheus-receive-remote-write -``` - -Switch to Charmed Postgresql VM model, find offers and relate with them: -```shell -# We are on the Kubernetes controller, for the cos model. Switch to postgresql model -juju switch <machine_controller_name>:<postgresql_model_name> - -juju find-offers <k8s_controller>: -``` - -A similar output should appear, if `k8s` is the k8s controller name and `cos` the model where `cos-lite` has been deployed: -```shell -Store URL Access Interfaces -k8s admin/cos.grafana-dashboards admin grafana_dashboard:grafana-dashboard -k8s admin/cos.loki-logging admin loki_push_api:logging -k8s admin/cos.prometheus-receive-remote-write admin prometheus-receive-remote-write:receive-remote-write -... -``` - -Consume offers to be reachable in the current model: -```shell -juju consume k8s:admin/cos.prometheus-receive-remote-write -juju consume k8s:admin/cos.loki-logging -juju consume k8s:admin/cos.grafana-dashboards -``` - -Now, deploy `grafana-agent` (subordinate charm) and relate it with Charmed Postgresql, later relate `grafana-agent` with consumed COS offers: -```shell -juju deploy grafana-agent -juju relate postgresql:cos-agent grafana-agent -juju relate grafana-agent grafana-dashboards -juju relate grafana-agent loki-logging -juju relate grafana-agent prometheus-receive-remote-write -``` - -After this is complete, Grafana will show the new dashboards: `Postgresql Exporter` and allows access for Charmed Postgresql logs on Loki. - -The example of `juju status` on Charmed Postgresql VM model: -```shell -ubuntu@localhost:~$ juju status -Model Controller Cloud/Region Version SLA Timestamp -vmmodel local localhost/localhost 2.9.42 unsupported 00:12:18+02:00 - -SAAS Status Store URL -grafana-dashboards active k8s admin/cos.grafana-dashboards -loki-logging active k8s admin/cos.loki-logging -prometheus-receive-remote-write active k8s admin/cos.prometheus-receive-remote-write - -App Version Status Scale Charm Channel Rev Exposed Message -grafana-agent active 1 grafana-agent edge 5 no -postgresql 14.7 active 1 postgresql 14/edge 296 no Primary - -Unit Workload Agent Machine Public address Ports Message -postgresql/3* active idle 4 10.85.186.140 Primary - grafana-agent/0* active idle 10.85.186.140 - -Machine State Address Inst id Series AZ Message -4 started 10.85.186.140 juju-fcde9e-4 jammy Running -``` - -The example of `juju status` on COS K8s model: -```shell -ubuntu@localhost:~$ juju status -Model Controller Cloud/Region Version SLA Timestamp -cos k8s microk8s/localhost 2.9.42 unsupported 00:15:31+02:00 - -App Version Status Scale Charm Channel Rev Address Exposed Message -alertmanager 0.23.0 active 1 alertmanager-k8s stable 47 10.152.183.206 no -catalogue active 1 catalogue-k8s stable 13 10.152.183.183 no -grafana 9.2.1 active 1 grafana-k8s stable 64 10.152.183.140 no -loki 2.4.1 active 1 loki-k8s stable 60 10.152.183.241 no -prometheus 2.33.5 active 1 prometheus-k8s stable 103 10.152.183.240 no -traefik 2.9.6 active 1 traefik-k8s stable 110 10.76.203.178 no - -Unit Workload Agent Address Ports Message -alertmanager/0* active idle 10.1.84.125 -catalogue/0* active idle 10.1.84.127 -grafana/0* active idle 10.1.84.83 -loki/0* active idle 10.1.84.79 -prometheus/0* active idle 10.1.84.96 -traefik/0* active idle 10.1.84.119 - -Offer Application Charm Rev Connected Endpoint Interface Role -grafana-dashboards grafana grafana-k8s 64 1/1 grafana-dashboard grafana_dashboard requirer -loki-logging loki loki-k8s 60 1/1 logging loki_push_api provider -prometheus-receive-remote-write prometheus prometheus-k8s 103 1/1 receive-remote-write prometheus_remote_write provider -``` \ No newline at end of file diff --git a/docs/how-to/h-manage-app.md b/docs/how-to/h-manage-app.md deleted file mode 100644 index 52b9d51673..0000000000 --- a/docs/how-to/h-manage-app.md +++ /dev/null @@ -1,54 +0,0 @@ -# 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 application -``` - -To remove a relation: - -```shell -juju remove-relation postgresql 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:db mailman3-core -``` - -Also extended permissions can be requested using `db-admin` edpoint: -```shell -juju relate postgresql:db-admin mailman3-core -``` - - -## 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 -juju add-relation application postgresql -``` - -### 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/leader set-password password=<password> --wait -``` - -* To randomly generate a password for the operator user - -```shell -juju run-action postgresql/leader set-password --wait -``` \ No newline at end of file diff --git a/docs/how-to/h-manage-units.md b/docs/how-to/h-manage-units.md deleted file mode 100644 index d592cab09c..0000000000 --- a/docs/how-to/h-manage-units.md +++ /dev/null @@ -1,40 +0,0 @@ -# How to deploy and manage units - -## Basic Usage - -To deploy a single unit of PostgreSQL using its default configuration -```shell -juju deploy postgresql --channel 14/stable -``` - -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 --channel 14/stable -n <number_of_replicas> -``` - -To retrieve primary replica one can use the action `get-primary` on any of the units running postgresql: -```shell -juju run-action postgresql/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 - -To scaling-up the cluster, use `juju add-unit`: -```shell -juju add-unit postgresql --num-units <amount_of_units_to_add> -``` - -To scaling-down the cluster, use `juju remove-unit`: -```shell -juju remove-unit postgresql/<unit_id_to_remove> -``` - -Warning: do NOT remove the last unit, it will destroy your data! \ No newline at end of file diff --git a/docs/how-to/h-migrate-cluster-via-restore.md b/docs/how-to/h-migrate-cluster-via-restore.md deleted file mode 100644 index 1ffdef2c4d..0000000000 --- a/docs/how-to/h-migrate-cluster-via-restore.md +++ /dev/null @@ -1,35 +0,0 @@ -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-how-to-restore-backup/9693?channel=14/stable) - -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-how-to-configure-s3/9681?channel=14/stable) -- 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/leader set-password username=operator password=<previous cluster password> --wait -juju run-action postgresql/leader set-password username=replication password=<previous cluster password> --wait -juju run-action postgresql/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/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/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. \ No newline at end of file diff --git a/docs/how-to/h-restore-backup.md b/docs/how-to/h-restore-backup.md deleted file mode 100644 index e9e32c5a9e..0000000000 --- a/docs/how-to/h-restore-backup.md +++ /dev/null @@ -1,28 +0,0 @@ -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-how-to-migrate-cluster-via-restore/9691?channel=14/stable): - -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-how-to-manage-units/9689?channel=14/stable) -- Access to S3 storage -- [Have configured settings for S3 storage](/t/charmed-postgresql-how-to-configure-s3/9681?channel=14/stable) -- [Have existing backups in your S3-storage](/t/charmed-postgresql-how-to-create-and-list-backups/9683?channel=14/stable) - -To view the available backups to restore you can enter the command `list-backups`: -```shell -juju run-action postgresql/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/leader restore backup-id=YYYY-MM-DDTHH:MM:SSZ --wait -``` - -Your restore will then be in progress. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index a248a30c9c..0000000000 --- a/docs/index.md +++ /dev/null @@ -1,59 +0,0 @@ -The Charmed PostgreSQL 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 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 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 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](/t/charmed-postgresql-tutorial-overview/9707?channel=14/stable)</br> Get started - a hands-on introduction to using Charmed PostgreSQL operator for new users </br> | [How-to guides](/t/charmed-postgresql-how-to-manage-units/9689?channel=14/stable) </br> Step-by-step guides covering key operations and common tasks | -| [Reference](https://charmhub.io/postgresql/actions?channel=14/stable) </br> Technical information - specifications, APIs, architecture | [Explanation](/t/charmed-postgresql-explanations-interfaces-endpoints/10251?channel=14/stable) </br> Concepts - discussion and clarification of key topics | - -# Navigation - -| Level | Path | Navlink | -|-------|-------------------------------|-----------------------------------------------------------------------------------------------------| -| 1 | tutorial | [Tutorial]() | -| 2 | t-overview | [1. Introduction](/t/charmed-postgresql-tutorial-overview/9707) | -| 2 | t-setup-environment | [2. Set up the environment](/t/charmed-postgresql-tutorial-setup-environment/9709) | -| 2 | t-deploy-postgresql | [3. Deploy PostgreSQL](/t/charmed-postgresql-tutorial-deploy-postgresql/9697) | -| 2 | t-managing-units | [4. Manage your units](/t/charmed-postgresql-tutorial-managing-units/9705) | -| 2 | t-manage-passwords | [5. Manage passwords](/t/charmed-postgresql-tutorial-manage-passwords/9703) | -| 2 | t-integrations | [6. Relate your PostgreSQL to other applications](/t/charmed-postgresql-tutorial-integrations/9701) | -| 2 | t-enable-security | [7. Enable security](/t/charmed-postgresql-tutorial-enable-security/9699) | -| 2 | t-cleanup-environment | [8. Cleanup your environment](/t/charmed-postgresql-tutorial-cleanup-environment/9695) | -| 1 | how-to | [How To]() | -| 2 | h-manage-units | [Manage units](/t/charmed-postgresql-how-to-manage-units/9689) | -| 2 | h-enable-encryption | [Enable encryption](/t/charmed-postgresql-how-to-enable-encryption/9685) | -| 2 | h-manage-app | [Manage applications](/t/charmed-postgresql-how-to-manage-app/9687) | -| 2 | h-configure-s3-aws | [Configure S3 AWS](/t/charmed-postgresql-how-to-configure-s3-for-aws/9681) | -| 2 | h-configure-s3-radosgw | [Configure S3 RadosGW](/t/charmed-postgresql-how-to-configure-s3-for-radosgw/10313) | -| 2 | h-create-and-list-backups | [Create and List Backups](/t/charmed-postgresql-how-to-create-and-list-backups/9683) | -| 2 | h-restore-backup | [Restore a Backup](/t/charmed-postgresql-how-to-restore-backup/9693) | -| 2 | h-migrate-cluster-via-restore | [Cluster Migration with Restore](/t/charmed-postgresql-how-to-migrate-cluster-via-restore/9691) | -| 2 | h-enable-monitoring | [Enable Monitoring](/t/charmed-postgresql-explanations-enable-monitoring/10600) | -| 1 | reference | [Reference]() | -| 2 | r-actions | [Actions](https://charmhub.io/postgresql/actions) | -| 2 | r-configurations | [Configurations](https://charmhub.io/postgresql/configure) | -| 2 | r-libraries | [Libraries](https://charmhub.io/postgresql/libraries) | -| 2 | r-integrations | [Integrations](https://charmhub.io/postgresql/integrations) | -| 1 | explanation | [Explanation]() | -| 2 | e-interfaces | [Interfaces/endpoints](/t/charmed-postgresql-explanations-interfaces-endpoints/10251) | - - - -# Redirects - -[details=Mapping table] -| Path | Location | -| ---- | -------- | -[/details] \ No newline at end of file diff --git a/docs/reference/.gitkeep b/docs/reference/.gitkeep deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/tutorial/t-cleanup-environment.md b/docs/tutorial/t-cleanup-environment.md deleted file mode 100644 index 4b611dca8a..0000000000 --- a/docs/tutorial/t-cleanup-environment.md +++ /dev/null @@ -1,20 +0,0 @@ -# Cleanup and extra info - -This is part of the [Charmed PostgreSQL Tutorial](/t/charmed-postgresql-tutorial-overview/9707?channel=14/stable). Please refer to this page for more information and the overview of the content. - -## Remove Multipass VM -If you're done with testing and would like to free up resources on your machine, just remove Multipass VM. -*Warning: when you remove VM as shown below you will lose all the data in PostgreSQL and any other applications inside Multipass VM!* -```shell -multipass delete --purge my-vm -``` - -## Next Steps - -In this tutorial we've successfully deployed PostgreSQL, added/removed cluster members, added/removed users to/from the database, and even enabled and disabled TLS. You may now keep your Charmed PostgreSQL deployment running and write to the database or remove it entirely using the steps in [Remove Charmed PostgreSQL and Juju](#remove-charmed-postgresql-and-juju). If you're looking for what to do next you can: -- Run [Charmed PostgreSQL on Kubernetes](https://github.com/canonical/postgresql-k8s-operator). -- Check out our Charmed offerings of [MySQL](https://charmhub.io/mysql) and [Kafka](https://charmhub.io/kafka?channel=edge). -- Read about [High Availability Best Practices](https://canonical.com/blog/database-high-availability) -- [Report](https://github.com/canonical/postgresql-operator/issues) any problems you encountered. -- [Give us your feedback](https://chat.charmhub.io/charmhub/channels/data-platform). -- [Contribute to the code base](https://github.com/canonical/postgresql-operator) \ No newline at end of file diff --git a/docs/tutorial/t-deploy-postgresql.md b/docs/tutorial/t-deploy-postgresql.md deleted file mode 100644 index 840599e1b8..0000000000 --- a/docs/tutorial/t-deploy-postgresql.md +++ /dev/null @@ -1,109 +0,0 @@ -# Get a Charmed PostgreSQL up and running - -This is part of the [Charmed PostgreSQL Tutorial](/t/charmed-postgresql-tutorial-overview/9707?channel=14/stable). Please refer to this page for more information and the overview of the content. - -## Deploy Charmed PostgreSQL - -To deploy Charmed PostgreSQL, all you need to do is run the following command, which will fetch the charm from [Charmhub](https://charmhub.io/postgresql?channel=14/stable) and deploy it to your model: -```shell -juju deploy postgresql --channel 14/stable -``` - -Juju will now fetch Charmed PostgreSQL and begin deploying it to the LXD cloud. This process can take several minutes depending on how provisioned (RAM, CPU, etc) your machine is. You can track the progress by running: -```shell -juju status --watch 1s -``` - -This command is useful for checking the status of Charmed PostgreSQL and gathering information about the machines hosting Charmed PostgreSQL. Some of the helpful information it displays include IP addresses, ports, state, etc. The command updates the status of Charmed PostgreSQL every second and as the application starts you can watch the status and messages of Charmed PostgreSQL change. Wait until the application is ready - when it is ready, `juju status` will show: -``` -Model Controller Cloud/Region Version SLA Timestamp -tutorial overlord localhost/localhost 2.9.42 unsupported 09:41:53+01:00 - -App Version Status Scale Charm Channel Rev Exposed Message -postgresql active 1 postgresql 14/stable 281 no - -Unit Workload Agent Machine Public address Ports Message -postgresql/0* active idle 0 10.89.49.129 - -Machine State Address Inst id Series AZ Message -0 started 10.89.49.129 juju-a8a31d-0 jammy Running -``` -To exit the screen with `juju status --watch 1s`, enter `Ctrl+c`. -If you want to further inspect juju logs, can watch for logs with `juju debug-log`. -More info on logging at [juju logs](https://juju.is/docs/olm/juju-logs). - -## Access PostgreSQL -> **!** *Disclaimer: this part of the tutorial accesses PostgreSQL via the `operator` user. **Do not** directly interface with this user in a production environment. In a production environment always create a separate user using [Data Integrator](https://charmhub.io/data-integrator) and connect to PostgreSQL with that user instead. Later in the section covering Relations we will cover how to access PostgreSQL without the `operator` user.* - -The first action most users take after installing PostgreSQL is accessing PostgreSQL. The easiest way to do this is via the [PostgreSQL interactive terminal](https://www.postgresql.org/docs/14/app-psql.html) `psql`. Connecting to the database requires that you know the values for `host`, `username` and `password`. To retrieve the necessary fields please run Charmed PostgreSQL action `get-password`: -```shell -juju run-action postgresql/leader get-password --wait -``` -Running the command should output: -```yaml -unit-postgresql-0: - UnitId: postgresql/0 - id: "2" - results: - operator-password: <password> - status: completed - timing: - completed: 2023-03-20 08:42:22 +0000 UTC - enqueued: 2023-03-20 08:42:19 +0000 UTC - started: 2023-03-20 08:42:21 +0000 UTC -``` - -*Note: to request a password for a different user, use an option `username`:* -```shell -juju run-action postgresql/leader get-password username=replication --wait -``` - -The host’s IP address can be found with `juju status` (the unit hosting the PostgreSQL application): -``` -... -Unit Workload Agent Machine Public address Ports Message -postgresql/0* active idle 0 10.89.49.129 -... -``` - -To access the units hosting Charmed PostgreSQL use: -```shell -juju ssh postgresql/leader -``` -*Note: if at any point you'd like to leave the unit hosting Charmed PostgreSQL, enter* `Ctrl+d` or type `exit`*. - -The `psql` tool is already installed here. To show list of all available databases use: -```shell -psql --host=10.89.49.129 --username=operator --password --list -``` -*Note: when requested, enter the `<password>` for charm user `operator` from the output above.* - -The example of the output: -``` - List of databases - Name | Owner | Encoding | Collate | Ctype | Access privileges ------------+----------+----------+---------+---------+----------------------- - postgres | operator | UTF8 | C.UTF-8 | C.UTF-8 | - template0 | operator | UTF8 | C.UTF-8 | C.UTF-8 | =c/operator + - | | | | | operator=CTc/operator - template1 | operator | UTF8 | C.UTF-8 | C.UTF-8 | =c/operator + - | | | | | operator=CTc/operator -(3 rows) -``` - -You can now interact with PostgreSQL directly using any [PostgreSQL SQL Queries](https://www.postgresql.org/docs/14/queries.html). For example entering `SELECT version();` should output something like: -``` -> psql --host=10.89.49.129 --username=operator --password postgres -Password: -psql (14.7 (Ubuntu 14.7-0ubuntu0.22.04.1)) -Type "help" for help. - -postgres=# SELECT version(); - version --------------------------------------------------------------------------------------------------------------------------------------- - PostgreSQL 14.7 (Ubuntu 14.7-0ubuntu0.22.04.1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.3.0-1ubuntu1~22.04) 11.3.0, 64-bit -(1 row) -``` -*Note: if at any point you'd like to leave the PostgreSQL client, enter `Ctrl+d` or type `exit`*. - -Feel free to test out any other PostgreSQL queries. When you’re ready to leave the PostgreSQL shell you can just type `exit`. Once you've typed `exit` you will be back in the host of Charmed PostgreSQL (`postgresql/0`). Exit this host by once again typing `exit`. Now you will be in your original shell where you first started the tutorial; here you can interact with Juju and LXD. \ No newline at end of file diff --git a/docs/tutorial/t-enable-security.md b/docs/tutorial/t-enable-security.md deleted file mode 100644 index f8b5bfba4f..0000000000 --- a/docs/tutorial/t-enable-security.md +++ /dev/null @@ -1,69 +0,0 @@ -# Enable Security in your PostgreSQL deployment - -This is part of the [Charmed PostgreSQL Tutorial](/t/charmed-postgresql-tutorial-overview/9707?channel=14/stable). Please refer to this page for more information and the overview of the content. - -## Transport Layer Security (TLS) -[TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) is used to encrypt data exchanged between two applications; it secures data transmitted over the network. Typically, enabling TLS within a highly available database, and between a highly available database and client/server applications, requires domain-specific knowledge and a high level of expertise. Fortunately, the domain-specific knowledge has been encoded into Charmed PostgreSQL. This means (re-)configuring TLS on Charmed PostgreSQL is readily available and requires minimal effort on your end. - -Again, relations come in handy here as TLS is enabled via relations; i.e. by relating Charmed PostgreSQL to the [TLS Certificates Charm](https://charmhub.io/tls-certificates-operator). The TLS Certificates Charm centralises TLS certificate management in a consistent manner and handles providing, requesting, and renewing TLS certificates. - -### Configure TLS -Before enabling TLS on Charmed PostgreSQL we must first deploy the `tls-certificates-operator` charm: -```shell -juju deploy tls-certificates-operator --config generate-self-signed-certificates="true" --config ca-common-name="Tutorial CA" -``` - -Wait until the `tls-certificates-operator` is up and active, use `juju status --watch 1s` to monitor the progress: -``` -Model Controller Cloud/Region Version SLA Timestamp -tutorial overlord localhost/localhost 2.9.42 unsupported 10:31:40+01:00 - -App Version Status Scale Charm Channel Rev Exposed Message -postgresql active 2 postgresql 14/stable 281 no -tls-certificates-operator active 1 tls-certificates-operator stable 22 no - -Unit Workload Agent Machine Public address Ports Message -postgresql/0* active idle 0 10.89.49.129 Primary -postgresql/1 active idle 1 10.89.49.197 -tls-certificates-operator/0* active idle 4 10.89.49.185 - -Machine State Address Inst id Series AZ Message -0 started 10.89.49.129 juju-a8a31d-0 jammy Running -1 started 10.89.49.197 juju-a8a31d-1 jammy Running -4 started 10.89.49.185 juju-a8a31d-4 jammy Running -``` -*Note: this tutorial uses [self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate); self-signed certificates should not be used in a production cluster.* - -To enable TLS on Charmed PostgreSQL, relate the two applications: -```shell -juju relate postgresql tls-certificates-operator -``` - -### Add external TLS certificate -Use `openssl` to connect to the PostgreSQL and check the TLS certificate in use: -```shell -> openssl s_client -starttls postgres -connect 10.89.49.129:5432 | grep Issuer -... -depth=1 C = US, CN = Tutorial CA -verify error:num=19:self-signed certificate in certificate chain -... -``` -Congratulations! PostgreSQL is now using TLS certificate generated by the external application `tls-certificates-operator`. - - -### Remove external TLS certificate -To remove the external TLS certificate, unrelate applications: -```shell -juju remove-relation postgresql tls-certificates-operator -``` - -Check the TLS certificate in use: -```shell -> openssl s_client -starttls postgres -connect 10.89.49.129:5432 -... -no peer certificate available ---- -No client certificate CA names sent -... -``` -The Charmed PostgreSQL application is not using TLS anymore. \ No newline at end of file diff --git a/docs/tutorial/t-integrations.md b/docs/tutorial/t-integrations.md deleted file mode 100644 index 38305da6d9..0000000000 --- a/docs/tutorial/t-integrations.md +++ /dev/null @@ -1,145 +0,0 @@ -# Integrating your Charmed PostgreSQL - -This is part of the [Charmed PostgreSQL Tutorial](/t/charmed-postgresql-tutorial-overview/9707?channel=14/stable). Please refer to this page for more information and the overview of the content. - -## Integrations (Relations for Juju 2.9) -Relations, or what Juju 3.0+ documentation [describes as an Integration](https://juju.is/docs/sdk/integration), are the easiest way to create a user for PostgreSQL in Charmed PostgreSQL. Relations automatically create a username, password, and database for the desired user/application. As mentioned earlier in the [Access PostgreSQL section](#access-PostgreSQL) it is a better practice to connect to PostgreSQL via a specific user rather than the admin user. - -### Data Integrator Charm -Before relating to a charmed application, we must first deploy our charmed application. In this tutorial we will relate to the [Data Integrator Charm](https://charmhub.io/data-integrator). This is a bare-bones charm that allows for central management of database users, providing support for different kinds of data platforms (e.g. PostgreSQL, MySQL, MongoDB, Kafka, etc) with a consistent, opinionated and robust user experience. In order to deploy the Data Integrator Charm we can use the command `juju deploy` we have learned above: - -```shell -juju deploy data-integrator --channel edge --config database-name=test-database -``` -The expected output: -``` -Located charm "data-integrator" in charm-hub, revision 6 -Deploying "data-integrator" from charm-hub charm "data-integrator", revision 6 in channel edge on jammy -``` - -Checking the deployment progress using `juju status` will show you the `blocked` state for newly deployed charm: -``` -Model Controller Cloud/Region Version SLA Timestamp -tutorial overlord localhost/localhost 2.9.42 unsupported 10:22:13+01:00 - -App Version Status Scale Charm Channel Rev Exposed Message -data-integrator blocked 1 data-integrator edge 6 no Please relate the data-integrator with the desired product -postgresql active 2 postgresql 14/stable 281 no - -Unit Workload Agent Machine Public address Ports Message -data-integrator/0* blocked idle 3 10.89.49.179 Please relate the data-integrator with the desired product -postgresql/0* active idle 0 10.89.49.129 -postgresql/1 active idle 1 10.89.49.197 - -Machine State Address Inst id Series AZ Message -0 started 10.89.49.129 juju-a8a31d-0 jammy Running -1 started 10.89.49.197 juju-a8a31d-1 jammy Running -3 started 10.89.49.179 juju-a8a31d-3 jammy Running -``` -The `blocked` state is expected due to not-yet established relation (integration) between applications. - -### Relate to PostgreSQL -Now that the Database Integrator Charm has been set up, we can relate it to PostgreSQL. This will automatically create a username, password, and database for the Database Integrator Charm. Relate the two applications with: -```shell -juju relate data-integrator postgresql -``` -Wait for `juju status --watch 1s` to show all applications/units as `active`: -``` -Model Controller Cloud/Region Version SLA Timestamp -tutorial overlord localhost/localhost 2.9.42 unsupported 10:22:31+01:00 - -App Version Status Scale Charm Channel Rev Exposed Message -data-integrator active 1 data-integrator edge 6 no -postgresql active 2 postgresql 14/stable 281 no - -Unit Workload Agent Machine Public address Ports Message -data-integrator/0* active idle 3 10.89.49.179 -postgresql/0* active idle 0 10.89.49.129 Primary -postgresql/1 active idle 1 10.89.49.197 - -Machine State Address Inst id Series AZ Message -0 started 10.89.49.129 juju-a8a31d-0 jammy Running -1 started 10.89.49.197 juju-a8a31d-1 jammy Running -3 started 10.89.49.179 juju-a8a31d-3 jammy Running -``` - -To retrieve information such as the username, password, and database. Enter: -```shell -juju run-action data-integrator/leader get-credentials --wait -``` -This should output something like: -```yaml -unit-data-integrator-0: - UnitId: data-integrator/0 - id: "20" - results: - ok: "True" - postgresql: - database: test-database - endpoints: 10.89.49.129:5432 - password: 136bvw0s7FjJ6mxZ - read-only-endpoints: 10.89.49.197:5432 - username: relation-3 - version: "14.7" - status: completed - timing: - completed: 2023-03-20 09:22:50 +0000 UTC - enqueued: 2023-03-20 09:22:46 +0000 UTC - started: 2023-03-20 09:22:50 +0000 UTC -``` -*Note: your hostnames, usernames, and passwords will likely be different.* - -### Access the related database -Use `endpoints`, `username`, `password` from above to connect newly created database `test-database` on PostgreSQL server: -```shell -> psql --host=10.89.49.129 --username=relation-3 --password test-database -... -test-database=> \l -... - test-database | operator | UTF8 | C.UTF-8 | C.UTF-8 | =Tc/operator + - | | | | | operator=CTc/operator + - | | | | | "relation-3"=CTc/operator -... -``` - -The newly created database `test-database` is also available on all other PostgreSQL cluster members: -```shell -> psql --host=10.89.49.197 --username=relation-3 --password --list -... - test-database | operator | UTF8 | C.UTF-8 | C.UTF-8 | =Tc/operator + - | | | | | operator=CTc/operator + - | | | | | "relation-3"=CTc/operator -... -``` - -When you relate two applications Charmed PostgreSQL automatically sets up a new user and database for you. -Please note the database name we specified when we first deployed the `data-integrator` charm: `--config database-name=test-database`. - -### Remove the user -To remove the user, remove the relation. Removing the relation automatically removes the user that was created when the relation was created. Enter the following to remove the relation: -```shell -juju remove-relation postgresql data-integrator -``` - -Now try again to connect to the same PostgreSQL you just used in [Access the related database](#access-the-related-database): -```shell -> psql --host=10.89.49.129 --username=relation-3 --password --list -``` - -This will output an error message: -``` -psql: error: connection to server at "10.89.49.129", port 5432 failed: FATAL: password authentication failed for user "relation-3" -``` -As this user no longer exists. This is expected as `juju remove-relation postgresql data-integrator` also removes the user. -Note: data stay remain on the server at this stage! - -Relate the two applications again if you wanted to recreate the user: -```shell -juju relate data-integrator postgresql -``` -Re-relating generates a new user and password: -```shell -juju run-action data-integrator/leader get-credentials --wait -``` -You can connect to the database with this new credentials. -From here you will see all of your data is still present in the database. \ No newline at end of file diff --git a/docs/tutorial/t-manage-passwords.md b/docs/tutorial/t-manage-passwords.md deleted file mode 100644 index 281df44c6c..0000000000 --- a/docs/tutorial/t-manage-passwords.md +++ /dev/null @@ -1,65 +0,0 @@ -# Manage Passwords - -This is part of the [Charmed PostgreSQL Tutorial](/t/charmed-postgresql-tutorial-overview/9707?channel=14/stable). Please refer to this page for more information and the overview of the content. - -## Passwords -When we accessed PostgreSQL earlier in this tutorial, we needed to use a password manually. Passwords help to secure our database and are essential for security. Over time it is a good practice to change the password frequently. Here we will go through setting and changing the password for the admin user. - -### Retrieve the password -As previously mentioned, the operator's password can be retrieved by running the `get-password` action on the Charmed PostgreSQL application: -```shell -juju run-action postgresql/leader get-password --wait -``` -Running the command should output: -```yaml -unit-postgresql-0: - UnitId: postgresql/0 - id: "14" - results: - operator-password: eItxBiOYeMf7seSv - status: completed - timing: - completed: 2023-03-20 09:17:51 +0000 UTC - enqueued: 2023-03-20 09:17:49 +0000 UTC - started: 2023-03-20 09:17:50 +0000 UTC -``` - -### Rotate the password -You can change the operator's password to a new random password by entering: -```shell -juju run-action postgresql/leader set-password --wait -``` -Running the command should output: -```yaml -unit-postgresql-0: - UnitId: postgresql/0 - id: "16" - results: - operator-password: npGdNGNGVtu7SO50 - status: completed - timing: - completed: 2023-03-20 09:18:11 +0000 UTC - enqueued: 2023-03-20 09:18:08 +0000 UTC - started: 2023-03-20 09:18:10 +0000 UTC -``` -Please notice the `status: completed` above which means the password has been successfully updated. The password should be different from the previous password. - -### Set the new password -You can change the password to a specific password by entering: -```shell -juju run-action postgresql/leader set-password password=my-password --wait -``` -Running the command should output: -```yaml -unit-postgresql-0: - UnitId: postgresql/0 - id: "18" - results: - operator-password: my-password - status: completed - timing: - completed: 2023-03-20 09:20:06 +0000 UTC - enqueued: 2023-03-20 09:20:04 +0000 UTC - started: 2023-03-20 09:20:05 +0000 UTC -``` -The password should match whatever you passed in when you entered the command. \ No newline at end of file diff --git a/docs/tutorial/t-managing-units.md b/docs/tutorial/t-managing-units.md deleted file mode 100644 index d9d39c0722..0000000000 --- a/docs/tutorial/t-managing-units.md +++ /dev/null @@ -1,58 +0,0 @@ -# Scale your Charmed PostgreSQL - -This is part of the [Charmed PostgreSQL Tutorial](/t/charmed-postgresql-tutorial-overview/9707?channel=14/stable). Please refer to this page for more information and the overview of the content. - -## Adding and Removing units - -Charmed PostgreSQL operator uses [PostgreSQL Patroni-based cluster](https://patroni.readthedocs.io/en/latest/) for scaling. It provides features such as automatic membership management, fault tolerance, automatic failover, and so on. The charm uses Postgres’s [Synchronous replication](https://patroni.readthedocs.io/en/latest/replication_modes.html#postgresql-synchronous-replication) with Patroni. - -> **!** *Disclaimer: this tutorial hosts replicas all on the same machine, this should not be done in a production environment. To enable high availability in a production environment, replicas should be hosted on different servers to [maintain isolation](https://canonical.com/blog/database-high-availability).* - - -### Add cluster members (replicas) -You can add two replicas to your deployed PostgreSQL application with: -```shell -juju add-unit postgresql -n 2 -``` - -You can now watch the scaling process in live using: `juju status --watch 1s`. It usually takes several minutes for new cluster members to be added. You’ll know that all three nodes are in sync when `juju status` reports `Workload=active` and `Agent=idle`: -``` -Model Controller Cloud/Region Version SLA Timestamp -tutorial overlord localhost/localhost 2.9.42 unsupported 10:16:44+01:00 - -App Version Status Scale Charm Channel Rev Exposed Message -postgresql active 3 postgresql 14/stable 281 no - -Unit Workload Agent Machine Public address Ports Message -postgresql/0* active idle 0 10.89.49.129 Primary -postgresql/1 active idle 1 10.89.49.197 -postgresql/2 active idle 2 10.89.49.175 - -Machine State Address Inst id Series AZ Message -0 started 10.89.49.129 juju-a8a31d-0 jammy Running -1 started 10.89.49.197 juju-a8a31d-1 jammy Running -2 started 10.89.49.175 juju-a8a31d-2 jammy Running -``` - -### Remove cluster members (replicas) -Removing a unit from the application, scales the replicas down. Before we scale down the replicas, list all the units with `juju status`, here you will see three units `postgresql/0`, `postgresql/1`, and `postgresql/2`. Each of these units hosts a PostgreSQL replica. To remove the replica hosted on the unit `postgresql/2` enter: -```shell -juju remove-unit postgresql/2 -``` - -You’ll know that the replica was successfully removed when `juju status --watch 1s` reports: -``` -Model Controller Cloud/Region Version SLA Timestamp -tutorial overlord localhost/localhost 2.9.42 unsupported 10:17:14+01:00 - -App Version Status Scale Charm Channel Rev Exposed Message -postgresql active 2 postgresql 14/stable 281 no - -Unit Workload Agent Machine Public address Ports Message -postgresql/0* active idle 0 10.89.49.129 -postgresql/1 active idle 1 10.89.49.197 - -Machine State Address Inst id Series AZ Message -0 started 10.89.49.129 juju-a8a31d-0 jammy Running -1 started 10.89.49.197 juju-a8a31d-1 jammy Running -``` \ No newline at end of file diff --git a/docs/tutorial/t-overview.md b/docs/tutorial/t-overview.md deleted file mode 100644 index 0908492e2f..0000000000 --- a/docs/tutorial/t-overview.md +++ /dev/null @@ -1,24 +0,0 @@ -# Charmed PostgreSQL tutorial -The Charmed PostgreSQL Operator delivers automated operations management from [day 0 to day 2](https://codilime.com/blog/day-0-day-1-day-2-the-software-lifecycle-in-the-cloud-age/) on the [PostgreSQL](https://www.postgresql.org/) relational database. It is an open source, end-to-end, production-ready data platform on top of Juju. As a first step this tutorial shows you how to get Charmed PostgreSQL up and running, but the tutorial does not stop there. Through this tutorial you will learn a variety of operations, everything from adding replicas to advanced operations such as enabling Transport Layer Security (TLS). In this tutorial we will walk through how to: -- Set up an environment using [Multipass](https://multipass.run/) with [LXD](https://ubuntu.com/lxd) and [Juju](https://juju.is/). -- Deploy PostgreSQL using a single command. -- Access the database directly. -- Add high availability with PostgreSQL Patroni-based cluster. -- Request and change passwords. -- Automatically create PostgreSQL users via Juju relations. -- Reconfigure TLS certificate in one command. - -While this tutorial intends to guide and teach you as you deploy Charmed PostgreSQL, it will be most beneficial if you already have a familiarity with: -- Basic terminal commands. -- PostgreSQL concepts such as replication and users. - -## Step-by-step guide - -Here’s an overview of the steps required with links to our separate tutorials that deal with each individual step: -* [Set up the environment](/t/charmed-postgresql-tutorial-setup-environment/9709?channel=14/stable) -* [Deploy PostgreSQL](/t/charmed-postgresql-tutorial-deploy-postgresql/9697?channel=14/stable) -* [Managing your units](/t/charmed-postgresql-tutorial-managing-units/9705?channel=14/stable) -* [Manage passwords](/t/charmed-postgresql-tutorial-manage-passwords/9703?channel=14/stable) -* [Relate your PostgreSQL to other applications](/t/charmed-postgresql-tutorial-integrations/9701?channel=14/stable) -* [Enable security](/t/charmed-postgresql-tutorial-enable-security/9699?channel=14/stable) -* [Cleanup your environment](/t/charmed-postgresql-tutorial-cleanup-environment/9695?channel=14/stable) \ No newline at end of file diff --git a/docs/tutorial/t-setup-environment.md b/docs/tutorial/t-setup-environment.md deleted file mode 100644 index 589c0ebaf3..0000000000 --- a/docs/tutorial/t-setup-environment.md +++ /dev/null @@ -1,50 +0,0 @@ -# Environment Setup - -This is part of the [Charmed PostgreSQL Tutorial](/t/charmed-postgresql-tutorial-overview/9707?channel=14/stable). Please refer to this page for more information and the overview of the content. - -## Minimum requirements -Before we start, make sure your machine meets the following requirements: -- Ubuntu 20.04 (Focal) or later. -- 8GB of RAM. -- 2 CPU threads. -- At least 20GB of available storage. -- Access to the internet for downloading the required snaps and charms. - -## Multipass environment -[Multipass](https://multipass.run/) is a quick and easy way to launch virtual machines running Ubuntu. It uses "[cloud-init](https://cloud-init.io/)" standard to install and configure all the necessary parts automatically. - -Let's install Multipass from [Snap](https://snapcraft.io/multipass) and launch a new VM using "[charm-dev](https://github.com/canonical/multipass-blueprints/blob/main/v1/charm-dev.yaml)" cloud-init config: -```shell -sudo snap install multipass && \ -multipass launch --cpus 4 --memory 8G --disk 30G --name my-vm charm-dev # tune CPU/RAM/HDD accordingly to your needs -``` -*Note: all 'multipass launch' params are [described here](https://multipass.run/docs/launch-command)*. - -Multipass [list of commands](https://multipass.run/docs/multipass-cli-commands) is short and self-explanatory, e.g. show all running VMs: -```shell -multipass list -``` - -As soon as new VM started, enter inside using: -```shell -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: -```shell -juju bootstrap localhost overlord -``` - -The controller can work with different models; models host applications such as Charmed PostgreSQL. Set up a specific model for Charmed PostgreSQL named ‘tutorial’: -```shell -juju add-model tutorial -``` - -You can now view the model you created above by entering the command `juju status` into the command line. You should see the following: -``` -Model Controller Cloud/Region Version SLA Timestamp -tutorial overlord localhost/localhost 2.9.42 unsupported 09:38:32+01:00 - -Model "admin/tutorial" is empty. -``` \ No newline at end of file