From 68e806c7fb7fee66542375105c8c1f951e5b5435 Mon Sep 17 00:00:00 2001 From: deusebio Date: Mon, 3 Apr 2023 20:35:45 +0200 Subject: [PATCH] Documentation Sync with Discourse (#120) --------- Co-authored-by: Alex Lutay <1928266+taurus-forever@users.noreply.github.com> --- docs/how-to/h-configure-s3.md | 23 + docs/how-to/h-create-and-list-backups.md | 16 + docs/how-to/h-enable-encryption.md | 53 ++ docs/how-to/h-manage-app.md | 54 +++ docs/how-to/h-manage-units.md | 35 ++ docs/how-to/h-migrate-cluster-via-restore.md | 37 ++ docs/how-to/h-restore-backup.md | 30 ++ docs/index.md | 55 +++ docs/landing.md | 28 -- docs/reference/{charm.md => r-charm.md} | 2 +- docs/reference/{peers.md => r-peers.md} | 2 +- docs/reference/r-requirements.md | 7 + docs/tutorial.md | 482 ------------------- docs/tutorial/t-cleanup-environment.md | 20 + docs/tutorial/t-deploy-postgresql.md | 107 ++++ docs/tutorial/t-enable-security.md | 66 +++ docs/tutorial/t-integrations.md | 136 ++++++ docs/tutorial/t-manage-passwords.md | 65 +++ docs/tutorial/t-managing-units.md | 48 ++ docs/tutorial/t-overview.md | 31 ++ docs/tutorial/t-setup-environment.md | 45 ++ metadata.yaml | 1 + 22 files changed, 831 insertions(+), 512 deletions(-) create mode 100644 docs/how-to/h-configure-s3.md create mode 100644 docs/how-to/h-create-and-list-backups.md create mode 100644 docs/how-to/h-enable-encryption.md create mode 100644 docs/how-to/h-manage-app.md create mode 100644 docs/how-to/h-manage-units.md create mode 100644 docs/how-to/h-migrate-cluster-via-restore.md create mode 100644 docs/how-to/h-restore-backup.md create mode 100644 docs/index.md delete mode 100644 docs/landing.md rename docs/reference/{charm.md => r-charm.md} (99%) rename docs/reference/{peers.md => r-peers.md} (99%) create mode 100644 docs/reference/r-requirements.md delete mode 100644 docs/tutorial.md create mode 100644 docs/tutorial/t-cleanup-environment.md create mode 100644 docs/tutorial/t-deploy-postgresql.md create mode 100644 docs/tutorial/t-enable-security.md create mode 100644 docs/tutorial/t-integrations.md create mode 100644 docs/tutorial/t-manage-passwords.md create mode 100644 docs/tutorial/t-managing-units.md create mode 100644 docs/tutorial/t-overview.md create mode 100644 docs/tutorial/t-setup-environment.md diff --git a/docs/how-to/h-configure-s3.md b/docs/how-to/h-configure-s3.md new file mode 100644 index 000000000..b02b4c427 --- /dev/null +++ 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= secret-key= --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= +``` \ 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 new file mode 100644 index 000000000..f62da8705 --- /dev/null +++ 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 +``` \ No newline at end of file diff --git a/docs/how-to/h-enable-encryption.md b/docs/how-to/h-enable-encryption.md new file mode 100644 index 000000000..02fa7c8bc --- /dev/null +++ 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 +``` \ No newline at end of file diff --git a/docs/how-to/h-manage-app.md b/docs/how-to/h-manage-app.md new file mode 100644 index 000000000..a85fb8c43 --- /dev/null +++ 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= --wait +``` + +* To randomly generate a password for the operator user + +```shell +juju run-action postgresql-k8s/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 new file mode 100644 index 000000000..7d7f95427 --- /dev/null +++ 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 +``` + +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= +``` +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 +``` + +Warning: scaling-down to zero units 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 new file mode 100644 index 000000000..396dd4893 --- /dev/null +++ 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= --wait +juju run-action postgresql-k8s/leader set-password username=replication password= --wait +juju run-action postgresql-k8s/leader set-password username=rewind 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. \ No newline at end of file diff --git a/docs/how-to/h-restore-backup.md b/docs/how-to/h-restore-backup.md new file mode 100644 index 000000000..a6d3c71f4 --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..752b32c53 --- /dev/null +++ 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]()
Get started - a hands-on introduction to using Charmed PostgreSQL K8s operator for new users
| [How-to guides -- Coming Soon]()
Step-by-step guides covering key operations and common tasks | +| [Reference -- Coming Soon]()
Technical information - specifications, APIs, architecture | [Explanation -- Coming Soon]()
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] \ No newline at end of file diff --git a/docs/landing.md b/docs/landing.md deleted file mode 100644 index b31ec3c12..000000000 --- a/docs/landing.md +++ /dev/null @@ -1,28 +0,0 @@ -## 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]()
Get started - a hands-on introduction to using Charmed PostgreSQL K8s operator for new users
| [How-to guides -- Coming Soon]()
Step-by-step guides covering key operations and common tasks | -| [Reference -- Coming Soon]()
Technical information - specifications, APIs, architecture | [Explanation -- Coming Soon]()
Concepts - discussion and clarification of key topics | - -# Navigation -[details=Navigation] -| Level | Path | Navlink | -| ----- | -------- | ------------------------------- | -| 1 | Tutorials | [Tutorials - Coming Soon]() | -| 1 | how-tos-coming-soon | [How To -- Coming Soon]() | -| 1 | explanation-coming-soon | [Explanation -- Coming Soon]() | -| 1 | reference-coming-soon | [Reference -- Coming Soon]() | -[/details] diff --git a/docs/reference/charm.md b/docs/reference/r-charm.md similarity index 99% rename from docs/reference/charm.md rename to docs/reference/r-charm.md index 92a8883eb..b6f978b4f 100644 --- a/docs/reference/charm.md +++ b/docs/reference/r-charm.md @@ -58,4 +58,4 @@ flowchart TD mark_cluster_as_initialised--> update_config[Turn on/off PostgreSQL \n synchronous_commit configuration] update_config --> set_active[Set Active\n Status] set_active --> rtn2([return]) -``` +``` \ No newline at end of file diff --git a/docs/reference/peers.md b/docs/reference/r-peers.md similarity index 99% rename from docs/reference/peers.md rename to docs/reference/r-peers.md index 0d512dfc7..0e3b6be31 100644 --- a/docs/reference/peers.md +++ b/docs/reference/r-peers.md @@ -56,4 +56,4 @@ flowchart TD update_read_only_endpoint --> remove_departing_units[Remove departing units \n from the cluster] remove_departing_units --> update_config[Turn on/off PostgreSQL \n synchronous_commit configuration] update_config --> rtn2([return]) -``` +``` \ No newline at end of file diff --git a/docs/reference/r-requirements.md b/docs/reference/r-requirements.md new file mode 100644 index 000000000..e9917161d --- /dev/null +++ b/docs/reference/r-requirements.md @@ -0,0 +1,7 @@ +## Minimum requirements + +- Machine is running Ubuntu 20.04(focal) or later. +- 8GB of RAM. +- 2 CPU threads per host. +- For production deployment: at least 60GB of available storage on each host. +- Access to the internet for downloading the charm. \ No newline at end of file diff --git a/docs/tutorial.md b/docs/tutorial.md deleted file mode 100644 index 4624e3e1f..000000000 --- a/docs/tutorial.md +++ /dev/null @@ -1,482 +0,0 @@ -# Charmed PostgreSQL K8s tutorial -The Charmed PostgreSQL K8s 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-k8s.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 K8s 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 [MicroK8s](https://microk8s.io/) 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 K8s, it will be most beneficial if you already have a familiarity with: -- Basic terminal commands. -- PostgreSQL concepts such as replication and users. - -## 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 MicroK8s and Juju (the files '/var/log/cloud-init.log' and '/var/log/cloud-init-output.log' contain all low-level installation details). The Juju controller can work with different models; models host applications such as Charmed PostgreSQL K8s. Set up a specific model for Charmed PostgreSQL K8s 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 charm-dev microk8s/localhost 2.9.42 unsupported 11:56:38+01:00 - -Model "admin/tutorial" is empty. -``` - -## Deploy Charmed PostgreSQL K8s -To deploy Charmed PostgreSQL K8s, all you need to do is run the following command, which will fetch the charm from [Charmhub](https://charmhub.io/postgresql-k8s?channel=edge) and deploy it to your model: -```shell -juju deploy postgresql-k8s --channel edge --trust -``` -Note: `--trust` is required because the charm and Patroni need to create some K8s resources. - -Juju will now fetch Charmed PostgreSQL K8s and begin deploying it to the local MicroK8s. 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 K8s and gathering information about the machines hosting Charmed PostgreSQL K8s. Some of the helpful information it displays include IP addresses, ports, state, etc. The command updates the status of Charmed PostgreSQL K8s every second and as the application starts you can watch the status and messages of Charmed PostgreSQL K8s change. Wait until the application is ready - when it is ready, `juju status` will show: -``` -Model Controller Cloud/Region Version SLA Timestamp -tutorial charm-dev microk8s/localhost 2.9.42 unsupported 12:00:43+01:00 - -App Version Status Scale Charm Channel Rev Address Exposed Message -postgresql-k8s active 1 postgresql-k8s edge 56 10.152.183.167 no - -Unit Workload Agent Address Ports Message -postgresql-k8s/0* active idle 10.1.188.206 -``` -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-k8s.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 K8s action `get-password`: -```shell -juju run-action postgresql-k8s/leader get-password --wait -``` -Running the command should output: -```yaml -unit-postgresql-k8s-0: - UnitId: postgresql-k8s/0 - id: "2" - results: - password: SYhCduijXTAfg9mU - status: completed - timing: - completed: 2023-03-20 11:01:26 +0000 UTC - enqueued: 2023-03-20 11:01:24 +0000 UTC - started: 2023-03-20 11:01:25 +0000 UTC -``` - -*Note: to request a password for a different user, use an option `username`:* -```shell -juju run-action postgresql-k8s/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 Address Ports Message -postgresql-k8s/0* active idle 10.1.188.206 -... -``` - -To access the units hosting Charmed PostgreSQL K8s use: -```shell -juju ssh --container postgresql postgresql-k8s/leader bash -``` -*Note: if at any point you'd like to leave the unit hosting Charmed PostgreSQL K8s, 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.1.188.206 --username=operator --password --list -``` -*Note: when requested, enter the `` 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 | en_US.UTF-8 | en_US.UTF-8 | - template0 | operator | UTF8 | en_US.UTF-8 | en_US.UTF-8 | =c/operator + - | | | | | operator=CTc/operator - template1 | operator | UTF8 | en_US.UTF-8 | en_US.UTF-8 | =c/operator + - | | | | | operator=CTc/operator -(3 rows) -``` - -You can now interact with PostgreSQL directly using any [PostgreSQL SQL Queries](https://www.postgresql-k8s.org/docs/14/queries.html). For example entering `SELECT version();` should output something like: -``` -> root@postgresql-k8s-0:/# psql --host=10.1.188.206 --username=operator --password postgres -Password: -psql (14.5 (Ubuntu 14.5-0ubuntu0.22.04.1)) -Type "help" for help. - -postgres=# SELECT version(); - version ---------------------------------------------------------------------------------------------------------------------------------- - PostgreSQL 14.5 (Ubuntu 14.5-0ubuntu0.22.04.1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.2.0-19ubuntu1) 11.2.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 K8s (`postgresql-k8s/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 MicroK8s. - -## Scale Charmed PostgreSQL K8s -Charmed PostgreSQL K8s 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-k8s-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 by scaling it to three units using: -```shell -juju scale-application postgresql-k8s 3 -``` - -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 charm-dev microk8s/localhost 2.9.42 unsupported 12:09:49+01:00 - -App Version Status Scale Charm Channel Rev Address Exposed Message -postgresql-k8s active 3 postgresql-k8s edge 56 10.152.183.167 no - -Unit Workload Agent Address Ports Message -postgresql-k8s/0* active idle 10.1.188.206 Primary -postgresql-k8s/1 active idle 10.1.188.209 -postgresql-k8s/2 active idle 10.1.188.210 -``` - -### 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-k8s/0`, `postgresql-k8s/1`, and `postgresql-k8s/2`. Each of these units hosts a PostgreSQL replica. To scale the application down to two units, enter: -```shell -juju scale-application postgresql-k8s 2 -``` - -You’ll know that the replica was successfully removed when `juju status --watch 1s` reports: -``` -Model Controller Cloud/Region Version SLA Timestamp -tutorial charm-dev microk8s/localhost 2.9.42 unsupported 12:10:08+01:00 - -App Version Status Scale Charm Channel Rev Address Exposed Message -postgresql-k8s active 2 postgresql-k8s edge 56 10.152.183.167 no - -Unit Workload Agent Address Ports Message -postgresql-k8s/0* active idle 10.1.188.206 Primary -postgresql-k8s/1 active idle 10.1.188.209 -``` - -## 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 K8s application: -```shell -juju run-action postgresql-k8s/leader get-password --wait -``` -Running the command should output: -```yaml -unit-postgresql-k8s-0: - UnitId: postgresql-k8s/0 - id: "6" - results: - password: SYhCduijXTAfg9mU - status: completed - timing: - completed: 2023-03-20 11:10:33 +0000 UTC - enqueued: 2023-03-20 11:10:32 +0000 UTC - started: 2023-03-20 11:10:33 +0000 UTC -``` - -### Rotate the password -You can change the operator's password to a new random password by entering: -```shell -juju run-action postgresql-k8s/leader set-password --wait -``` -Running the command should output: -```yaml -unit-postgresql-k8s-0: - UnitId: postgresql-k8s/0 - id: "8" - results: - password: 7CYrRiBrC4du3ToX - status: completed - timing: - completed: 2023-03-20 11:10:47 +0000 UTC - enqueued: 2023-03-20 11:10:46 +0000 UTC - started: 2023-03-20 11:10:47 +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-k8s/leader set-password password=my-password --wait -``` -Running the command should output: -```yaml -unit-postgresql-k8s-0: - UnitId: postgresql-k8s/0 - id: "10" - results: - password: my-password - status: completed - timing: - completed: 2023-03-20 11:11:06 +0000 UTC - enqueued: 2023-03-20 11:11:02 +0000 UTC - started: 2023-03-20 11:11:05 +0000 UTC -``` -The password should match whatever you passed in when you entered the command. - -## 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 K8s. 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 charm-dev microk8s/localhost 2.9.42 unsupported 12:11:53+01:00 - -App Version Status Scale Charm Channel Rev Address Exposed Message -data-integrator waiting 1 data-integrator edge 6 10.152.183.66 no installing agent -postgresql-k8s active 2 postgresql-k8s edge 56 10.152.183.167 no - -Unit Workload Agent Address Ports Message -data-integrator/0* blocked idle 10.1.188.211 Please relate the data-integrator with the desired product -postgresql-k8s/0* active idle 10.1.188.206 -postgresql-k8s/1 active idle 10.1.188.209 -``` -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-k8s -``` -Wait for `juju status --watch 1s` to show all applications/units as `active`: -``` -Model Controller Cloud/Region Version SLA Timestamp -tutorial charm-dev microk8s/localhost 2.9.42 unsupported 12:12:12+01:00 - -App Version Status Scale Charm Channel Rev Address Exposed Message -data-integrator waiting 1 data-integrator edge 6 10.152.183.66 no installing agent -postgresql-k8s active 2 postgresql-k8s edge 56 10.152.183.167 no - -Unit Workload Agent Address Ports Message -data-integrator/0* active idle 10.1.188.211 -postgresql-k8s/0* active idle 10.1.188.206 -postgresql-k8s/1 active idle 10.1.188.209 -``` - -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: "12" - results: - ok: "True" - postgresql: - database: test-database - endpoints: postgresql-k8s-primary.tutorial.svc.cluster.local:5432 - password: WHnROd8wqzQKzd4F - read-only-endpoints: postgresql-k8s-replicas.tutorial.svc.cluster.local:5432 - username: relation_id_3 - version: "14.5" - status: completed - timing: - completed: 2023-03-20 11:12:26 +0000 UTC - enqueued: 2023-03-20 11:12:25 +0000 UTC - started: 2023-03-20 11:12:26 +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.1.188.206 --username=relation_id_3 --password test-database -Password: -... -test-database=> \l -... - test-database | operator | UTF8 | en_US.UTF-8 | en_US.UTF-8 | =Tc/operator + - | | | | | operator=CTc/operator + - | | | | | relation_id_3=CTc/operator -... -``` - -The newly created database `test-database` is also available on all other PostgreSQL cluster members: -```shell -> psql --host=10.89.49.209 --username=relation-3 --password --list -... - test-database | operator | UTF8 | en_US.UTF-8 | en_US.UTF-8 | =Tc/operator + - | | | | | operator=CTc/operator + - | | | | | relation_id_3=CTc/operator -... -``` - -When you relate two applications Charmed PostgreSQL K8s 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-k8s 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.1.188.206 --username=relation_id_3 --password --list -``` - -This will output an error message: -``` -psql: error: connection to server at "10.1.188.206", port 5432 failed: FATAL: password authentication failed for user "relation_id_3" -``` -As this user no longer exists. This is expected as `juju remove-relation postgresql-k8s data-integrator` also removes the user. -Note: data stay remain on the server at this stage! - -Relate the the two applications again if you wanted to recreate the user: -```shell -juju relate data-integrator postgresql-k8s -``` -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. - -## 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 K8s. This means (re-)configuring TLS on Charmed PostgreSQL K8s 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 K8s 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 K8s we must first deploy the `tls-certificates-operator` charm: -```shell -juju deploy tls-certificates-operator --channel=edge --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 charm-dev microk8s/localhost 2.9.42 unsupported 12:18:05+01:00 - -App Version Status Scale Charm Channel Rev Address Exposed Message -postgresql-k8s active 2 postgresql-k8s edge 56 10.152.183.167 no -tls-certificates-operator waiting 1 tls-certificates-operator edge 22 10.152.183.138 no installing agent - -Unit Workload Agent Address Ports Message -postgresql-k8s/0* active idle 10.1.188.206 Primary -postgresql-k8s/1 active idle 10.1.188.209 -tls-certificates-operator/0* active idle 10.1.188.212 -``` -*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 K8s, relate the two applications: -```shell -juju relate postgresql-k8s 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.1.188.206: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 and return to the locally generate one, unrelate applications: -```shell -juju remove-relation postgresql-k8s tls-certificates-operator -``` - -Check the TLS certificate in use: -```shell -> openssl s_client -starttls postgres -connect 10.1.188.206:5432 -... -no peer certificate available ---- -No client certificate CA names sent -... -``` -The Charmed PostgreSQL K8s application is not using TLS anymore. - -## 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 K8s deployment running and write to the database or remove it entirely using the steps in [Remove Charmed PostgreSQL K8s and Juju](#remove-charmed-postgresql-k8s-and-juju). If you're looking for what to do next you can: -- Run [Charmed PostgreSQL on VMs](https://github.com/canonical/postgresql-operator). -- Check out our Charmed offerings of [MySQL](https://charmhub.io/mysql-k8s?channel=edge) and [Kafka](https://charmhub.io/kafka-k8s?channel=edge). -- Read about [High Availability Best Practices](https://canonical.com/blog/database-high-availability) -- [Report](https://github.com/canonical/postgresql-k8s-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-k8s-operator) - -## 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 -``` - -# License: -The Charmed PostgreSQL K8s Operator [is distributed](https://github.com/canonical/postgresql-k8s-operator/blob/main/LICENSE) under the Apache Software License, version 2.0. It installs/operates/depends on [PostgreSQL](https://www.postgresql-k8s.org/ftp/source/), which [is licensed](https://www.postgresql-k8s.org/about/licence/) under PostgreSQL License, a liberal Open Source license, similar to the BSD or MIT licenses.. - -## Trademark Notice -PostgreSQL is a trademark or registered trademark of PostgreSQL Global Development Group. Other trademarks are property of their respective owners. diff --git a/docs/tutorial/t-cleanup-environment.md b/docs/tutorial/t-cleanup-environment.md new file mode 100644 index 000000000..8851bde7a --- /dev/null +++ b/docs/tutorial/t-cleanup-environment.md @@ -0,0 +1,20 @@ +# Cleanup and extra info + +This is part of the [Charmed PostgreSQL Tutorial](/t/charmed-postgresql-k8s-tutorial-overview/9296). Please refer to this page for more information and the overview of the content. + +## Remove and cleanup environment +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 K8s deployment running and write to the database or remove it entirely using the steps in [Remove Charmed PostgreSQL K8s and Juju](#remove-charmed-postgresql-k8s-and-juju). If you're looking for what to do next you can: +- Run [Charmed PostgreSQL on VMs](https://github.com/canonical/postgresql-operator). +- Check out our Charmed offerings of [MySQL](https://charmhub.io/mysql-k8s?channel=edge) and [Kafka](https://charmhub.io/kafka-k8s?channel=edge). +- Read about [High Availability Best Practices](https://canonical.com/blog/database-high-availability) +- [Report](https://github.com/canonical/postgresql-k8s-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-k8s-operator) \ No newline at end of file diff --git a/docs/tutorial/t-deploy-postgresql.md b/docs/tutorial/t-deploy-postgresql.md new file mode 100644 index 000000000..c8531bea1 --- /dev/null +++ b/docs/tutorial/t-deploy-postgresql.md @@ -0,0 +1,107 @@ +# Get a Charmed PostgreSQL up and running + +This is part of the [Charmed PostgreSQL Tutorial](/t/charmed-postgresql-k8s-tutorial-overview/9296). Please refer to this page for more information and the overview of the content. + +## Deploy + +To deploy Charmed PostgreSQL K8s, all you need to do is run the following command, which will fetch the charm from [Charmhub](https://charmhub.io/postgresql-k8s?channel=edge) and deploy it to your model: +```shell +juju deploy postgresql-k8s --channel edge --trust +``` +Note: `--trust` is required because the charm and Patroni need to create some K8s resources. + +Juju will now fetch Charmed PostgreSQL K8s and begin deploying it to the local MicroK8s. 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 K8s and gathering information about the machines hosting Charmed PostgreSQL K8s. Some of the helpful information it displays include IP addresses, ports, state, etc. The command updates the status of Charmed PostgreSQL K8s every second and as the application starts you can watch the status and messages of Charmed PostgreSQL K8s change. Wait until the application is ready - when it is ready, `juju status` will show: +``` +Model Controller Cloud/Region Version SLA Timestamp +tutorial charm-dev microk8s/localhost 2.9.42 unsupported 12:00:43+01:00 + +App Version Status Scale Charm Channel Rev Address Exposed Message +postgresql-k8s active 1 postgresql-k8s edge 56 10.152.183.167 no + +Unit Workload Agent Address Ports Message +postgresql-k8s/0* active idle 10.1.188.206 +``` +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 K8s action `get-password`: +```shell +juju run-action postgresql-k8s/leader get-password --wait +``` +Running the command should output: +```yaml +unit-postgresql-k8s-0: + UnitId: postgresql-k8s/0 + id: "2" + results: + password: SYhCduijXTAfg9mU + status: completed + timing: + completed: 2023-03-20 11:01:26 +0000 UTC + enqueued: 2023-03-20 11:01:24 +0000 UTC + started: 2023-03-20 11:01:25 +0000 UTC +``` + +*Note: to request a password for a different user, use an option `username`:* +```shell +juju run-action postgresql-k8s/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 Address Ports Message +postgresql-k8s/0* active idle 10.1.188.206 +... +``` + +To access the units hosting Charmed PostgreSQL K8s use: +```shell +juju ssh --container postgresql postgresql-k8s/leader bash +``` +*Note: if at any point you'd like to leave the unit hosting Charmed PostgreSQL K8s, 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.1.188.206 --username=operator --password --list +``` +*Note: when requested, enter the `` 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 | en_US.UTF-8 | en_US.UTF-8 | + template0 | operator | UTF8 | en_US.UTF-8 | en_US.UTF-8 | =c/operator + + | | | | | operator=CTc/operator + template1 | operator | UTF8 | en_US.UTF-8 | en_US.UTF-8 | =c/operator + + | | | | | operator=CTc/operator +(3 rows) +``` + +You can now interact with PostgreSQL directly using any [PostgreSQL SQL Queries](https://www.postgresql-k8s.org/docs/14/queries.html). For example entering `SELECT version();` should output something like: +``` +> root@postgresql-k8s-0:/# psql --host=10.1.188.206 --username=operator --password postgres +Password: +psql (14.5 (Ubuntu 14.5-0ubuntu0.22.04.1)) +Type "help" for help. + +postgres=# SELECT version(); + version +--------------------------------------------------------------------------------------------------------------------------------- + PostgreSQL 14.5 (Ubuntu 14.5-0ubuntu0.22.04.1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.2.0-19ubuntu1) 11.2.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 K8s (`postgresql-k8s/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 MicroK8s. \ No newline at end of file diff --git a/docs/tutorial/t-enable-security.md b/docs/tutorial/t-enable-security.md new file mode 100644 index 000000000..bf79fb94f --- /dev/null +++ b/docs/tutorial/t-enable-security.md @@ -0,0 +1,66 @@ +# Enable Security in your PostgreSQL deployment + +This is part of the [Charmed PostgreSQL Tutorial](/t/charmed-postgresql-k8s-tutorial-overview/9296). 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 K8s. This means (re-)configuring TLS on Charmed PostgreSQL K8s 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 K8s 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 K8s we must first deploy the `tls-certificates-operator` charm: +```shell +juju deploy tls-certificates-operator --channel=edge --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 charm-dev microk8s/localhost 2.9.42 unsupported 12:18:05+01:00 + +App Version Status Scale Charm Channel Rev Address Exposed Message +postgresql-k8s active 2 postgresql-k8s edge 56 10.152.183.167 no +tls-certificates-operator waiting 1 tls-certificates-operator edge 22 10.152.183.138 no installing agent + +Unit Workload Agent Address Ports Message +postgresql-k8s/0* active idle 10.1.188.206 Primary +postgresql-k8s/1 active idle 10.1.188.209 +tls-certificates-operator/0* active idle 10.1.188.212 +``` +*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 K8s, relate the two applications: +```shell +juju relate postgresql-k8s 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.1.188.206: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 and return to the locally generate one, unrelate applications: +```shell +juju remove-relation postgresql-k8s tls-certificates-operator +``` + +Check the TLS certificate in use: +```shell +> openssl s_client -starttls postgres -connect 10.1.188.206:5432 +... +no peer certificate available +--- +No client certificate CA names sent +... +``` + +The Charmed PostgreSQL K8s 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 new file mode 100644 index 000000000..a6638398f --- /dev/null +++ b/docs/tutorial/t-integrations.md @@ -0,0 +1,136 @@ +# Integrating your Charmed PostgreSQL + +This is part of the [Charmed PostgreSQL Tutorial](/t/charmed-postgresql-k8s-tutorial-overview/9296). 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 K8s. 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 charm-dev microk8s/localhost 2.9.42 unsupported 12:11:53+01:00 + +App Version Status Scale Charm Channel Rev Address Exposed Message +data-integrator waiting 1 data-integrator edge 6 10.152.183.66 no installing agent +postgresql-k8s active 2 postgresql-k8s edge 56 10.152.183.167 no + +Unit Workload Agent Address Ports Message +data-integrator/0* blocked idle 10.1.188.211 Please relate the data-integrator with the desired product +postgresql-k8s/0* active idle 10.1.188.206 +postgresql-k8s/1 active idle 10.1.188.209 +``` +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-k8s +``` +Wait for `juju status --watch 1s` to show all applications/units as `active`: +``` +Model Controller Cloud/Region Version SLA Timestamp +tutorial charm-dev microk8s/localhost 2.9.42 unsupported 12:12:12+01:00 + +App Version Status Scale Charm Channel Rev Address Exposed Message +data-integrator waiting 1 data-integrator edge 6 10.152.183.66 no installing agent +postgresql-k8s active 2 postgresql-k8s edge 56 10.152.183.167 no + +Unit Workload Agent Address Ports Message +data-integrator/0* active idle 10.1.188.211 +postgresql-k8s/0* active idle 10.1.188.206 +postgresql-k8s/1 active idle 10.1.188.209 +``` + +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: "12" + results: + ok: "True" + postgresql: + database: test-database + endpoints: postgresql-k8s-primary.tutorial.svc.cluster.local:5432 + password: WHnROd8wqzQKzd4F + read-only-endpoints: postgresql-k8s-replicas.tutorial.svc.cluster.local:5432 + username: relation_id_3 + version: "14.5" + status: completed + timing: + completed: 2023-03-20 11:12:26 +0000 UTC + enqueued: 2023-03-20 11:12:25 +0000 UTC + started: 2023-03-20 11:12:26 +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.1.188.206 --username=relation_id_3 --password test-database +Password: +... +test-database=> \l +... + test-database | operator | UTF8 | en_US.UTF-8 | en_US.UTF-8 | =Tc/operator + + | | | | | operator=CTc/operator + + | | | | | relation_id_3=CTc/operator +... +``` + +The newly created database `test-database` is also available on all other PostgreSQL cluster members: +```shell +> psql --host=10.89.49.209 --username=relation-3 --password --list +... + test-database | operator | UTF8 | en_US.UTF-8 | en_US.UTF-8 | =Tc/operator + + | | | | | operator=CTc/operator + + | | | | | relation_id_3=CTc/operator +... +``` + +When you relate two applications Charmed PostgreSQL K8s 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-k8s 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.1.188.206 --username=relation_id_3 --password --list +``` + +This will output an error message: +``` +psql: error: connection to server at "10.1.188.206", port 5432 failed: FATAL: password authentication failed for user "relation_id_3" +``` +As this user no longer exists. This is expected as `juju remove-relation postgresql-k8s data-integrator` also removes the user. +Note: data stay remain on the server at this stage! + +Relate the the two applications again if you wanted to recreate the user: +```shell +juju relate data-integrator postgresql-k8s +``` +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 new file mode 100644 index 000000000..fce65325e --- /dev/null +++ b/docs/tutorial/t-manage-passwords.md @@ -0,0 +1,65 @@ +# Manage Passwords + +This is part of the [Charmed PostgreSQL Tutorial](/t/charmed-postgresql-k8s-tutorial-overview/9296). 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 K8s application: +```shell +juju run-action postgresql-k8s/leader get-password --wait +``` +Running the command should output: +```yaml +unit-postgresql-k8s-0: + UnitId: postgresql-k8s/0 + id: "6" + results: + password: SYhCduijXTAfg9mU + status: completed + timing: + completed: 2023-03-20 11:10:33 +0000 UTC + enqueued: 2023-03-20 11:10:32 +0000 UTC + started: 2023-03-20 11:10:33 +0000 UTC +``` + +### Rotate the password +You can change the operator's password to a new random password by entering: +```shell +juju run-action postgresql-k8s/leader set-password --wait +``` +Running the command should output: +```yaml +unit-postgresql-k8s-0: + UnitId: postgresql-k8s/0 + id: "8" + results: + password: 7CYrRiBrC4du3ToX + status: completed + timing: + completed: 2023-03-20 11:10:47 +0000 UTC + enqueued: 2023-03-20 11:10:46 +0000 UTC + started: 2023-03-20 11:10:47 +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-k8s/leader set-password password=my-password --wait +``` +Running the command should output: +```yaml +unit-postgresql-k8s-0: + UnitId: postgresql-k8s/0 + id: "10" + results: + password: my-password + status: completed + timing: + completed: 2023-03-20 11:11:06 +0000 UTC + enqueued: 2023-03-20 11:11:02 +0000 UTC + started: 2023-03-20 11:11: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 new file mode 100644 index 000000000..e1d6b8973 --- /dev/null +++ b/docs/tutorial/t-managing-units.md @@ -0,0 +1,48 @@ +# Scale your Charmed PostgreSQL + +This is part of the [Charmed PostgreSQL Tutorial](/t/charmed-postgresql-k8s-tutorial-overview/9296). Please refer to this page for more information and the overview of the content. + +## Adding and Removing units + +Charmed PostgreSQL K8s 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-k8s-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 by scaling it to three units using: +```shell +juju scale-application postgresql-k8s 3 +``` + +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 charm-dev microk8s/localhost 2.9.42 unsupported 12:09:49+01:00 + +App Version Status Scale Charm Channel Rev Address Exposed Message +postgresql-k8s active 3 postgresql-k8s edge 56 10.152.183.167 no + +Unit Workload Agent Address Ports Message +postgresql-k8s/0* active idle 10.1.188.206 Primary +postgresql-k8s/1 active idle 10.1.188.209 +postgresql-k8s/2 active idle 10.1.188.210 +``` + +### 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-k8s/0`, `postgresql-k8s/1`, and `postgresql-k8s/2`. Each of these units hosts a PostgreSQL replica. To scale the application down to two units, enter: +```shell +juju scale-application postgresql-k8s 2 +``` + +You’ll know that the replica was successfully removed when `juju status --watch 1s` reports: +``` +Model Controller Cloud/Region Version SLA Timestamp +tutorial charm-dev microk8s/localhost 2.9.42 unsupported 12:10:08+01:00 + +App Version Status Scale Charm Channel Rev Address Exposed Message +postgresql-k8s active 2 postgresql-k8s edge 56 10.152.183.167 no + +Unit Workload Agent Address Ports Message +postgresql-k8s/0* active idle 10.1.188.206 Primary +postgresql-k8s/1 active idle 10.1.188.209 +``` \ No newline at end of file diff --git a/docs/tutorial/t-overview.md b/docs/tutorial/t-overview.md new file mode 100644 index 000000000..4d4bec512 --- /dev/null +++ b/docs/tutorial/t-overview.md @@ -0,0 +1,31 @@ +# Charmed PostgreSQL K8s tutorial + +The Charmed PostgreSQL K8s 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-k8s.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 K8s 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 [MicroK8s](https://microk8s.io/) 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 K8s, 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-k8s-tutorial-setup-environment/9297?channel=edge) +* [Deploy PostgreSQL](/t/charmed-postgresql-k8s-tutorial-deploy/9298?channel=dpe/edge) +* [Managing your units](/t/charmed-postgresql-k8s-tutorial-managing-units/9299?channel=dpe/edge) +* [Manage passwords](/t/charmed-postgresql-k8s-tutorial-manage-passwords/9300?channel=dpe/edge) +* [Relate your PostgreSQL to other applications](/t/charmed-postgresql-k8s-tutorial-integrations/9301?channel=dpe/edge) +* [Enable security](/t/charmed-postgresql-k8s-tutorial-enable-security/9302?channel=dpe/edge) +* [Cleanup your environment](/t/charmed-postgresql-k8s-tutorial-cleanup/9303?channel=dpe/edge) + +# License: +The Charmed PostgreSQL K8s Operator [is distributed](https://github.com/canonical/postgresql-k8s-operator/blob/main/LICENSE) under the Apache Software License, version 2.0. It installs/operates/depends on [PostgreSQL](https://www.postgresql-k8s.org/ftp/source/), which [is licensed](https://www.postgresql-k8s.org/about/licence/) under PostgreSQL License, a liberal Open Source license, similar to the BSD or MIT licenses.. + +## Trademark Notice +PostgreSQL is a trademark or registered trademark of PostgreSQL Global Development Group. Other trademarks are property of their respective owners. \ No newline at end of file diff --git a/docs/tutorial/t-setup-environment.md b/docs/tutorial/t-setup-environment.md new file mode 100644 index 000000000..c1370d069 --- /dev/null +++ b/docs/tutorial/t-setup-environment.md @@ -0,0 +1,45 @@ +# Environment Setup + +This is part of the [Charmed PostgreSQL Tutorial](/t/charmed-postgresql-k8s-tutorial-overview/9296). 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 MicroK8s and Juju (the files '/var/log/cloud-init.log' and '/var/log/cloud-init-output.log' contain all low-level installation details). The Juju controller can work with different models; models host applications such as Charmed PostgreSQL K8s. Set up a specific model for Charmed PostgreSQL K8s 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 charm-dev microk8s/localhost 2.9.42 unsupported 11:56:38+01:00 + +Model "admin/tutorial" is empty. +``` \ No newline at end of file diff --git a/metadata.yaml b/metadata.yaml index 1fb6de1cf..f64113fca 100644 --- a/metadata.yaml +++ b/metadata.yaml @@ -5,6 +5,7 @@ name: postgresql-k8s display-name: PostgreSQL K8s description: | Charm to operate the PostgreSQL database on Kubernetes clusters +docs: https://discourse.charmhub.io/t/charmed-postgresql-k8s-documenation/9307 summary: | Charm to operate the PostgreSQL database on Kubernetes clusters