canonical / postgresql-k8s-operator

A Charmed Operator for running PostgreSQL on Kubernetes

Charmed PostgreSQL K8s operator

Description

This repository contains a Juju Charm for deploying PostgreSQL on Kubernetes.

To deploy on virtual machines, please use Charmed PostgreSQL operator.

Usage

Bootstrap a Kubernetes (e.g. Multipass-based MicroK8s) and create a new model using Juju 2.9+:

juju add-model postgresql-k8s
juju deploy postgresql-k8s --channel 14 --trust

Note: the --trust flag is required because the charm and Patroni need to create some K8s resources.

Note: the above model must be created on K8s environment. Use another charm for VMs!

To confirm the deployment, you can run:

juju status --watch 1s

Once PostgreSQL starts up, it will be running on the default port (5432).

If required, you can remove the deployment completely by running:

juju destroy-model postgresql-k8s --destroy-storage --yes

Note: the --destroy-storage will delete any data persisted by PostgreSQL.

Documentation

This operator provides a PostgreSQL database with replication enabled: one primary instance and one (or more) hot standby replicas. The Operator in this repository is a Python-based framework which wraps PostgreSQL distributed by Ubuntu Jammy and adding Patroni on top of it, providing lifecycle management and handling events (install, configure, integrate, remove, etc).

Please follow the tutorial guide with detailed explanation how to access DB, configure cluster, change credentials and/or enable TLS.

Integrations (relations)

The charm supports modern postgresql_client and legacy pgsql interfaces (in a backward compatible mode).

Note: do NOT relate both modern and legacy interfaces simultaneously!

Modern interfaces

This charm provides modern 'postgresql_client' interface. Applications can easily connect PostgreSQL using 'data_interfaces' library from 'data-platform-libs'.

Modern postgresql_client interface (database endpoint):

Adding a relation is accomplished with juju relate (or juju integrate for Juju 3.x) via endpoint database. Example:

# Deploy Charmed PostgreSQL cluster with 3 nodes
juju deploy postgresql-k8s -n 3 --trust --channel 14

# Deploy the relevant application charms
juju deploy mycharm

# Relate PostgreSQL with your application
juju relate postgresql-k8s:database mycharm:database

# Check established relation (using postgresql_client interface):
juju status --relations

# Example of the properly established relation:
# > Relation provider          Requirer          Interface          Type
# > postgresql-k8s:database    mycharm:database  postgresql_client  regular

Legacy interfaces

Note: Legacy relations are deprecated and will be discontinued on future releases. Usage should be avoided.

Legacy pgsql interface (db and db-admin endpoints):

This charm supports legacy interface pgsql from the previous PostgreSQL charm:

juju deploy postgresql-k8s --trust --channel 14
juju deploy finos-waltz-k8s --channel edge
juju relate postgresql-k8s:db finos-waltz-k8s

Note: The endpoint db-admin provides the same legacy interface pgsql with PostgreSQL admin-level privileges. It is NOT recommended to use it from security point of view.

OCI Images

This charm uses pinned and tested version of the charmed-postgresql ROCK image.

Security

Security issues in the Charmed PostgreSQL K8s Operator can be reported through LaunchPad. Please do not file GitHub issues about security issues.

Contributing

Please see the Juju SDK docs for guidelines on enhancements to this charm following best practice guidelines, and CONTRIBUTING.md for developer guidance.

License

The Charmed PostgreSQL K8s Operator is distributed under the Apache Software License, version 2.0. It installs/operates/depends on PostgreSQL, which is licensed 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.