public_git
/
postgres-operator
mirror of https://github.com/zalando/postgres-operator.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

update user docs and README

This commit is contained in:
Felix Kunde 2019-07-11 17:05:04 +02:00
parent a87b6edc48
commit 0a5158c492
2 changed files with 30 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
README.md
View File

@ -8,33 +8,31 @@
<img src="docs/diagrams/logo.png" width="200"> <img src="docs/diagrams/logo.png" width="200">
The Postgres operator manages PostgreSQL clusters on Kubernetes. Configuration The Postgres Operator enables highly-available [PostgreSQL](https://www.postgresql.org/)
happens only via manifests. Therefore, it integrates easily in automated CI/CD clusters on Kubernetes (K8s) powered by [Patroni](https://github.com/zalando/spilo).
It is configured only through manifests to ease integration into automated CI/CD
pipelines with no access to Kubernetes directly. pipelines with no access to Kubernetes directly.
By default, the operator is building up on two other Open Source projects The Postgres Operator has been developed at Zalando and is being used in
developed at Zalando. [Spilo](https://github.com/zalando/spilo) provides the production for over two years.
Docker image that contains PostgreSQL incl. some pre-compiled extensions. Spilo
also includes [Patroni](https://github.com/zalando/spilo) to manage highly
available Postgres cluster powered by streaming replication.
## Getting started ## Getting started
For a quick first impression follow the instructions of [this](docs/quickstart.md) For a quick first impression follow the instructions of this
tutorial. [tutorial](docs/quickstart.md).
## Documentation ## Documentation
There is a browser-friendly version of this documentation at There is a browser-friendly version of this documentation at
[postgres-operator.readthedocs.io](https://postgres-operator.readthedocs.io) [postgres-operator.readthedocs.io](https://postgres-operator.readthedocs.io)
* [concepts](docs/index.md) * [How it works](docs/index.md)
* [user documentation](docs/user.md) * [The Postgres experience on K8s](docs/user.md)
* [administrator documentation](docs/administrator.md) * [DBA options - from RBAC to backup](docs/administrator.md)
* [developer documentation](docs/developer.md) * [Debug and extend the operator](docs/developer.md)
* [operator configuration reference](docs/reference/operator_parameters.md) * [Configuration options](docs/reference/operator_parameters.md)
* [cluster manifest reference](docs/reference/cluster_manifest.md) * [Postgres manifest reference](docs/reference/cluster_manifest.md)
* [command-line options and environment variables](docs/reference/command_line_and_environment.md) * [Command-line options and environment variables](docs/reference/command_line_and_environment.md)
## Google Summer of Code ## Google Summer of Code

33
docs/user.md
View File

@ -33,7 +33,7 @@ spec:
version: "10" version: "10"
``` ```
If you have clone the Postgres Operator [repository](https://github.com/zalando/postgres-operator) Once you cloned the Postgres Operator [repository](https://github.com/zalando/postgres-operator)
you can find this example also in the manifests folder: you can find this example also in the manifests folder:
```bash ```bash
@ -93,8 +93,8 @@ for an example of `zalando` role, defined with `superuser` and `createdb` flags.
Manifest roles are defined as a dictionary, with a role name as a key and a Manifest roles are defined as a dictionary, with a role name as a key and a
list of role options as a value. For a role without any options it is best to list of role options as a value. For a role without any options it is best to
supply the empty list `[]`. It is also possible to leave this field empty as in supply the empty list `[]`. It is also possible to leave this field empty as in
our example manifests, but in certain cases such empty field may removed by K8s our example manifests. In certain cases such empty field may be missing later
[due to the `null` value it gets](https://kubernetes.io/docs/concepts/overview/object-management-kubectl/declarative-config/#how-apply-calculates-differences-and-merges-changes) removed by K8s [due to the `null` value it gets](https://kubernetes.io/docs/concepts/overview/object-management-kubectl/declarative-config/#how-apply-calculates-differences-and-merges-changes)
(`foobar_user:` is equivalent to `foobar_user: null`). (`foobar_user:` is equivalent to `foobar_user: null`).
The operator accepts the following options: `superuser`, `inherit`, `login`, The operator accepts the following options: `superuser`, `inherit`, `login`,
@ -107,8 +107,8 @@ The operator automatically generates a password for each manifest role and
places it in the secret named places it in the secret named
`{username}.{team}-{clustername}.credentials.postgresql.acid.zalan.do` in the `{username}.{team}-{clustername}.credentials.postgresql.acid.zalan.do` in the
same namespace as the cluster. This way, the application running in the same namespace as the cluster. This way, the application running in the
K8s cluster and working with the database can obtain the password right K8s cluster and connecting to Postgres can obtain the password right from the
from the secret, without ever sharing it outside of the cluster. secret, without ever sharing it outside of the cluster.
At the moment it is not possible to define membership of the manifest role in At the moment it is not possible to define membership of the manifest role in
other roles. other roles.
@ -247,7 +247,7 @@ spec:
Here `cluster` is a name of a source cluster that is going to be cloned. A new Here `cluster` is a name of a source cluster that is going to be cloned. A new
cluster will be cloned from S3, using the latest backup before the `timestamp`. cluster will be cloned from S3, using the latest backup before the `timestamp`.
In this case, `uid` field is also mandatory - operator will use it to find a In this case, `uid` field is also mandatory - operator will use it to find a
correct key inside an S3 bucket. You can find this field from metadata of a correct key inside an S3 bucket. You can find this field in the metadata of the
source cluster: source cluster:
```yaml ```yaml
@ -286,8 +286,8 @@ Standby clusters are like normal cluster but they are streaming from a remote
cluster. As the first version of this feature, the only scenario covered by cluster. As the first version of this feature, the only scenario covered by
operator is to stream from a WAL archive of the master. Following the more operator is to stream from a WAL archive of the master. Following the more
popular infrastructure of using Amazon's S3 buckets, it is mentioned as popular infrastructure of using Amazon's S3 buckets, it is mentioned as
`s3_wal_path` here. To make a cluster a standby add a `standby` section in the `s3_wal_path` here. To start a cluster as standby add the following `standby`
YAML file as follows. section in the YAML file:
```yaml ```yaml
spec: spec:
@ -297,16 +297,15 @@ spec:
Things to note: Things to note:
- An empty string is provided in `s3_wal_path` of the standby cluster will - An empty string in the `s3_wal_path` field of the standby cluster will result
result in error and no statefulset will be created. in an error and no statefulset will be created.
- Only one pod can be deployed for stand-by cluster. - Only one pod can be deployed for stand-by cluster.
- To manually promote the standby_cluster, use `patronictl` and remove config - To manually promote the standby_cluster, use `patronictl` and remove config
entry. entry.
- There is no way to transform a non-standby cluster to become a standby cluster - There is no way to transform a non-standby cluster to a standby cluster
through operator. Hence, if a cluster is created without standby section in through the operator. Adding the standby section to the manifest of a running
YAML and later modified by adding that section, there will be no effect on Postgres cluster will have no effect. However, it can be done through Patroni
the cluster. However, it can be done through Patroni by adding the by adding the [standby_cluster] (https://github.com/zalando/patroni/blob/bd2c54581abb42a7d3a3da551edf0b8732eefd27/docs/replica_bootstrap.rst#standby-cluster)
[standby_cluster] (https://github.com/zalando/patroni/blob/bd2c54581abb42a7d3a3da551edf0b8732eefd27/docs/replica_bootstrap.rst#standby-cluster)
section using `patronictl edit-config`. Note that the transformed standby section using `patronictl edit-config`. Note that the transformed standby
cluster will not be doing any streaming. It will be in standby mode and allow cluster will not be doing any streaming. It will be in standby mode and allow
read-only transactions only. read-only transactions only.
@ -407,7 +406,7 @@ actions:
Fist step has a limitation, AWS rate-limits this operation to no more than once Fist step has a limitation, AWS rate-limits this operation to no more than once
every 6 hours. Note, that if the statefulset is scaled down before resizing the every 6 hours. Note, that if the statefulset is scaled down before resizing the
size changes are only applied to the volumes attached to the running pods. The new size is only applied to the volumes attached to the running pods. The
size of volumes that correspond to the previously running pods is not changed. size of volumes that correspond to the previously running pods is not changed.
## Logical backups ## Logical backups
@ -422,7 +421,7 @@ parameter in the spec section:
The operator will create and sync a K8s cron job to do periodic logical backups The operator will create and sync a K8s cron job to do periodic logical backups
of this particular Postgres cluster. Due to the [limitation of K8s cron jobs](https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/#cron-job-limitations) of this particular Postgres cluster. Due to the [limitation of K8s cron jobs](https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/#cron-job-limitations)
it is highly advisable to set up additional monitoring for this feature; such it is highly advisable to set up additional monitoring for this feature; such
monitoring is outside of the scope of operator responsibilities. See monitoring is outside the scope of operator responsibilities. See
[configuration reference](reference/cluster_manifest.md) and [configuration reference](reference/cluster_manifest.md) and
[administrator documentation](administrator.md) for details on how backups are [administrator documentation](administrator.md) for details on how backups are
executed. executed.