Charmed PostgreSQL VM
- By Canonical Data Platform
- Databases
Channel | Revision | Published | Runs on |
---|---|---|---|
latest/stable | 345 | 09 Nov 2023 | |
latest/stable | 239 | 09 Feb 2022 | |
latest/stable | 226 | 01 Apr 2021 | |
14/stable | 430 | 28 Jun 2024 | |
14/stable | 429 | 28 Jun 2024 | |
14/candidate | 468 | 02 Sep 2024 | |
14/candidate | 467 | 02 Sep 2024 | |
14/beta | 468 | 02 Sep 2024 | |
14/beta | 467 | 02 Sep 2024 | |
14/edge | 472 | Yesterday | |
14/edge | 471 | Yesterday |
juju deploy postgresql --channel 14/edge
Deploy universal operators easily with Juju, the Universal Operator Lifecycle Manager.
Platform:
Architecture
PostgreSQL is one of the most popular open source database. The “Charmed PostgreSQL” is a Juju-based operator to deploy and support PostgreSQL from day 0 to day 2, it is based on the PostgreSQL Community Edition using the Patroni to manage PostgreSQL cluster based on PostgreSQL synchronous replication.
HLD (High Level Design)
The charm design leverages on the SNAP “charmed-postgresql” which is deployed by Juju on the specified VM/MAAS/bare-metal machine based on Ubuntu Jammy/22.04. SNAP allows to run PostgreSQL service(s) in a secure and isolated environment (strict confinement). The installed SNAP:
> juju ssh postgresql/0 snap list charmed-postgresql
Name Version Rev Tracking Publisher Notes
charmed-postgresql 14.9 70 latest/stable dataplatformbot held
The SNAP ships the following components:
- PostgreSQL (based on Ubuntu APT package “postgresql”)
- PgBouncer (based on Canonical backport)
- Patroni (based on Canonical backport)
- pgBackRest (based on Canonical backport)
- Prometheus PostgreSQL Exporter (based on Canonical backport)
- Prometheus PgBouncer Exporter (based on Canonical backport)
- Prometheus Grafana dashboards and Loki alert rules are part of the charm revision (and missing in SNAP).
Versions of all the components above are carefully chosen to fit functionality of each other.
The Charmed PostgreSQL unit consisting of a several services which are enabled/activated accordingly to the setup:
> juju ssh postgresql/0 snap services charmed-postgresql
Service Startup Current Notes
charmed-postgresql.patroni enabled active -
charmed-postgresql.pgbackrest-service enabled active -
charmed-postgresql.prometheus-postgres-exporter enabled active -
The patroni
snap service is a main PostgreSQL instance which is normally up and running right after the charm deployment.
The pgbackrest
snap service is a backup framework for PostgreSQL. It is disabled if Backup is not configured.
The prometheus-postgres-exporter
service is activated after the relation with COS Monitoring only.
Note: it is possible to star/stop/restart snap services manually but it is NOT recommended to avoid a split brain with a charm state machine! Do it with a caution!!!
Important: all snap resources must be executed under the special user
snapd_daemon
only!
The snap “charmed-postgresql” also ships list of tools used by charm:
charmed-postgresql.psql
(aliaspsq
) - is PostgreSQL interactive terminal.charmed-postgresql.patronictl
- a tool to monitor and manage Patroni.charmed-postgresql.pgbackrest
- a tool to backup/restore PostgreSQL DB.
Integrations
PgBouncer
PgBouncer is a lightweight connection pooler for PostgreSQL that provides transparent routing between your application and back-end PostgreSQL Servers. The “PgBouncer” is an independent charm “Charmed PostgreSQL” can be related with.
TLS Certificates Operator
TLS Certificates charm responsible for distributing certificates through relationship. Certificates are provided by the operator through Juju configs. For the playground deployments, the self-signed operator is available as well.
S3 Integrator
S3 Integrator is an integrator charm for providing S3 credentials to Charmed PostgreSQL which seek to access shared S3 data. Store the credentials centrally in the integrator charm and relate consumer charms as needed.
Data Integrator
Data Integrator charm is a solution to request DB credentials for non-native Juju applications. Not all applications implement a data_interfaces relation but allow setting credentials via config. Also, some of the applications are run outside of juju. This integrator charm allows receiving credentials which can be passed into application config directly without implementing juju-native relation.
PostgreSQL Test App
The charm “PostgreSQL Test App” is a Canonical test application to validate the charm installation / functionality and perform the basic performance tests.
Grafana
Grafana is an open-source visualization tools that allows to query, visualize, alert on, and visualize metrics from mixed datasources in configurable dashboards for observability. This charms is shipped with its own Grafana dashboard and supports integration with the Grafana Operator to simplify observability. Please follow COS Monitoring setup.
Loki
Loki is an open-source fully-featured logging system. This charms is shipped with support for the Loki Operator to collect the generated logs. Please follow COS Monitoring setup.
Prometheus
Prometheus is an open-source systems monitoring and alerting toolkit with a dimensional data model, flexible query language, efficient time series database and modern alerting approach. This charm is shipped with a Prometheus exporters, alerts and support for integrating with the Prometheus Operator to automatically scrape the targets. Please follow COS Monitoring setup.
LLD (Low Level Design)
Please check the charm state machines displayed on workflow diagrams. The low-level logic is mostly common for both VM and K8s charms.
Juju Events
Accordingly to the Juju SDK: “an event is a data structure that encapsulates part of the execution context of a charm”.
For this charm, the following events are observed:
- on_install: install the snap “charmed-postgresql” and perform basic preparations to bootstrap the cluster on the first leader (or join the already configured cluster).
- leader-elected: generate all the secrets to bootstrap the cluster.
- leader-settings-changed: Handle the leader settings changed event.
- start: Init/setting up the cluster node.
- config_changed: usually fired in response to a configuration change using the GUI or CLI. Create and set default cluster and cluster-set names in the peer relation databag (on the leader only).
- update-status: Takes care of workload health checks.
Charm Code Overview
The “src/charm.py” is the default entry point for a charm and has the PostgresqlOperatorCharm
Python class which inherits from CharmBase.
CharmBase is the base class from which all Charms are formed, defined by Ops (Python framework for developing charms). See more information in Charm.
The __init__
method guarantees that the charm observes all events relevant to its operation and handles them.
The VM and K8s charm flavors shares the codebase via charm libraries in lib/charms/postgresql_k8s/v0/ (of K8s flavor of the charm!):
> charmcraft list-lib postgresql-k8s
Library name API Patch
postgresql 0 12
postgresql_tls 0 7