From 7b8b3b36e136be1fb2e0660c538da21170b10b7f Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 10 Jul 2024 10:33:17 +0300 Subject: [PATCH] 'new: docs/how-to/h-upgrade/h-rollback-minor.md,docs/how-to/h-setup/h-deploy-microk8s.md,docs/reference/r-releases-group/r-releases.md,docs/how-to/h-enable-monitoring.md,docs/explanation/e-interfaces.md,docs/how-to/h-upgrade/h-upgrade-minor.md,docs/how-to/h-upgrade/h-upgrade-major.md,docs/how-to/h-upgrade/h-rollback-major.md,docs/reference/r-releases-group/r-releases-rev144.md,docs/tutorial/t-managing-units.md,docs/tutorial/t-overview.md,docs/reference/r-releases-group/r-releases-rev81.md,docs/explanation/e-juju-details.md,docs/reference/r-releases-group/r-releases-rev103.md,docs/tutorial/t-cleanup-environment.md,docs/tutorial/t-setup-environment.md,docs/reference/r-requirements.md,docs/reference/r-testing.md,docs/how-to/h-setup/h-manage-units.md,docs/how-to/h-upgrade/h-upgrade-intro.md,docs/index.md,docs/reference/r-releases-group/r-releases-rev76.md,docs/tutorial/t-deploy-charm.md,docs/tutorial/t-enable-security.md,docs/reference/r-contacts.md,docs/how-to/h-setup/h-manage-app.md,docs/how-to/h-setup/h-enable-encryption.md,docs/explanation/e-statuses.md' (#336) Co-authored-by: discourse-gatekeeper-docs-bot --- docs/explanation/e-interfaces.md | 31 +++ docs/explanation/e-juju-details.md | 43 ++++ docs/explanation/e-statuses.md | 16 ++ docs/how-to/h-enable-monitoring.md | 93 +++++++++ docs/how-to/h-setup/h-deploy-microk8s.md | 35 ++++ docs/how-to/h-setup/h-enable-encryption.md | 52 +++++ docs/how-to/h-setup/h-manage-app.md | 42 ++++ docs/how-to/h-setup/h-manage-units.md | 22 ++ docs/how-to/h-upgrade/h-rollback-major.md | 5 + docs/how-to/h-upgrade/h-rollback-minor.md | 44 ++++ docs/how-to/h-upgrade/h-upgrade-intro.md | 17 ++ docs/how-to/h-upgrade/h-upgrade-major.md | 5 + docs/how-to/h-upgrade/h-upgrade-minor.md | 168 ++++++++++++++++ docs/index.md | 63 ++++++ docs/reference/r-contacts.md | 18 ++ .../r-releases-group/r-releases-rev103.md | 41 ++++ .../r-releases-group/r-releases-rev144.md | 54 +++++ .../r-releases-group/r-releases-rev76.md | 46 +++++ .../r-releases-group/r-releases-rev81.md | 37 ++++ docs/reference/r-releases-group/r-releases.md | 13 ++ docs/reference/r-requirements.md | 28 +++ docs/reference/r-testing.md | 71 +++++++ docs/tutorial/t-cleanup-environment.md | 27 +++ docs/tutorial/t-deploy-charm.md | 190 ++++++++++++++++++ docs/tutorial/t-enable-security.md | 77 +++++++ docs/tutorial/t-managing-units.md | 83 ++++++++ docs/tutorial/t-overview.md | 27 +++ docs/tutorial/t-setup-environment.md | 52 +++++ 28 files changed, 1400 insertions(+) create mode 100644 docs/explanation/e-interfaces.md create mode 100644 docs/explanation/e-juju-details.md create mode 100644 docs/explanation/e-statuses.md create mode 100644 docs/how-to/h-enable-monitoring.md create mode 100644 docs/how-to/h-setup/h-deploy-microk8s.md create mode 100644 docs/how-to/h-setup/h-enable-encryption.md create mode 100644 docs/how-to/h-setup/h-manage-app.md create mode 100644 docs/how-to/h-setup/h-manage-units.md create mode 100644 docs/how-to/h-upgrade/h-rollback-major.md create mode 100644 docs/how-to/h-upgrade/h-rollback-minor.md create mode 100644 docs/how-to/h-upgrade/h-upgrade-intro.md create mode 100644 docs/how-to/h-upgrade/h-upgrade-major.md create mode 100644 docs/how-to/h-upgrade/h-upgrade-minor.md create mode 100644 docs/index.md create mode 100644 docs/reference/r-contacts.md create mode 100644 docs/reference/r-releases-group/r-releases-rev103.md create mode 100644 docs/reference/r-releases-group/r-releases-rev144.md create mode 100644 docs/reference/r-releases-group/r-releases-rev76.md create mode 100644 docs/reference/r-releases-group/r-releases-rev81.md create mode 100644 docs/reference/r-releases-group/r-releases.md create mode 100644 docs/reference/r-requirements.md create mode 100644 docs/reference/r-testing.md create mode 100644 docs/tutorial/t-cleanup-environment.md create mode 100644 docs/tutorial/t-deploy-charm.md create mode 100644 docs/tutorial/t-enable-security.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/explanation/e-interfaces.md b/docs/explanation/e-interfaces.md new file mode 100644 index 000000000..d0ed0c326 --- /dev/null +++ b/docs/explanation/e-interfaces.md @@ -0,0 +1,31 @@ +# Interfaces/endpoints + +PgBouncer K8s supports modern ['postgresql_client'](https://github.com/canonical/charm-relation-interfaces) interface. Applications can easily connect PgBouncer 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`. Read more about [Juju relations (integrations)](https://juju.is/docs/olm/relations). Example: + +```shell +# Deploy Charmed PostgreSQL K8s and PgBouncer K8s clusters with 3 nodes each +juju deploy postgresql-k8s -n 3 --trust --channel 14/stable +juju deploy pgbouncer-k8s -n 3 --trust --channel 1/stable + +# Deploy the relevant charms, e.g. postgresql-test-app +juju deploy postgresql-test-app + +# Relate all applications +juju integrate postgresql-k8s pgbouncer-k8s +juju integrate pgbouncer-k8s postgresql-test-app:first-database + +# Check established relation (using postgresql_client interface): +juju status --relations + +# Example of the properly established relation: +# > Integration provider Requirer Interface Type Message +# > pgbouncer-k8s:database postgresql-test-app:first-database postgresql_client regular +# > postgresql-k8s:database pgbouncer-k8s:backend-database postgresql_client regular +# > ... +``` + +See all the charm interfaces [here](https://charmhub.io/pgbouncer-k8s/integrations). \ No newline at end of file diff --git a/docs/explanation/e-juju-details.md b/docs/explanation/e-juju-details.md new file mode 100644 index 000000000..04cc32e8f --- /dev/null +++ b/docs/explanation/e-juju-details.md @@ -0,0 +1,43 @@ +# Juju tech details + +[Juju](https://juju.is/) is an open source orchestration engine for software operators that enables the deployment, integration and lifecycle management of applications at any scale, on any infrastructure using charms. + +This [charm](https://charmhub.io/pgbouncer-k8s) is an operator - business logic encapsulated in reusable software packages that automate every aspect of an application's life. Charms are shared via [CharmHub](https://charmhub.io/). + +See also: + +* [Juju Documentation](https://juju.is/docs/juju) and [Blog](https://ubuntu.com/blog/tag/juju) +* [Charm SDK](https://juju.is/docs/sdk) + +## Breaking changes between Juju 2.9.x and 3.x + +As this charm documentation is written for Juju 3.x, users of 2.9.x will encounter noteworthy changes when following the instructions. This section explains those changes. + +Breaking changes have been introduced in the Juju client between versions 2.9.x and 3.x. These are caused by the renaming and re-purposing of several commands - functionality and command options remain unchanged. + +In the context of this guide, the pertinent changes are shown here: + +|2.9.x|3.x| +| --- | --- | +|**add-relation**|**integrate**| +|**relate**|**integrate**| +|**run**|**exec**| +|**run-action --wait**|**run**| + +See the [Juju 3.0 release notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022) for the comprehensive list of changes. + +The response is to therefore substitute the documented command with the equivalent 2.9.x command. For example: + +### Juju 3.x: +```shell +juju integrate pgbouncer-k8s:database postgresql-test-app + +juju run postgresql-k8s/leader get-password +``` +### Juju 2.9.x: +```shell +juju relate pgbouncer-k8s:database postgresql-test-app + +juju run-action --wait postgresql-k8s/leader get-password +``` +> :tipping_hand_man: [The document based on OpenStack guide.](https://docs.openstack.org/charm-guide/latest/project/support-notes.html#breaking-changes-between-juju-2-9-x-and-3-x) \ No newline at end of file diff --git a/docs/explanation/e-statuses.md b/docs/explanation/e-statuses.md new file mode 100644 index 000000000..0f8de2758 --- /dev/null +++ b/docs/explanation/e-statuses.md @@ -0,0 +1,16 @@ +# Charm Statuses + +> :warning: **WARNING** : it is an work-in-progress article. Do NOT use it in production! Contact [Canonical Data Platform team](https://chat.charmhub.io/charmhub/channels/data-platform) if you are interested in the topic. + +The charm follows [standard Juju applications statuses](https://juju.is/docs/olm/status-values#heading--application-status). Here you can find the expected end-users reaction on different statuses: + +| Juju Status | Message | Expectations | Actions | +|-------|-------|-------|-------| +| **active** | any | Normal charm operations | No actions required | +| **waiting** | any | Charm is waiting for relations to be finished | No actions required | +| **maintenance** | any | Charm is performing the internal maintenance (e.g. re-configuration) | No actions required | +| **blocked** | any | The manual user activity is required! | Follow the message hints (see below) | +| **blocked** | waiting for backend database relation to initialise | Normal behavior, charm needs all relations to work. | Follow the hint to establish a proper relation. | +| **error** | any | An unhanded internal error happened | Read the message hint. Execute `juju resolve ` after addressing the root of the error state | +| **terminated** | any | The unit is gone and will be cleaned by Juju soon | No actions possible | +| **unknown** | any | Juju doesn't know the charm app/unit status. Possible reason: K8s charm termination in progress. | Manual investigation required if status is permanent | \ No newline at end of file diff --git a/docs/how-to/h-enable-monitoring.md b/docs/how-to/h-enable-monitoring.md new file mode 100644 index 000000000..42b967c72 --- /dev/null +++ b/docs/how-to/h-enable-monitoring.md @@ -0,0 +1,93 @@ +# How to enable monitoring + +Enable monitoring requires that you: +* [Have a PgBouncer K8s deployed](/t/12253) +* [Deploy `cos-lite` bundle in a Kubernetes environment](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s) +* [COS configured for Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s/docs/h-enable-monitoring) + +Switch to COS K8s environment and offer COS interfaces to be cross-model related with PgBouncer K8s model: +```shell +# Switch to Kubernetes controller, for the cos model. +juju switch : + +juju offer grafana:grafana-dashboard +juju offer loki:logging +juju offer prometheus:receive-remote-write +``` + +Switch to PgBouncer K8s model, find offers and consume them: +```shell +# We are on the Kubernetes controller, for the cos model. Switch to postgresql model +juju switch : + +juju find-offers : # Do not miss ':' here! +``` + +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 admin grafana:grafana-dashboard +k8s admin/cos.loki admin loki:logging +k8s admin/cos.prometheus admin prometheus:receive-remote-write +... +``` + +Consume offers to be reachable in the current model: +```shell +juju consume :admin/cos.grafana +juju consume :admin/cos.loki +juju consume :admin/cos.prometheus +``` + +Now, deploy '[grafana-agent-k8s](https://charmhub.io/grafana-agent-k8s)' (as `pgbouncer-cos-agent`) and integrate (relate) it with PgBouncer K8s, later integrate (relate) `pgbouncer-cos-agent` with consumed COS offers: +```shell +juju deploy grafana-agent-k8s pgbouncer-cos-agent --trust + +juju relate pgbouncer-cos-agent grafana +juju relate pgbouncer-cos-agent loki +juju relate pgbouncer-cos-agent prometheus + +juju relate pgbouncer-cos-agent pgbouncer-k8s:grafana-dashboard +juju relate pgbouncer-cos-agent pgbouncer-k8s:logging +juju relate pgbouncer-cos-agent pgbouncer-k8s:metrics-endpoint +``` + +After this is complete, Grafana will show the new dashboards: `PgBouncer Exporter` and allows access for PgBouncer logs on Loki. + +The example of `juju status` for Charmed PostgreSQL K8s + PgBouncer K8s model: +```shell +TODO +``` + +The example of `juju status` on COS K8s model: +```shell +Model Controller Cloud/Region Version SLA Timestamp +cos microk8s microk8s/localhost 3.1.6 unsupported 00:21:19+02:00 + +App Version Status Scale Charm Channel Rev Address Exposed Message +alertmanager 0.25.0 active 1 alertmanager-k8s edge 91 10.152.183.215 no +catalogue active 1 catalogue-k8s edge 27 10.152.183.187 no +grafana 9.2.1 active 1 grafana-k8s edge 92 10.152.183.95 no +loki 2.7.4 active 1 loki-k8s edge 99 10.152.183.28 no +prometheus 2.46.0 active 1 prometheus-k8s edge 149 10.152.183.232 no +traefik 2.10.4 active 1 traefik-k8s edge 155 10.76.203.228 no + +Unit Workload Agent Address Ports Message +alertmanager/0* active idle 10.1.142.186 +catalogue/0* active idle 10.1.142.176 +grafana/0* active idle 10.1.142.189 +loki/0* active idle 10.1.142.187 +prometheus/0* active idle 10.1.142.188 +traefik/0* active idle 10.1.142.185 + +Offer Application Charm Rev Connected Endpoint Interface Role +grafana grafana grafana-k8s 92 1/1 grafana-dashboard grafana_dashboard requirer +loki loki loki-k8s 99 1/1 logging loki_push_api provider +prometheus prometheus prometheus-k8s 149 1/1 receive-remote-write prometheus_remote_write provider + +``` + +To connect Grafana WEB interface, follow the COS section "[Browse dashboards](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)": +```shell +juju run grafana/leader get-admin-password --model : +``` \ No newline at end of file diff --git a/docs/how-to/h-setup/h-deploy-microk8s.md b/docs/how-to/h-setup/h-deploy-microk8s.md new file mode 100644 index 000000000..ae193df72 --- /dev/null +++ b/docs/how-to/h-setup/h-deploy-microk8s.md @@ -0,0 +1,35 @@ +# Deploy PgBouncer K8s + +Please follow the [PgBouncer K8s Tutorial](/t/12251) for technical details and explanations. + +Short story for your Ubuntu 22.04 LTS: +```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 +multipass shell my-vm + +juju add-model demo +juju deploy postgresql-k8s --channel 14/stable --trust # --config profile=testing +juju deploy pgbouncer-k8s --channel 1/stable --trust + +juju integrate postgresql-k8s pgbouncer-k8s + +juju status --watch 1s +``` + +The expected result: +```shell +Model Controller Cloud/Region Version SLA Timestamp +demo microk8s microk8s/localhost 3.1.6 unsupported 22:42:26+02:00 + +App Version Status Scale Charm Channel Rev Address Exposed Message +pgbouncer-k8s 1.18.0 active 1 pgbouncer-k8s 1/stable 76 10.152.183.128 no backend-database relation initialised. +postgresql-k8s 14.9 active 1 postgresql-k8s 14/stable 158 10.152.183.110 no + +Unit Workload Agent Address Ports Message +pgbouncer-k8s/0* active executing 10.1.12.36 backend-database relation initialised. +postgresql-k8s/0* active idle 10.1.12.22 +``` +The charm PgBouncer K8s is now waiting for relations with a client application, e.g. [postgresql-test-app](https://charmhub.io/postgresql-test-app), [mattermost](https://charmhub.io/mattermost-k8s), ... + +Check the [Testing](/t/12272) reference to test your deployment. \ No newline at end of file diff --git a/docs/how-to/h-setup/h-enable-encryption.md b/docs/how-to/h-setup/h-enable-encryption.md new file mode 100644 index 000000000..13d2a362b --- /dev/null +++ b/docs/how-to/h-setup/h-enable-encryption.md @@ -0,0 +1,52 @@ +# How to enable encryption + +PgBouncer will enable encrypted connections by default with self generated certificates. Though also by default, connecting clients can disable encryption by setting the connection ssl-mode as disabled. +When related with the `tls-certificates-operator` the charmed operator for PgBouncer will require that every client connection (new and running connections) use encryption, rendering an error when attempting to establish an unencrypted connection. + +> **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 legacy/stable + +# 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 pgbouncer-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 routers this schema should be followed: + +* Generate a shared internal (private) key: + +```shell +openssl genrsa -out internal-key.pem 3072 +``` + +* apply newly generated internal key on each unit: + +``` +juju run pgbouncer-k8s/0 set-tls-private-key "internal-key=$(base64 -w0 internal-key.pem)" +juju run pgbouncer-k8s/1 set-tls-private-key "internal-key=$(base64 -w0 internal-key.pem)" +juju run pgbouncer-k8s/2 set-tls-private-key "internal-key=$(base64 -w0 internal-key.pem)" +``` + +* updates can also be done with auto-generated keys with: + +``` +juju run pgbouncer-k8s/0 set-tls-private-key +juju run pgbouncer-k8s/1 set-tls-private-key +juju run pgbouncer-k8s/2 set-tls-private-key +``` + +## Disable TLS + +To disable TLS, remove the relation: +```shell +juju remove-relation tls-certificates-operator pgbouncer-k8s +``` \ No newline at end of file diff --git a/docs/how-to/h-setup/h-manage-app.md b/docs/how-to/h-setup/h-manage-app.md new file mode 100644 index 000000000..bb1bf5b51 --- /dev/null +++ b/docs/how-to/h-setup/h-manage-app.md @@ -0,0 +1,42 @@ +# How to manage related applications + +## Modern `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 integrate pgbouncer-k8s application +``` + +To remove a relation: + +```shell +juju remove-relation pgbouncer-k8s application +``` + +All listed on CharmHub applications are available [here](https://charmhub.io/pgbouncer-k8s/integrations), e.g.: + * [postgresql-test-app](https://charmhub.io/postgresql-test-app) + * [mattermost-k8s](https://charmhub.io/mattermost-k8s) + +## Legacy `pgsql` interface: + +This charm also supports the legacy relation via the `pgsql` interface. Please note that these interface is deprecated. + + ```shell +juju relate pgbouncer-k8s:db myapplication-k8s +``` + +Also extended permissions can be requested using `db-admin` endpoint: +```shell +juju relate pgbouncer-k8s:db-admin myapplication-k8s +``` + +## Internal operator user + +To rotate the internal router passwords, the relation with backend-database should be removed and related again. That process will generate a new user and password for the application, while retaining the requested database and data. + +```shell +juju remove-relation postgresql-k8s pgbouncer-k8s + +juju integrate postgresql-k8s pgbouncer-k8s +``` \ No newline at end of file diff --git a/docs/how-to/h-setup/h-manage-units.md b/docs/how-to/h-setup/h-manage-units.md new file mode 100644 index 000000000..6cdebc05c --- /dev/null +++ b/docs/how-to/h-setup/h-manage-units.md @@ -0,0 +1,22 @@ +# How to deploy and manage units + +## Basic Usage + +To deploy a single unit of PgBouncer using its default configuration +```shell +juju deploy pgbouncer-k8s --trust --channel 1/stable +``` + +It is customary to use PgBouncer in HA setup. Hence usually more than one unit (preferably an odd number to prohibit a "split-brain" scenario) is deployed. To deploy PgBOuncer in HA mode, specify the number of desired units with the `-n` option. +```shell +juju deploy pgbouncer-k8s --trust --channel 1/stable -n +``` + +## Scaling + +Both scaling-up and scaling-down operations are performed using `juju scale-application`: +```shell +juju scale-application pgbouncer-k8s +``` + +> :tipping_hand_man: **Tip**: scaling-down to zero units is supported to safe K8s resources! \ No newline at end of file diff --git a/docs/how-to/h-upgrade/h-rollback-major.md b/docs/how-to/h-upgrade/h-rollback-major.md new file mode 100644 index 000000000..4a906ef5a --- /dev/null +++ b/docs/how-to/h-upgrade/h-rollback-major.md @@ -0,0 +1,5 @@ +# Major Rollback + +> :information_source: **Example**: PgBouncer 2 -> PgBouncer 1 + +Currently, the charm supports PgBouncer major version 1 only; therefore, minor rollbacks are only possible. Canonical is NOT planning to support in-place rollbacks for the major PgBouncer version change as the old PostgreSQL cluster with the old PgBouncer installation will stay nearby and can be reused for the rollback. \ No newline at end of file diff --git a/docs/how-to/h-upgrade/h-rollback-minor.md b/docs/how-to/h-upgrade/h-rollback-minor.md new file mode 100644 index 000000000..991efb36c --- /dev/null +++ b/docs/how-to/h-upgrade/h-rollback-minor.md @@ -0,0 +1,44 @@ +# Minor Rollback + +> :information_source: **Example**: PgBouncer 1.19 -> PgBouncer 1.18
+(including simple charm revision bump: from revision 43 to revision 42) + +> **:warning: WARNING**: do NOT trigger `rollback` during the **running** `upgrade` action! It may cause unpredictable PostgreSQL Cluster and/or PgBouncer state! + +## Minor rollback steps + +The rollback is NOT necessary if `sacrificial unit` is created before the upgrade, just remove it using scale-down the application. Otherwise perform the rollback: + +1. **Rollback**. Perform the charm rollback using `juju refresh`. The unit with the maximal ordinal will be rolled-back first and rollback continues for entire application. +2. **Check**. Make sure the charm and cluster are in healthy state again. + +## Manual Rollback + +After a `juju refresh`, case there any version incompatibilities in charm revisions or it dependencies, or any other unexpected failure in the upgrade process, the upgrade process will be halted an enter a failure state. + +Although the underlying PostgreSQL Cluster and PgBouncer continue to work, it’s important to rollback the charm to previous revision so an update can be later attempted after a further inspection of the failure. + +To execute a rollback we take the same procedure as the upgrade, the difference being the charm revision to upgrade to. In case of this tutorial example, one would refresh the charm back to revision `88`, the steps being: + +## Step 1: Rollback + +When using charm from charmhub: + +``` +juju refresh pgbouncer-k8s --revision=88 --trust +``` + +Case deploying from local charm file, one need to have the previous revision charm file and the `postgresql-image` resource, then run: + +``` +juju refresh pgbouncer-k8s --trust --path=./pgbouncer-k8s_ubuntu-22.04-amd64.charm \ + --resource pgbouncer-image=ghcr.io/canonical/charmed-postgresql@sha256:753477ce39712221f008955b746fcf01a215785a215fe3de56f525380d14ad97 +``` + +Where `pgbouncer-k8s_ubuntu-22.04-amd64.charm` is the previous revision charm file. The reference for the resource for a given revision can be found at the `metadata.yaml` file in the [charm repository](https://github.com/canonical/pgbouncer-k8s-operator/blob/6f68e042c4ff6c310164c078ad266e43654188a3/metadata.yaml#L29). + +The biggest ordinal unit will be rolled out and should rejoin the cluster after settling down. After the refresh command, the juju controller revision for the application will be back in sync with the running PgBouncer K8s revision. + +## Step 2: Check + +The future [improvement is planned](https://warthogs.atlassian.net/browse/DPE-2620) to check the state on pod/cluster on a low level. At the moment check `juju status` to make sure the cluster [state](/t/12266) is OK. \ No newline at end of file diff --git a/docs/how-to/h-upgrade/h-upgrade-intro.md b/docs/how-to/h-upgrade/h-upgrade-intro.md new file mode 100644 index 000000000..b73ed28a4 --- /dev/null +++ b/docs/how-to/h-upgrade/h-upgrade-intro.md @@ -0,0 +1,17 @@ +# PgBouncer K8s Upgrade + +Please choose the appropriate upgrade/rollback tutorial. + +Migration: + +* [Major upgrade](/t/12268), e.g. PgBouncer 1 -> PgBouncer 2. + +* [Major rollback](/t/12269), e.g. PgBouncer 2 -> PgBouncer 1. + +In-place minor upgrade: + +* [Minor upgrade](/t/12270), e.g. PgBouncer 1.18 -> PgBouncer 1.19
+(including charm revision bump 99 -> 102). + +* [Minor rollback](/t/12271), e.g. PgBouncer 1.19 -> PgBouncer 1.18
+(including charm revision return 102 -> 99). \ No newline at end of file diff --git a/docs/how-to/h-upgrade/h-upgrade-major.md b/docs/how-to/h-upgrade/h-upgrade-major.md new file mode 100644 index 000000000..3a80d4cb0 --- /dev/null +++ b/docs/how-to/h-upgrade/h-upgrade-major.md @@ -0,0 +1,5 @@ +# Major Upgrade + +> :information_source: **Example**: PgBouncer 1 -> PgBouncer 2 + +Currently, the charm supports PgBouncer major version 1 only; therefore, minor upgrades are only possible. Canonical is NOT planning to support in-place upgrades for the Major version change. The new PgBouncer will have to be installed nearby, and the data will be copied from the old to the new installation. After announcing the next PostgreSQL+PgBouncer major versions support, the appropriate manual will be published here. \ No newline at end of file diff --git a/docs/how-to/h-upgrade/h-upgrade-minor.md b/docs/how-to/h-upgrade/h-upgrade-minor.md new file mode 100644 index 000000000..1129c5e34 --- /dev/null +++ b/docs/how-to/h-upgrade/h-upgrade-minor.md @@ -0,0 +1,168 @@ +# Minor Upgrade + +TODO... + \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..4613ebd9c --- /dev/null +++ b/docs/index.md @@ -0,0 +1,63 @@ +# PgBouncer K8s Documentation + +The PgBouncer K8s Operator delivers automated operations management from day 0 to day 2 on the [PgBouncer](http://www.pgbouncer.org/) - the lightweight connection pooler for [PostgreSQL](https://www.postgresql.org/). It is an open source, end-to-end, production-ready data platform on top of [Juju](https://juju.is/). + +![image|690x423](upload://fqMd5JlHeegw0PlUjhWKRu858Nc.png) + +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. Consider to use [Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s). + +The PgBouncer K8s operator can deploy and operate on both [physical/virtual machines](https://github.com/canonical/pgbouncer-operator) and on [Kubernetes](https://github.com/canonical/pgbouncer-k8s-operator). Both flavours offer identical features and simplify deployment, scaling, configuration and management of PgBouncer reliably in production. + +## Project and community + +This PgBouncer K8s charm is an official distribution of PgBouncer. 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/pgbouncer) +- [Contribute](https://github.com/canonical/pgbouncer-k8s-operator/blob/main/CONTRIBUTING.md) and report [issues](https://github.com/canonical/pgbouncer-k8s-operator/issues/new/choose) +- Explore [Canonical Data Fabric solutions](https://canonical.com/data) +- [Contact us](/t/12264) for any further questions + +## In this documentation + +| | | +|--|--| +| [Tutorials](/t/12251)
Get started - a hands-on introduction to using PgBouncer operator for new users
| [How-to guides](/t/12257)
Step-by-step guides covering key operations and common tasks | +| [Reference](/t/12261)
Technical information - specifications, APIs, architecture | [Explanation](/t/12265)
Concepts - discussion and clarification of key topics | + +# Contents + +1. [Tutorial](tutorial) + 1. [1. Introduction](tutorial/t-overview.md) + 1. [2. Set up the environment](tutorial/t-setup-environment.md) + 1. [3. Deploy PgBouncer](tutorial/t-deploy-charm.md) + 1. [4. Manage units](tutorial/t-managing-units.md) + 1. [5. Enable security](tutorial/t-enable-security.md) + 1. [6. Clean up environment](tutorial/t-cleanup-environment.md) +1. [How To](how-to) + 1. [Setup](how-to/h-setup) + 1. [Deploy on MicroK8s](how-to/h-setup/h-deploy-microk8s.md) + 1. [Manage units](how-to/h-setup/h-manage-units.md) + 1. [Enable encryption](how-to/h-setup/h-enable-encryption.md) + 1. [Manage applications](how-to/h-setup/h-manage-app.md) + 1. [Upgrade](how-to/h-upgrade) + 1. [Intro](how-to/h-upgrade/h-upgrade-intro.md) + 1. [Major upgrade](how-to/h-upgrade/h-upgrade-major.md) + 1. [Major rollback](how-to/h-upgrade/h-rollback-major.md) + 1. [Minor upgrade](how-to/h-upgrade/h-upgrade-minor.md) + 1. [Minor rollback](how-to/h-upgrade/h-rollback-minor.md) + 1. [Monitor (COS)](how-to/h-enable-monitoring.md) +1. [Reference](reference) + 1. [Release Notes](reference/r-releases-group) + 1. [All releases](reference/r-releases-group/r-releases.md) + 1. [Revision 144/145](reference/r-releases-group/r-releases-rev144.md) + 1. [Revision 103](reference/r-releases-group/r-releases-rev103.md) + 1. [Revision 81](reference/r-releases-group/r-releases-rev81.md) + 1. [Revision 76](reference/r-releases-group/r-releases-rev76.md) + 1. [Requirements](reference/r-requirements.md) + 1. [Contributing](https://github.com/canonical/pgbouncer-k8s-operator/blob/main/CONTRIBUTING.md) + 1. [Testing](reference/r-testing.md) + 1. [Contacts](reference/r-contacts.md) +1. [Explanation](explanation) + 1. [Interfaces/endpoints](explanation/e-interfaces.md) + 1. [Statuses](explanation/e-statuses.md) + 1. [Juju](explanation/e-juju-details.md) \ No newline at end of file diff --git a/docs/reference/r-contacts.md b/docs/reference/r-contacts.md new file mode 100644 index 000000000..be65444a8 --- /dev/null +++ b/docs/reference/r-contacts.md @@ -0,0 +1,18 @@ +# Contact + +Charmed PgBouncer K8s is an open source project that warmly welcomes community contributions, suggestions, fixes, and constructive feedback. +* Raise software issues or feature requests on [**GitHub**](https://github.com/canonical/pgbouncer-k8s-operator/issues/new/choose) +* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File) +* Contact the Canonical Data Platform team through our [Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) channel. +[note] +Our legacy [Mattermost](https://chat.charmhub.io/charmhub/channels/data-platform) channel is read-only until January 31, 2025. +[/note] + + +## Useful links +* [Canonical Data Fabric](https://ubuntu.com/data/) +* [Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s) +* [PgBouncer K8s](https://charmhub.io/pgbouncer-k8s) +* [Git sources for PgBouncer K8s](https://github.com/canonical/pgbouncer-k8s-operator) +* [Canonical Data Platform on Launchpad](https://launchpad.net/~data-platform) +* [Mailing list on Launchpad](https://lists.launchpad.net/data-platform/) \ No newline at end of file diff --git a/docs/reference/r-releases-group/r-releases-rev103.md b/docs/reference/r-releases-group/r-releases-rev103.md new file mode 100644 index 000000000..b520177e1 --- /dev/null +++ b/docs/reference/r-releases-group/r-releases-rev103.md @@ -0,0 +1,41 @@ +# PgBouncer K8s revision 103 +March 8, 2024 + +Dear community, we are excited to announce that the new Charmed PgBouncer K8s operator is published in the `1/stable` [charmhub](https://charmhub.io/pgbouncer-k8s?channel=1/stable) channel for Kubernetes. + +## New features + +* Juju 3.1.7 support (changes to Juju secrets) ([#196](https://github.com/canonical/pgbouncer-k8s-operator/pull/196)) +* Improved stability ([DPE-3049](https://warthogs.atlassian.net/browse/DPE-3049)| [#186](https://github.com/canonical/pgbouncer-k8s-operator/pull/186)) +* Fewer restarts on deployments and integrations +* Updated Charmed PostgreSQL ROCK ([revision 96](https://github.com/canonical/pgbouncer-k8s-operator/pull/210)) +* Updated Python library dependencies ([#226](https://github.com/canonical/pgbouncer-k8s-operator/pull/226)) + +## Bugfixes + +Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.net/jira/software/c/projects/DPE/issues/) and [GitHub](https://github.com/canonical/pgbouncer-k8s-operator/issues) platforms. [GitHub Releases](https://github.com/canonical/pgbouncer-k8s-operator/releases) provide a detailed list of bugfixes/PRs/Git commits for each revision. + +### Highlights for the current revision + +* Fix secret keys: do not set peer secrets as peer data ([#212](https://github.com/canonical/pgbouncer-k8s-operator/pull/212)) +* Removed binary dependencies ([DPE-3062](https://warthogs.atlassian.net/browse/DPE-3062) | [#179](https://github.com/canonical/pgbouncer-k8s-operator/pull/179)) +* Fixed Juju secrets usage ([DPE-3184](https://warthogs.atlassian.net/browse/DPE-3184) | [#178](https://github.com/canonical/pgbouncer-k8s-operator/pull/178)) +* Updated TLS libraries ([#191](https://github.com/canonical/pgbouncer-k8s-operator/pull/191)) + +## Inside the charms + +* Charmed PgBouncer K8s ships the latest PgBouncer `1.21.0-0ubuntu0.22.04.1~ppa1` +* The Prometheus pgbouncer-exporter is `0.7.0-0ubuntu0.22.04.1~ppa1` +* K8s charms based on our [ROCK OCI](https://github.com/orgs/canonical/packages?tab=packages&q=charmed) (Ubuntu LTS 22.04 - `ubuntu:22.04`-based) + +## Technical notes + +* Upgrade via `juju refresh` is possible from this revision onwards (103+) +* Please check [the external components requirements](/t/12263) +* Use this operator together with the [Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s) operator + +## Contact + +[Open a GitHub issue](https://github.com/canonical/pgbouncer-k8s-operator/issues) if you want to submit a bug report, or [contribute](https://github.com/canonical/pgbouncer-k8s-operator/blob/main/CONTRIBUTING.md) to the project! + +Check our [Contacts](/t/12264) page for more ways to reach us. \ No newline at end of file diff --git a/docs/reference/r-releases-group/r-releases-rev144.md b/docs/reference/r-releases-group/r-releases-rev144.md new file mode 100644 index 000000000..6f655cbf8 --- /dev/null +++ b/docs/reference/r-releases-group/r-releases-rev144.md @@ -0,0 +1,54 @@ +>Reference > Release Notes > [All revisions](/t/12261) > Revision 144/145 +# Revision 144/145 + +18 May, 2024 + +Dear community, + +We'd like to announce that Canonical's newest Charmed PgBouncer K8s operator has been published in the 1/stable [channel](https://charmhub.io/pgbouncer-k8s?channel=1/stable) :tada: : + +| |AMD64|ARM64| +|---:|:---:|:---:| +| Revision: | 144 | 145 | + +[note] +If you are jumping over several stable revisions, make sure to check [previous release notes](/t/12261) before upgrading to this revision. +[/note] + +## Features you can start using today + +* [New ARM support!](https://charmhub.io/pgbouncer-k8s/docs/r-requirements) [[#250](https://github.com/canonical/pgbouncer-k8s-operator/pull/250)] +* Add K8s NodePort support [[#264](https://github.com/canonical/pgbouncer-k8s-operator/pull/264)][[DPE-3777](https://warthogs.atlassian.net/browse/DPE-3777)] + * Add charm upgrade tests [[#217](https://github.com/canonical/pgbouncer-k8s-operator/pull/217)][[DPE-3255](https://warthogs.atlassian.net/browse/DPE-3255)] +* All the functionality from [previous revisions](https://charmhub.io/pgbouncer-k8s/docs/r-releases) + +## Bugfixes + +* Recreate auth_query on backend rerelation in [#284](https://github.com/canonical/pgbouncer-k8s-operator/pull/284), [[DPE-4221](https://warthogs.atlassian.net/browse/DPE-4221)] +* Update data-platform-libs: data_interfaces to 34 in [#277](https://github.com/canonical/pgbouncer-k8s-operator/pull/277) +* Update Rock in [#281](https://github.com/canonical/pgbouncer-k8s-operator/pull/281) +* Fixed autostart metrics service if password is not yet set in [#279](https://github.com/canonical/pgbouncer-k8s-operator/pull/279) +* Various bugfixes in [#252](https://github.com/canonical/pgbouncer-k8s-operator/pull/252) +* Update ROCK in [#263](https://github.com/canonical/pgbouncer-k8s-operator/pull/263) + +Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.net/jira/software/c/projects/DPE/issues/) and [GitHub](https://github.com/canonical/pgbouncer-k8s-operator/issues) platforms. +[GitHub Releases](https://github.com/canonical/pgbouncer-k8s-operator/releases) provide a detailed list of bugfixes, PRs, and commits for each revision. + +## Inside the charms + +* Charmed PgBouncer K8s ships the latest PgBouncer `1.21.0-0ubuntu0.22.04.1~ppa1` +* The Prometheus pgbouncer-exporter is `0.7.0-0ubuntu0.22.04.1~ppa1` +* K8s charms based on our [ROCK OCI](https://github.com/orgs/canonical/packages?tab=packages&q=charmed) (Ubuntu LTS 22.04.4) revision `113` + +## Technical notes + +* Upgrade via `juju refresh` is possible from this revision onwards (103+) +* Please check [the external components requirements](https://charmhub.io/pgbouncer-k8s/docs/r-requirements) +* Use this operator together with the [Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s) operator + +## Contact us + +Charmed PgBouncer K8s is an open source project that warmly welcomes community contributions, suggestions, fixes, and constructive feedback. +* Raise software issues or feature requests on [**GitHub**](https://github.com/canonical/pgbouncer-k8s-operator/issues) +* Report security issues through [**Launchpad**](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File) +* Contact the Canonical Data Platform team through our [Matrix](https://matrix.to/#/#charmhub-data-platform:ubuntu.com) channel. \ No newline at end of file diff --git a/docs/reference/r-releases-group/r-releases-rev76.md b/docs/reference/r-releases-group/r-releases-rev76.md new file mode 100644 index 000000000..9e22e06cc --- /dev/null +++ b/docs/reference/r-releases-group/r-releases-rev76.md @@ -0,0 +1,46 @@ +# PgBouncer K8s revision 76 +Monday, October 23, 2023 + +Dear community, we would like to inform you that new PgBouncer K8s is published in the `1/stable` [charmhub](https://charmhub.io/pgbouncer-k8s?channel=1/stable) channel for Kubernetes. + +## Features you can start using today: + +* Added [Juju 3 support](/t/12263) (Juju 2 is still supported) [[DPE-1762](https://warthogs.atlassian.net/browse/DPE-1762)] +* Juju peer and relation secrets support [[DPE-1766](https://warthogs.atlassian.net/browse/DPE-1766)][[DPE-2296](https://warthogs.atlassian.net/browse/DPE-2296)] +* Charm [minor upgrades](/t/12270) and [minor rollbacks](/t/12271) [[DPE-1771](https://warthogs.atlassian.net/browse/DPE-1771)] +* ["Charmed PostgreSQL K8s" extensions support ](https://charmhub.io/postgresql-k8s/docs/h-enable-plugins) [[DPE-2056](https://warthogs.atlassian.net/browse/DPE-2056)] +* [COS support](/t/12279) [[DPE-1779](https://warthogs.atlassian.net/browse/DPE-1779)] +* Logs rotation [[DPE-1756](https://warthogs.atlassian.net/browse/DPE-1756)] +* [TLS support](/t/12255) [[DPE-335](https://warthogs.atlassian.net/browse/DPE-335)] +* The "[data-integrator](https://charmhub.io/data-integrator)" support +* [Support](https://charmhub.io/pgbouncer-k8s/integrations?channel=1/stable) for modern `postgresql_client`, legacy `pgsql` and `tls-certificates` interfaces +* Workload updated to [PgBouncer 1.18](https://www.pgbouncer.org/changelog.html) (fixes for PostgreSQL 14) +* [Complete documentation on CharmHub](https://charmhub.io/pgbouncer-k8s?channel=1/stable) + +## Bugfixes included: + +Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.net/jira/software/c/projects/DPE/issues/) and [GitHub](https://github.com/canonical/pgbouncer-k8s-operator/issues) platforms.
[GitHub Releases](https://github.com/canonical/pgbouncer-k8s-operator/releases) provides a detailed list of bugfixes/PRs/commits for each revision. + +## What is inside the charms: + +* Charmed PgBouncer K8s ships the latest PgBouncer “1.18.0-0ubuntu0.22.04.1” +* The Prometheus pgbouncer-exporter is "0.7.0-0ubuntu0.22.04.1~ppa1" +* K8s charms [based on our](https://github.com/orgs/canonical/packages?tab=packages&q=charmed) ROCK OCI (Ubuntu LTS “22.04” - ubuntu:22.04-based) +* Principal charms supports the latest LTS series “22.04” only. +* Subordinate charms support LTS “22.04” and “20.04” only. + +## Technical notes: + +* Upgrade (`juju refresh`) is possible from this revision 76+. +* Please check [the external components requirements](/t/12263) +* Use this operator together with modern [Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s) operator. + +## How to reach us: + +If you would like to chat with us about your use-cases or ideas, you can reach us at [Canonical Mattermost public channel](https://chat.charmhub.io/charmhub/channels/data-platform) or [Discourse](https://discourse.charmhub.io/). Check all other contact details [here](/t/12264). + +Consider [opening a GitHub issue](https://github.com/canonical/pgbouncer-k8s-operator/issues) if you want to open a bug report.
[Contribute](https://github.com/canonical/pgbouncer-k8s-operator/blob/main/CONTRIBUTING.md) to the project! + +## Footer: + +It is the first stable release of the operator "PgBouncer K8s" by Canonical Data.
Well done, Team! \ No newline at end of file diff --git a/docs/reference/r-releases-group/r-releases-rev81.md b/docs/reference/r-releases-group/r-releases-rev81.md new file mode 100644 index 000000000..9e15f134d --- /dev/null +++ b/docs/reference/r-releases-group/r-releases-rev81.md @@ -0,0 +1,37 @@ +# PgBouncer K8s revision 81 +Wednesday, December 6, 2023 + +Dear community, this is to inform you that new PgBouncer K8s is published in `1/stable` [charmhub](https://charmhub.io/pgbouncer-k8s?channel=1/stable) channel for Kubernetes. + +## The features you can start using today: + +* PgBouncer is updated from 1.18 to 1.21 [[DPE-3040](https://warthogs.atlassian.net/browse/DPE-3040)] +* Open TCP port `6432` on K8s [[GH PR#159](https://github.com/canonical/pgbouncer-k8s-operator/pull/159)] +* Updated Python library dependencies [[GH PR#158](https://github.com/canonical/pgbouncer-k8s-operator/pull/158)] + +## Bugfixes included: + +Canonical Data issues are now public on both [Jira](https://warthogs.atlassian.net/jira/software/c/projects/DPE/issues/) and [GitHub](https://github.com/canonical/pgbouncer-k8s-operator/issues) platforms.
[GitHub Releases](https://github.com/canonical/pgbouncer-k8s-operator/releases) provide a detailed list of bugfixes/PRs/Git commits for each revision. + +* Juju Secrets fixes provided by updated data Interfaces library (LIBPATCH 24). +* Fixed [GitHub Issue #166](https://github.com/canonical/pgbouncer-k8s-operator/issues/166) [[DPE-3113](https://warthogs.atlassian.net/browse/DPE-3113)] + +## What is inside the charms: + +* Charmed PgBouncer K8s ships the latest PgBouncer “1.21.0-0ubuntu0.22.04.1~ppa1” +* The Prometheus pgbouncer-exporter is "0.7.0-0ubuntu0.22.04.1~ppa1" +* K8s charms [based on our](https://github.com/orgs/canonical/packages?tab=packages&q=charmed) ROCK OCI (Ubuntu LTS “22.04” - ubuntu:22.04-based) +* Principal charms supports the latest LTS series “22.04” only. +* Subordinate charms support LTS “22.04” and “20.04” only. + +## Technical notes: + +* Upgrade (`juju refresh`) is possible from this revision 76+. +* Please check [the external components requirements](/t/12263) +* Use this operator together with a modern operator "[Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s)". + +## How to reach us: + +If you would like to chat with us about your use-cases or ideas, you can reach us at [Canonical Mattermost public channel](https://chat.charmhub.io/charmhub/channels/data-platform) or [Discourse](https://discourse.charmhub.io/). Check all other contact details [here](/t/12264). + +Consider [opening a GitHub issue](https://github.com/canonical/pgbouncer-k8s-operator/issues) if you want to open a bug report.
[Contribute](https://github.com/canonical/pgbouncer-k8s-operator/blob/main/CONTRIBUTING.md) to the project! \ No newline at end of file diff --git a/docs/reference/r-releases-group/r-releases.md b/docs/reference/r-releases-group/r-releases.md new file mode 100644 index 000000000..6924e8fe4 --- /dev/null +++ b/docs/reference/r-releases-group/r-releases.md @@ -0,0 +1,13 @@ +# Release Notes + +Here you will find release notes for the main revisions of this charm that are available in Charmhub [channels](https://juju.is/docs/sdk/channel): + +* **`stable`**: production-ready releases +* **`candidate`, `beta`, `edge`** : [risk channels](https://juju.is/docs/sdk/channel#heading--risk) - new and experimental features. Not recommended for production. + +| Channel | amd64 | arm64 | +|----------:|:-----:|:-----:| +| `1/stable` | [144](/t/14070) | [145](/t/14070) | +| | [103](/t/13297) | - | +| | [81](/t/12751) | - | +| | [76](/t/12262) | - | \ 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..69bcbd121 --- /dev/null +++ b/docs/reference/r-requirements.md @@ -0,0 +1,28 @@ +## Juju version + +The charm supports both [Juju 2.9 LTS](https://github.com/juju/juju/releases) and [Juju 3.1](https://github.com/juju/juju/releases). + +The minimum supported Juju versions are: + +* 2.9.32+ +* 3.1.7+ (Juju secrets refactored/stabilized in Juju 3.1.7) + +## Kubernetes requirements + +* Kubernetes 1.27+ +* Canonical MicroK8s 1.27+ (snap channel 1.27-strict/stable and newer) +## Minimum requirements + +Make sure your machine meets the following requirements: +- Ubuntu 22.04 (Jammy) or later. +- 8GB of RAM. +- 2 CPU threads. +- At least 20GB of available storage. +- Access to the internet for downloading the required OCI/ROCKs and charms. + +## Supported architectures + +The charm is based on [ROCK OCI](https://github.com/canonical/charmed-postgresql-rock) named "[charmed-postgresql](https://github.com/canonical/charmed-postgresql-rock/pkgs/container/charmed-postgresql)", which is recursively based on SNAP "[charmed-postgresql](https://snapcraft.io/charmed-postgresql)", which is currently available for `amd64` and `arm64` (revision 146+). Please [contact us](/t/12264) if you are interested in new architecture! + +## Charmed PostgreSQL K8s requirements +Please also keep in mind "[Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s/docs/r-requirements)" requirements. \ No newline at end of file diff --git a/docs/reference/r-testing.md b/docs/reference/r-testing.md new file mode 100644 index 000000000..032bfd933 --- /dev/null +++ b/docs/reference/r-testing.md @@ -0,0 +1,71 @@ +# Charm Testing reference + +There are [a lot of test types](https://en.wikipedia.org/wiki/Software_testing) available and most of them are well applicable for PgBouncer K8s. Here is a list prepared by Canonical: + +* Smoke test +* Unit tests +* Integration tests +* System test +* Performance test + +**:information_source: Note:** below examples are written for Juju 3.x, but Juju 2.9 is [supported](/t/12263) as well.
Please adopt the `juju run ...` commands as `juju run-action ... --wait` for Juju 2.9. + +## Smoke test + +[u]Complexity[/u]: trivial
+[u]Speed[/u]: fast
+[u]Goal[/u]: ensure basic functionality works over short amount of time. + +[Setup an Juju 3.x environment](/t/12252), deploy DB with test application and start "continuous write" test: +```shell +juju add-model smoke-test + +juju deploy postgresql-k8s --trust --channel 14/stable --config profile=testing +juju deploy pgbouncer-k8s --trust --channel 1/stable +juju relate postgresql-k8s pgbouncer-k8s + +juju scale-application postgresql-k8s 3 # (optional) +juju scale-application pgbouncer-k8s 3 # (optional) + +juju deploy postgresql-test-app --channel latest/stable +juju relate pgbouncer-k8s postgresql-test-app:first-database + +# Make sure random data inserted into DB by test application: +juju run postgresql-test-app/leader get-inserted-data + +# Start "continuous write" test: +juju run postgresql-test-app/leader start-continuous-writes +export password=$(juju run postgresql-k8s/leader get-password username=operator | yq '.. | select(. | has("password")).password') +watch -n1 -x juju ssh --container postgresql postgresql-k8s/leader "psql -h 127.0.0.1 -p 6432 -U operator -W -e \"select count(*) from TODO.TODO\"" + +# Watch the counter is growing! +``` +[u]Expected results[/u]: + +* postgresql-test-app continuously inserts records in database `TODO` table `TODO`. +* the counters (amount of records in table) are growing on all cluster members + +[u]Hints[/u]: +```shell +# Stop "continuous write" test +juju run postgresql-test-app/leader stop-continuous-writes + +# Truncate "continuous write" table (delete all records from DB) +juju run postgresql-test-app/leader clear-continuous-writes +``` + +## Unit tests + +Please check the "[Contributing](https://github.com/canonical/pgbouncer-k8s-operator/blob/main/CONTRIBUTING.md#testing)" guide and follow `tox run -e unit` examples there. + +## Integration tests + +Please check the "[Contributing](https://github.com/canonical/pgbouncer-k8s-operator/blob/main/CONTRIBUTING.md#testing)" guide and follow `tox run -e integration` examples there. + +## System test + +Please check/deploy the charm [postgresql-k8s-bundle](https://charmhub.io/pgbouncer-k8s-bundle) ([Git](https://github.com/canonical/pgbouncer-k8s-bundle)). It deploy and test all the necessary parts at once. + +## Performance test + +Please use the separate [Charmed PostgreSQL K8s performance testing document](https://charmhub.io/postgresql-k8s/docs/r-testing) but deploy Charmed PostgreSQL K8s behind PgBouncer K8s. \ No newline at end of file diff --git a/docs/tutorial/t-cleanup-environment.md b/docs/tutorial/t-cleanup-environment.md new file mode 100644 index 000000000..f9d376c2a --- /dev/null +++ b/docs/tutorial/t-cleanup-environment.md @@ -0,0 +1,27 @@ +# Clean up and extra info + +This is part of the [PgBouncer K8s Tutorial](/t/12251). Please refer to this page for more information and the overview of the content. + +## Remove and clean up environment + +If you're done with testing and would like to free up resources on your machine, just remove Multipass VM. +[note type="negative"] +**Warning**: when you remove VM as shown below, you will lose all the data in PostgreSQL and any other applications inside Multipass VM! + +For more information, see [multipass delete](https://multipass.run/docs/delete-command). +[/note] + +```shell +multipass delete --purge my-vm +``` + +## Next Steps +In this tutorial, we've successfully deployed PgBouncer, added/removed cluster members, added/removed users to/from the database, and even enabled and disabled TLS. You may now keep your deployment running and write to the database, or remove it entirely. + +If you're looking for what to do next, you can: +- Run [Charmed PostgreSQL VM on LXD](https://github.com/canonical/postgresql-operator). +- Check out our Charmed offerings of [MySQL K8s](https://charmhub.io/mysql-k8s) and [Kafka K8s](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/pgbouncer-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/pgbouncer-k8s-operator) \ No newline at end of file diff --git a/docs/tutorial/t-deploy-charm.md b/docs/tutorial/t-deploy-charm.md new file mode 100644 index 000000000..a694ce1ad --- /dev/null +++ b/docs/tutorial/t-deploy-charm.md @@ -0,0 +1,190 @@ +# Get a PgBouncer K8s up and running + +This is part of the [PgBouncer K8s Tutorial](/t/12251). Please refer to this page for more information and the overview of the content. + +In this section, you will deploy PgBouncer together with a PostgreSQL server from [Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s). + +[note] +**Note**: All commands are written for `juju >= v.3.0` + +If you are using an earlier version, be aware that: + + - `juju run` replaces `juju run-action --wait` in `juju v.2.9` + - `juju integrate` replaces `juju relate` and `juju add-relation` in `juju v.2.9` + +For more information, check the [Juju 3.0 Release Notes](https://juju.is/docs/juju/roadmap#heading--juju-3-0-0---22-oct-2022). +[/note] + +## Deploy Charmed PostgreSQL K8s + PgBouncer K8s + +To deploy Charmed PostgreSQL K8s + PgBouncer K8s, all you need to do is run the following commands: + +```shell +juju deploy pgbouncer-k8s --channel 1/stable --trust +``` +```shell +juju deploy postgresql-k8s --trust +``` +[note] +**Note**: `--trust` is required to create some K8s resources. +[/note] + +Juju will now fetch charms from [Charmhub](https://charmhub.io/) and begin deploying them to 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 Juju applications and gathering information about the machines hosting them. It displays helpful information like IP addresses, ports, state, etc. The `--watch 1s` flag updates the status of charms every second, so as the application starts, you can watch the status and messages as they change. + +When the application is ready, `juju status` will show +```shell +Model Controller Cloud/Region Version SLA Timestamp +test16 microk8s microk8s/localhost 3.1.6 unsupported 21:55:49+02:00 + +App Version Status Scale Charm Channel Rev Address Exposed Message +pgbouncer-k8s 1.18.0 waiting 1 pgbouncer-k8s 1/stable 76 10.152.183.84 no installing agent +postgresql-k8s 14.9 active 1 postgresql-k8s 14/stable 158 10.152.183.92 no Primary + +Unit Workload Agent Address Ports Message +pgbouncer-k8s/0* blocked idle 10.1.12.15 waiting for backend database relation to initialise +postgresql-k8s/0* active idle 10.1.12.6 Primary +``` +[note] +**Note**: 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). +[/note] + +At this stage, PgBouncer will be in a blocked state due to missing [relation/integration](https://charmhub.io/postgresql-k8s/docs/t-integrations#integrations-juju-30-or-relations-juju-29-2) with PostgreSQL DB. + +Integrate them by using the command +```shell +juju integrate postgresql-k8s pgbouncer-k8s +``` +Shortly, `juju status` will report a new blocking reason `Missing relation: database` as it waits for a client to consume the DB service. + +Let's deploy [data-integrator](https://charmhub.io/data-integrator) and request access to database `test123`: +```shell +juju deploy data-integrator --config database-name=test123 +juju integrate data-integrator pgbouncer-k8s +``` +In a couple of seconds, the status will be happy for the entire model: +```shell +Model Controller Cloud/Region Version SLA Timestamp +test16 microk8s microk8s/localhost 3.1.6 unsupported 21:57:34+02:00 + +App Version Status Scale Charm Channel Rev Address Exposed Message +data-integrator active 1 data-integrator stable 13 10.152.183.136 no +pgbouncer-k8s 1.18.0 active 1 pgbouncer-k8s 1/stable 76 10.152.183.84 no +postgresql-k8s 14.9 active 1 postgresql-k8s 14/stable 158 10.152.183.92 no Primary + +Unit Workload Agent Address Ports Message +data-integrator/0* active idle 10.1.12.16 +pgbouncer-k8s/0* active idle 10.1.12.15 +postgresql-k8s/0* active idle 10.1.12.6 Primary +``` + +## Access database +The easiest way to access PostgreSQL is via the [PostgreSQL Command Line Client](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 these values, please run data-integrator action `get-credentials`: +```shell +juju run data-integrator/leader get-credentials +``` +[note type="caution"] +For versions of juju before v3.0, use `juju run-action` instead of `juju run`. +[/note] + +Running the command above should output: +```yaml +postgresql: + database: test123 + endpoints: pgbouncer-k8s-0.pgbouncer-k8s-endpoints.test16.svc.cluster.local:6432 + password: VYm6tg2KkFOBj8mP3IW9O821 + username: relation_id_7 + version: "14.9" +``` + +The IP address of the PgBouncer K8s's host can be found with `juju status`: +```shell +... +App Version Status Scale Charm Channel Rev Address Exposed Message +pgbouncer-k8s 1.18.0 active 1 pgbouncer-k8s 1/stable 76 10.152.183.84 no +``` + +Make sure `psql` is installed with the command `psql --version`. + +To access the PostgreSQL database via PgBouncer, use the port 6432 and your host's IP address: +```shell +psql -h 10.152.183.84 -p 6432 -U relation_id_7 -W -d test123 +``` +Inside MySQL, list DBs available on the host with `show databases`: +```shell +Password for user relation_id_7: VYm6tg2KkFOBj8mP3IW9O821 +psql (14.9 (Ubuntu 14.9-0ubuntu0.22.04.1)) +Type "help" for help. + +test123=> \l + List of databases + Name | Owner | Encoding | Collate | Ctype | Access privileges +-----------+---------------+----------+---------+---------+--------------------------------- +... + test123 | relation_id_5 | UTF8 | C | C.UTF-8 | relation_id_5=CTc/relation_id_5+ + | | | | | relation_id_7=CTc/relation_id_5+ + | | | | | admin=CTc/relation_id_5 +... +``` +[note] +**Note**: If at any point you'd like to leave the PostgreSQL client, enter `Ctrl+D` or type `exit`. +[/note] + +You can now interact with PostgreSQL directly using any [SQL Queries](https://www.postgresql.org/docs/14/sql-syntax.html). + +For example, entering `SELECT VERSION(), CURRENT_DATE;` should output something like: +```shell +test123=> SELECT VERSION(), CURRENT_DATE; + version | current_date +--------------------------------------------------------------------------------------------------------------------------------------+-------------- + PostgreSQL 14.9 (Ubuntu 14.9-0ubuntu0.22.04.1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0, 64-bit | 2023-10-23 +(1 row) +``` + +Feel free to test out any other PostgreSQL queries. When you’re ready to leave the `psql` shell, you can just type `exit`. + +Now you will be in your original shell where you first started the tutorial. Here you can interact with Juju and MicroK8s. + +### 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 pgbouncer-k8s data-integrator +``` + +Now try again to connect to the same PgBouncer K8s you used earlier: +```shell +psql -h 10.152.183.84 -p 6432 -U relation_id_7 -W -d test123 +``` + +This will output an error message because this user no longer exists. +```shell +psql: error: connection to server at "10.152.183.92", port 5432 failed: FATAL: password authentication failed for user "relation_id_7" +``` +This is expected, as `juju remove-relation pgbouncer-k8s data-integrator` also removes the user. + +[note] +**Note**: Data remains on the server at this stage. +[/note] + +Relate the two applications again if you wanted to recreate the user: +```shell +juju integrate data-integrator pgbouncer-k8s +``` +Re-relating generates a new user and password: +```shell +juju run data-integrator/leader get-credentials +``` +You can connect to the database with these 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-enable-security.md b/docs/tutorial/t-enable-security.md new file mode 100644 index 000000000..60475b5e0 --- /dev/null +++ b/docs/tutorial/t-enable-security.md @@ -0,0 +1,77 @@ +# Enable TLS for PgBouncer K8s + +This is part of the [PgBouncer K8s Tutorial](/t/12251). Please refer to this page for more information and the overview of the content. + +## Transport Layer Security (TLS) + +[Transport Layer Security (TLS)](https://en.wikipedia.org/wiki/Transport_Layer_Security) is a protocol used to encrypt data exchanged between two applications. Essentially, it secures data transmitted over a network. + +Typically, enabling TLS internally within a highly available database or between a highly available database and client/server applications, requires domain-specific knowledge and a high level of expertise. This has all been encoded into Charmed PgBouncer. This means (re-)configuring TLS on this charm is readily available and requires minimal effort on your end. + +Again, integrations come in handy here, as TLS is enabled by relating Charmed PostgreSQL to the [Self Signed Certificates Charm](https://charmhub.io/self-signed-certificates). This charm centralises TLS certificate management consistently and handles operations like providing, requesting, and renewing TLS certificates. + +In this section, we will learn how to set up the `pgbouncer`, `data-integrator`, `postgresql`, and `self-signed-certificates` charms to enable TLS encryption. + +[note type="caution"] +**Disclaimer:** In this tutorial, we use [self-signed certificates](https://en.wikipedia.org/wiki/Self-signed_certificate) provided by the [`self-signed-certificates-operator`](https://github.com/canonical/self-signed-certificates-operator). + +**This is not recommended for a production environment.** + +For production environments, check the collection of [Charmhub operators](https://charmhub.io/?q=tls-certificates) that implement the `tls-certificate` interface, and choose the most suitable for your use-case. +[/note] + + +### Configure TLS + +Before enabling TLS on Charmed PostgreSQL VM, we must deploy the `self-signed-certificates` charm: +```shell +juju deploy self-signed-certificates --config ca-common-name="Tutorial CA" +``` + +Wait until the `self-signed-certificates` is up and active, using `juju status --watch 1s` to monitor the progress: +```shell +Model Controller Cloud/Region Version SLA Timestamp +test16 microk8s microk8s/localhost 3.1.6 unsupported 22:24:20+02:00 + +App Version Status Scale Charm Channel Rev Address Exposed Message +data-integrator active 1 data-integrator stable 13 10.152.183.136 no +pgbouncer-k8s 1.18.0 active 2 pgbouncer-k8s 1/stable 76 10.152.183.84 no +postgresql-k8s 14.9 active 2 postgresql-k8s 14/stable 158 10.152.183.92 no +self-signed-certificates active 1 self-signed-certificates stable 72 10.152.183.87 no + +Unit Workload Agent Address Ports Message +data-integrator/0* active idle 10.1.12.16 +pgbouncer-k8s/0* active idle 10.1.12.15 +pgbouncer-k8s/1 active idle 10.1.12.61 +postgresql-k8s/0* active idle 10.1.12.6 Primary +postgresql-k8s/1 active idle 10.1.12.35 +self-signed-certificates/0* active idle 10.1.12.44 +``` + +### Add external TLS certificate +To enable TLS on PgBouncer, relate the two applications: +```shell +juju relate pgbouncer-k8s self-signed-certificates +``` +#### Check the TLS certificate in use: +Use `openssl` to connect to the PostgreSQL through PgBouncer and check the TLS certificate in use: +```shell +> openssl s_client -starttls postgres -connect 10.152.183.84:6432 | grep Issue +depth=1 C = US, CN = Tutorial CA +verify error:num=19:self-signed certificate in certificate chain +``` +Congratulations! Your connection is now using TLS certificate generated by the external application `self-signed-certificates`. + +### Remove external TLS certificate + +To remove the external TLS and return to the locally generated one, un-relate applications: +```shell +juju remove-relation pgbouncer-k8s self-signed-certificates +``` + +#### Check the TLS certificate in use: +```shell +> openssl s_client -starttls postgres -connect 10.152.183.84:6432 | grep Issue +``` + +The connection will fail due to missing SSL without `self-signed-certificates`. \ 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..4270c6850 --- /dev/null +++ b/docs/tutorial/t-managing-units.md @@ -0,0 +1,83 @@ +# Scale your PgBouncer K8s + +This is part of the [PgBouncer K8s Tutorial](/t/12251). Please refer to this page for more information and the overview of the content. + +## Adding and Removing units + +Please check the explanation of scaling Charmed PostgreSQL K8s operator [here](https://charmhub.io/postgresql-k8s/docs/t-managing-units). + +### Add more PgBouncer instances + +You can add two more units to your deployed PgBouncer application by scaling it using: +```shell +juju scale-application pgbouncer-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`: +```shell +Model Controller Cloud/Region Version SLA Timestamp +test16 microk8s microk8s/localhost 3.1.6 unsupported 22:16:20+02:00 + +App Version Status Scale Charm Channel Rev Address Exposed Message +data-integrator active 1 data-integrator stable 13 10.152.183.136 no +pgbouncer-k8s 1.18.0 active 3 pgbouncer-k8s 1/stable 76 10.152.183.84 no +postgresql-k8s 14.9 active 1 postgresql-k8s 14/stable 158 10.152.183.92 no Primary + +Unit Workload Agent Address Ports Message +data-integrator/0* active idle 10.1.12.16 +pgbouncer-k8s/0* active idle 10.1.12.15 +pgbouncer-k8s/1 active idle 10.1.12.61 +pgbouncer-k8s/2 active idle 10.1.12.50 +postgresql-k8s/0* active idle 10.1.12.6 Primary +``` + +You can scale Charmed PostgreSQL in the same way: +```shell +juju scale-application postgresql-k8s 3 +``` +Make sure all units are active using `juju status`: +```shell +Model Controller Cloud/Region Version SLA Timestamp +test16 microk8s microk8s/localhost 3.1.6 unsupported 22:18:00+02:00 + +App Version Status Scale Charm Channel Rev Address Exposed Message +data-integrator active 1 data-integrator stable 13 10.152.183.136 no +pgbouncer-k8s 1.18.0 active 3 pgbouncer-k8s 1/stable 76 10.152.183.84 no +postgresql-k8s 14.9 active 3 postgresql-k8s 14/stable 158 10.152.183.92 no + +Unit Workload Agent Address Ports Message +data-integrator/0* active idle 10.1.12.16 +pgbouncer-k8s/0* active idle 10.1.12.15 +pgbouncer-k8s/1 active idle 10.1.12.61 +pgbouncer-k8s/2 active idle 10.1.12.50 +postgresql-k8s/0* active idle 10.1.12.6 Primary +postgresql-k8s/1 active idle 10.1.12.35 +postgresql-k8s/2 active idle 10.1.12.39 +``` + +### Remove extra members +Removing a unit from the application scales the replicas down. +```shell +juju scale-application pgbouncer-k8s 2 +``` +```shell +juju scale-application postgresql-k8s 2 +``` + +You’ll know that the replica was successfully removed when `juju status --watch 1s` reports: +```shell +Model Controller Cloud/Region Version SLA Timestamp +test16 microk8s microk8s/localhost 3.1.6 unsupported 22:19:10+02:00 + +App Version Status Scale Charm Channel Rev Address Exposed Message +data-integrator active 1 data-integrator stable 13 10.152.183.136 no +pgbouncer-k8s 1.18.0 active 2 pgbouncer-k8s 1/stable 76 10.152.183.84 no +postgresql-k8s 14.9 active 2 postgresql-k8s 14/stable 158 10.152.183.92 no + +Unit Workload Agent Address Ports Message +data-integrator/0* active idle 10.1.12.16 +pgbouncer-k8s/0* active idle 10.1.12.15 +pgbouncer-k8s/1 active idle 10.1.12.61 +postgresql-k8s/0* active idle 10.1.12.6 Primary +postgresql-k8s/1 active idle 10.1.12.35 +``` \ 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..3d944b354 --- /dev/null +++ b/docs/tutorial/t-overview.md @@ -0,0 +1,27 @@ +# PgBouncer K8s tutorial + +The PgBouncer K8s Operator delivers automated operations management from day 0 to day 2 on the [PgBouncer](http://www.pgbouncer.org/) - the lightweight connection pooler for PostgreSQL. It is an open source, end-to-end, production-ready data platform on top of [Juju](https://juju.is/). + +As a first step, this tutorial will show you how to get PgBouncer K8s up and running. Then, you will learn a variety of operations such as adding replicas and 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 PgBouncer K8s using a single command. +- Configure TLS certificate in one command. + +## Requirements + +While this tutorial intends to guide and teach you as you deploy PgBouncer K8s, it will be most beneficial if: +- You are familiar with basic terminal commands. +- You are familiar with basic PostgreSQL and PgBouncer concepts. +- You are familiar with [Charmed PostgreSQL K8s](https://charmhub.io/postgresql-k8s) +- Your machine fulfils the [minimum requirements](https://charmhub.io/postgresql-k8s/docs/r-requirements). + +## Step-by-step guide + +Here’s an overview of the steps you will take in this tutorial: +* [Set up the environment](/t/12252) +* [Deploy PgBouncer](/t/12253) +* [Managing your units](/t/12254) +* [Enable security](/t/12255) +* [Clean up your environment](/t/12256) \ 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..12ae24b27 --- /dev/null +++ b/docs/tutorial/t-setup-environment.md @@ -0,0 +1,52 @@ +# Environment Setup + +This is part of the [PgBouncer K8s Tutorial](/t/12251). 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](https://charmhub.io/pgbouncer-k8s/docs/r-requirements). + +## Multipass environment +[Multipass](https://multipass.run/) is a quick and easy way to launch virtual machines running Ubuntu. It uses the [cloud-init](https://cloud-init.io/) standard to install and configure all the necessary parts automatically. + +Install Multipass from [Snap](https://snapcraft.io/multipass): +```shell +sudo snap install multipass +``` + +Launch a new VM using the [charm-dev](https://github.com/canonical/multipass-blueprints/blob/main/v1/charm-dev.yaml) cloud-init config: +```shell +multipass launch --cpus 4 --memory 8G --disk 30G --name my-vm charm-dev +``` +[note type=""] +**Note**: All 'multipass launch' params are [described here](https://multipass.run/docs/launch-command). +[/note] + +The Multipass [list of commands](https://multipass.run/docs/multipass-cli-commands) is short and self-explanatory. For example, to show all running VMs, just run the command `multipass list`. + +As soon as a new VM has started, access it using +```shell +multipass shell my-vm +``` + +[note] +**Note**: If at any point you'd like to leave a Multipass VM, enter `Ctrl+D` or type `exit`. +[/note] + +All the parts have been pre-installed inside the 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 + PgBouncer K8s. + +Set up a specific model 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 microk8s microk8s/localhost 3.1.6 unsupported 11:56:38+01:00 + +Model "admin/tutorial" is empty. +``` \ No newline at end of file