Architecture

PostgreSQL is one of the most popular open source database. The “Charmed PostgreSQL K8s” 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.

Juju K8s Concept

The charm design leverages the sidecar pattern to allow multiple containers in each pod with Pebble running as the workload container’s entrypoint.

Pebble is a lightweight, API-driven process supervisor that is responsible for configuring processes to run in a container and controlling those processes throughout the workload lifecycle.

Pebble services are configured through layers, and the following containers represent each one a layer forming the effective Pebble configuration, or pebble plan:

1. a charm container runs Juju operator code: juju ssh postgresql-k8s/0 bash
2. a postgresql (workload) container runs the PostgreSQL application along with other services (like monitoring metrics exporters, etc): juju ssh --container postgresql postgresql-k8s/0 bash

As a result, if you run a kubectl get pods on a namespace named for the Juju model you’ve deployed the “Charmed PostgreSQL K8s” charm into, you’ll see something like the following:

NAME                READY   STATUS    RESTARTS   AGE
postgresql-k8s-0    2/2     Running   0          65m

This shows there are 2 containers in the pod: charm and workload mentioned above.

And if you run kubectl describe pod postgresql-k8s-0, all the containers will have as Command /charm/bin/pebble. That’s because Pebble is responsible for the processes startup as explained above (see troubleshooting for more details.).

HLD (High Level Design)

The “Charmed PostgreSQL K8s” (workload container) based on postgresql-image resource defined in the charm metadata.yaml. It is an official Canonical “charmed-postgresql” OCI/Rock image, which is recursively based on Canonical SNAP “charmed-postgresql” (read more about the SNAP details here).

Charmcraft uploads an image as a charm resource to Charmhub during the publishing, as described in the Juju SDK How-to guides.

The charm supports Juju deploymed to all Kubernetes environments: MicroK8s, Charmed Kubernetes, GKE, Amazon EKS, …

The OCI/Rock ships the following components:

• PostgreSQL Community Edition (based on SNAP “charmed-postgresql”)
• Patroni (based on SNAP “charmed-postgresql”)
• PgBouncer (based on SNAP “charmed-postgresql”)
• pgBackRest (based on SNAP “charmed-postgresql”)
• Prometheus PostgreSQL Exporter (based on SNAP “charmed-postgresql”)
• Prometheus PgBouncer Exporter (based on SNAP “charmed-postgresql”)
• Prometheus Grafana dashboards and Loki alert rules are part of the charm revision (and missing in SNAP).

SNAP-based rock images guarantee the same components versions and functionality between VM and K8s charm flavors.

Pebble runs layers of all the currently enabled services, e.g. monitoring, backups, etc:

> juju ssh --container postgresql postgresql-k8s/0  /charm/bin/pebble services
Service            Startup   Current   Since
metrics_server     enabled   active    today at 21:42 UTC
pgbackrest server  disabled  inactive  -
postgresql         enabled   active    today at 21:42 UTC

The postgresql is a main Pebble service which is normally up and running right after the charm deployment.

All metrics_server Pebble service is activated after the relation with COS Monitoring only.

Note: it is possible to star/stop/restart pebble services manually but it is NOT recommended to avoid a split brain with a charm state machine! Do it with a caution!!!

Important: all pebble resources must be executed under the proper user (defined in user:group options of pebble layer)!

The rock “charmed-postgresql” also ships list of tools used by charm:

• psql - PostgreSQL client to connect the database.
• patronictl - a tool to monitor/manage Patroni.
• pgbackrest - a framework to backup and restore PostgreSQL.

Integrations

PgBouncer

PgBouncer is a lightweight connection pooler for PostgreSQL that provides transparent routing between your application and back-end PostgreSQL Servers. The “PgBouncer K8s” is an independent charm “Charmed PostgreSQL K8s” 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 charm flavors.

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:

1. postgresql_pebble_ready: informs charm about the availability of the rock “charmed-postgresql”-based workload K8s container. Also performs basic preparations to bootstrap the cluster on the first leader (or join the already configured cluster).
2. leader-elected: generate all the secrets to bootstrap the cluster.
3. 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).
4. 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