Skip to content

Add Tutorial and Landing page and update README and CONTRIBUTING guides #115

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 28, 2023
Merged

Add Tutorial and Landing page and update README and CONTRIBUTING guides #115

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
22ad65f
Add Tutorial and Landing page and update README and CONTRIBUTING guides
taurus-forever Mar 20, 2023
64edd46
Typo fix
taurus-forever Mar 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ this operator.
- Generally, before developing enhancements to this charm, you should consider [opening an issue
](https://github.com/canonical/postgresql-k8s-operator/issues) explaining your use case.
- If you would like to chat with us about your use-cases or proposed implementation, you can reach
us at [Canonical Mattermost public channel](https://chat.charmhub.io/charmhub/channels/charm-dev)
us at [public Canonical Data Platform channel](https://chat.charmhub.io/charmhub/channels/data-platform)
or [Discourse](https://discourse.charmhub.io/).
- Familiarising yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) library
will help you a lot when working on new features or bug fixes.
Expand Down Expand Up @@ -65,4 +65,4 @@ microk8s enable rbac
juju deploy ./postgresql-k8s_ubuntu-22.04-amd64.charm \
--resource postgresql-image=dataplatformoci/postgres-patroni \
--trust
```
```
98 changes: 32 additions & 66 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,92 +1,73 @@
# Charmed PostgreSQL Kubernetes Operator
# Charmed PostgreSQL K8s Operator

## Description

The Charmed PostgreSQL Kubernetes Operator deploys and operates the
[PostgreSQL](https://www.postgresql.org/about/) database on Kubernetes clusters.
This repository contains a [Juju K8s Charm](https://charmhub.io/postgresql-k8s) for deploying [PostgreSQL](https://www.postgresql.org/about/) on Kubernetes.
To deploy on virtual machines, please use [Charmed PostgreSQL Operator](https://charmhub.io/postgresql).

This operator provides a Postgres database with replication enabled (one master instance and one or
more hot standby replicas). The Operator in this repository is a Python script which wraps the LTS
Postgres versions distributed by [Ubuntu](https://hub.docker.com/r/ubuntu/postgres) and adding
[Patroni](https://github.com/zalando/patroni) on top of it, providing lifecycle management and
handling events (install, configure, integrate, remove, etc).
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 script which wraps PostgreSQL versions distributed by Ubuntu Jammy series and adding [Patroni](https://github.com/zalando/patroni) on top of it, providing lifecycle management and handling events (install, configure, integrate, remove, etc).

## Usage

### Basic Usage
Bootstrap a Kubernetes (e.g. [Multipass-based MicroK8s](https://discourse.charmhub.io/t/charmed-environment-charm-dev-with-canonical-multipass/8886)) and create a new Juju model:

```shell
juju add-model postgresql
```

### Basic Usage
To deploy a single unit of PostgreSQL using its default configuration.

```shell
juju deploy postgresql-k8s --channel edge --trust
```
Note: `--trust` is required because the charm and Patroni need to create some K8s resources.

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

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.
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 <number_of_units> --trust
```

To retrieve primary replica one can use the action `get-primary` on any of the units running
PostgreSQL.

To retrieve primary replica one can use the action `get-primary` on any of the units running PostgreSQL.
```shell
juju run-action postgresql-k8s/<unit_number> get-primary --wait
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.

### Replication

#### Adding Replicas

To add more replicas one can use the `juju scale-application` functionality i.e.

To add more replicas one can use the `juju add-unit` functionality i.e.
```shell
juju scale-application postgresql-k8s -n <number_of_units>
juju add-unit postgresql-k8s -n <number_of_units>
```

The implementation of `scale-application` allows the operator to add more than one unit, but
functions internally by adding one replica at a time, avoiding multiple replicas syncing from the
primary at the same time.
The implementation of `add-unit` allows the operator to add more than one unit, but functions internally by adding one replica at a time, avoiding multiple replicas syncing from the primary at the same time.

#### Removing Replicas

Similarly to scale down the number of replicas the `juju scale-application` functionality may be
used i.e.

Similarly to scale down the number of replicas the `juju remove-unit` functionality may be used i.e.
```shell
juju scale-application postgresql-k8s -n <number_of_units>
juju remove-unit postgresql-k8s -n <number_of_units>
```

The implementation of `scale-application` allows the operator to remove more than one unit. The
functionality of `scale-application` functions by removing one replica at a time to avoid downtime.
The implementation of `remove-unit` allows the operator to remove more than one unit. The functionality of `remove-unit` functions by removing one replica at a time to avoid downtime.

### Password rotation

#### Charm users

For users used internally by the Charmed PostgreSQL Kubernetes Operator an action can be used to
rotate their passwords.

For users used internally by the Charmed PostgreSQL K8s Operator an action can be used to rotate their passwords.
```shell
juju run-action postgresql-k8s/0 set-password username=<username> password=<password> --wait
juju run-action postgresql-k8s/leader set-password username=<username> password=<password> --wait
```

Currently, the users used by the operator are `operator` and `replication`. Those users should not
be used outside the operator.
Note: currently, the users used by the operator are `operator` and `replication`. Those users should not be used outside the operator.

#### Related applications users

To rotate the passwords of users created for related applications the relation should be removed
and the application should be related again to the Charmed PostgreSQL Kubernetes Operator. That
process will generate a new user and password for the application (removing the old user).
To rotate the passwords of users created for related applications the relation should be removed and the application should be related again to the Charmed PostgreSQL K8s Operator. That process will generate a new user and password for the application (removing the old user).

## Integrations (Relations)

Expand Down Expand Up @@ -123,25 +104,20 @@ juju integrate postgresql-k8s application
```

To remove a relation:

```shell
juju remove-relation postgresql-k8s application
```

#### Legacy `pgsql` interface:

We have also added support for the two database legacy relations from the
[original version](https://launchpad.net/charm-k8s-postgresql) of the charm via the `pgsql`
interface. Please note that these relations will be deprecated.

We have also added support for the two database legacy relations from the [original version](https://launchpad.net/postgresql-charm) of the charm via the `pgsql` interface. Please note that these relations will be deprecated.
```shell
juju relate postgresql-k8s:db finos-waltz-k8s
juju relate postgresql-k8s:db-admin discourse-k8s
```

#### `tls-certificates` interface:

The Charmed PostgreSQL Kubernetes Operator also supports TLS encryption on internal and external
The Charmed PostgreSQL K8s Operator also supports TLS encryption on internal and external
connections. To enable TLS:

```shell
Expand All @@ -155,26 +131,16 @@ juju relate postgresql-k8s tls-certificates-operator
juju remove-relation postgresql-k8s tls-certificates-operator
```

Note: The TLS settings shown here are for self-signed-certificates, which are not recommended for
production clusters. The TLS Certificates Operator offers a variety of configurations. Read more on
the TLS Certificates Operator [here](https://charmhub.io/tls-certificates-operator).
Note: The TLS settings shown here are for self-signed-certificates, which are not recommended for production clusters. The TLS Certificates Operator offers a variety of configurations. Read more on the TLS Certificates Operator [here](https://charmhub.io/tls-certificates-operator).

## Security

Security issues in the Charmed PostgreSQL Kubernetes Operator can be reported through
[LaunchPad](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File). Please do not file GitHub
issues about security issues.
Security issues in the Charmed PostgreSQL K8s Operator can be reported through [LaunchPad](https://wiki.ubuntu.com/DebuggingSecurity#How%20to%20File). Please do not file GitHub issues about security issues.

## Contributing

Please see the [Juju SDK docs](https://juju.is/docs/sdk) for guidelines on enhancements to this
charm following best practice guidelines, and
[CONTRIBUTING.md](https://github.com/canonical/postgresql-k8s-operator/blob/main/CONTRIBUTING.md)
for developer guidance.
Please see the [Juju SDK docs](https://juju.is/docs/sdk) for guidelines on enhancements to this charm following best practice guidelines, and [CONTRIBUTING.md](https://github.com/canonical/postgresql-k8s-operator/blob/main/CONTRIBUTING.md) for developer guidance.

## 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.org/ftp/source/), which [is licensed](https://www.postgresql.org/about/licence/) under PostgreSQL License, a liberal Open Source license, similar to the BSD or MIT licenses.

The Charmed PostgreSQL Kubernetes Operator is free software, distributed under the Apache Software
License, version 2.0. See
[LICENSE](https://github.com/canonical/postgresql-k8s-operator/blob/main/LICENSE) for more
information.
## Trademark Notice
PostgreSQL is a trademark or registered trademark of PostgreSQL Global Development Group. Other trademarks are property of their respective owners.
28 changes: 28 additions & 0 deletions docs/landing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
## 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]()</br> Get started - a hands-on introduction to using Charmed PostgreSQL K8s operator for new users </br> | [How-to guides -- Coming Soon]() </br> Step-by-step guides covering key operations and common tasks |
| [Reference -- Coming Soon]() </br> Technical information - specifications, APIs, architecture | [Explanation -- Coming Soon]() </br> 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]
Loading