Skip to content

Commit 86010a1

Browse files
jsilvelajlong49sxd
authored
docs: tidy up the YAML samples (#310)
Some of the sample files were not working or having missing options, also the names were not quite right. The `samples.md` file was updated with a new format defining the usage for the sample files and with the prerequisites needed for every sample making easier to test and use those sample files. Signed-off-by: Jonathan Gonzalez V <jonathan.gonzalez@enterprisedb.com> Co-authored-by: John Long <john.long@enterprisedb.com> Co-authored-by: Jonathan Gonzalez V <jonathan.gonzalez@enterprisedb.com>
1 parent fb05c0c commit 86010a1

11 files changed

Lines changed: 167 additions & 24 deletions

‎docs/README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,12 @@ docker run --rm -v "$(pwd):$(pwd)" -w "$(pwd)" -p 8000:8000 \
1919
minidocks/mkdocs \
2020
mkdocs serve -a 0.0.0.0:8000
2121
```
22+
23+
## Reminders
24+
25+
If you added samples to `docs/src/samples` or modified existing samples, please
26+
consider if they should be included in the curated [list of examples](src/samples.md)
27+
28+
And please help keeping the samples in the curated list, as well as any samples
29+
named `cluster-example-*` in runnable condition.
30+
These can be a big help for beginners.

‎docs/src/quickstart.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,3 +140,7 @@ spec:
140140
policies and version consistency in the cluster.
141141
For strict deterministic and repeatable deployments, you can add the digests
142142
to the image name, through the `<image>:<tag>@sha256:<digestValue>` format.
143+
144+
!!! Note "There's more"
145+
There are some examples cluster configurations bundled with the operator.
146+
Please refer to the ["Examples" section](samples.md).

‎docs/src/samples.md‎

Lines changed: 62 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,64 @@
1-
# Configuration Samples
2-
3-
In this section, you can find some examples of configuration files to set up your PostgreSQL `Cluster`.
4-
5-
* [`cluster-example.yaml`](samples/cluster-example.yaml):
6-
a basic example of `Cluster` that uses the default storage class. For demonstration and experimentation purposes
7-
on a personal Kubernetes cluster with Minikube or Kind as described in the ["Quickstart"](quickstart.md).
8-
* [`cluster-example-custom.yaml`](samples/cluster-example-custom.yaml):
9-
a basic example of `Cluster` that uses the default storage class and custom parameters for `postgresql.conf` and
10-
`pg_hba.conf` files
11-
* [`cluster-storage-class.yaml`](samples/cluster-storage-class.yaml):
12-
a basic example of `Cluster` that uses a specified storage class.
13-
* [`cluster-pvc-template.yaml`](samples/cluster-pvc-template.yaml):
14-
a basic example of `Cluster` that uses a persistent volume claim template.
15-
* [`cluster-example-full.yaml`](samples/cluster-example-full.yaml):
16-
an example of `Cluster` that sets most of the available options.
17-
* [`cluster-example-replica-streaming.yaml`](samples/cluster-example-replica-streaming.yaml):
18-
a replica cluster following `cluster-example`, usable in a different namespace.
19-
* [`cluster-example-replica-from-backup.yaml`](samples/cluster-example-replica-from-backup.yaml):
20-
a replica cluster following a cluster with backup configured. Usable in
21-
a different namespace.
1+
# Examples
2+
3+
In this section, you can find some examples of configuration files to set up
4+
your PostgreSQL Cluster.
5+
6+
!!! Important
7+
These are here for demonstration and experimentation
8+
purposes, and can be executed on a personal Kubernetes cluster with Minikube
9+
or Kind as described in the ["Quickstart"](quickstart.md).
10+
11+
Basic cluster
12+
: [`cluster-example.yaml`](samples/cluster-example.yaml)
13+
a basic example of a cluster.
14+
15+
Custom cluster
16+
: [`cluster-example-custom.yaml`](samples/cluster-example-custom.yaml)
17+
a basic cluster that uses the default storage class and custom parameters for
18+
the `postgresql.conf` and `pg_hba.conf` files.
19+
20+
Customized storage class
21+
: [`cluster-storage-class.yaml`](samples/cluster-storage-class.yaml):
22+
a basic cluster that uses a specified storage class of `standard`.
23+
24+
Customized storage class and backups
25+
: **Prerequisites**: bucket storage should be available. The sample config is for AWS,
26+
please change to suit your setup
27+
: [`cluster-storage-class-with-backup.yaml`](samples/cluster-storage-class-with-backup.yaml) a cluster
28+
with backups configured
29+
30+
Backup
31+
: **Prerequisites**: [`cluster-storage-class-with-backup.yaml`](samples/cluster-storage-class-with-backup.yaml)
32+
applied and Healthy
33+
: [`backup-example.yaml`](samples/backup-example.yaml):
34+
an example of a backup that runs against the previous sample
35+
36+
Cluster with PVC (Persistent Volume Claim) configured
37+
: [`cluster-pvc-template.yaml`](samples/cluster-pvc-template.yaml):
38+
a basic cluster that with an explicit persistent volume claim template.
39+
40+
Full example
41+
: [`cluster-example-full.yaml`](samples/cluster-example-full.yaml):
42+
a cluster that sets most of the available options.
43+
44+
Replica cluster via streaming
45+
: **Prerequisites**: [`cluster-example.yaml`](samples/cluster-example.yaml)
46+
applied and Healthy
47+
: [`cluster-example-replica-streaming.yaml`](samples/cluster-example-replica-streaming.yaml): a replica cluster following `cluster-example` with streaming replication.
48+
49+
Simple cluster with backup configured
50+
: **Prerequisites**: The configuration assumes `minio` is running and working.
51+
Please update `backup.barmanObjectStore` with your `minio` parameters or your cloud solution
52+
: [`cluster-example-with-backup.yaml`](samples/cluster-example-with-backup.yaml)
53+
a basic cluster with backups configured.
54+
55+
Replica cluster via backup
56+
: **Prerequisites**:
57+
[`cluster-storage-class-with-backup.yaml`](samples/cluster-storage-class-with-backup.yaml) applied and Healthy.
58+
And a backup
59+
[`cluster-example-trigger-backup.yaml`](samples/cluster-example-trigger-backup.yaml)
60+
applied and Completed.
61+
: [`cluster-example-replica-from-backup-simple.yaml`](samples/cluster-example-replica-from-backup-simple.yaml):
62+
a replica cluster following a cluster with backup configured.
2263

2364
For a list of available options, please refer to the ["API Reference" page](api_reference.md).

‎docs/src/samples/backup-example.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
apiVersion: postgresql.cnpg.io/v1
22
kind: Backup
33
metadata:
4-
name: backup-example
4+
name: pg-backup-example
55
spec:
66
cluster:
77
name: pg-backup

‎docs/src/samples/cluster-advanced-initdb.yaml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
apiVersion: postgresql.cnpg.io/v1
2+
kind: Cluster
3+
metadata:
4+
name: cluster-advanced-initdb
5+
spec:
6+
instances: 3
7+
8+
bootstrap:
9+
initdb:
10+
database: appdb
11+
owner: appuser
12+
postInitSQL:
13+
- create table numbers (i integer)
14+
- insert into numbers (select generate_series(1,10000))
15+
postInitTemplateSQL:
16+
- create extension intarray
17+
postInitApplicationSQL:
18+
- create table application_numbers (i integer)
19+
- insert into application_numbers (select generate_series(1,10000))
20+
dataChecksums: true
21+
encoding: 'UTF8'
22+
localeCollate: 'en_AU.UTF-8'
23+
localeCType: 'en_AU.UTF-8'
24+
storage:
25+
size: 1Gi

‎docs/src/samples/cluster-example-initdb.yaml‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,5 @@ spec:
1919
- insert into application_numbers (select generate_series(1,10000))
2020
dataChecksums: true
2121
encoding: 'UTF8'
22-
localeCollate: 'en_AU.UTF-8'
23-
localeCType: 'en_AU.UTF-8'
2422
storage:
2523
size: 1Gi

‎docs/src/samples/cluster-example-replica-from-backup-simple.yaml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
apiVersion: postgresql.cnpg.io/v1
2+
kind: Cluster
3+
metadata:
4+
name: cluster-example-replica-from-backup-simple
5+
spec:
6+
instances: 1
7+
8+
bootstrap:
9+
recovery:
10+
source: cluster-example-backup
11+
12+
replica:
13+
enabled: true
14+
source: cluster-example-backup
15+
16+
storage:
17+
size: 1Gi
18+
19+
externalClusters:
20+
- name: cluster-example-backup
21+
barmanObjectStore:
22+
destinationPath: s3://backups/
23+
endpointURL: http://minio:9000
24+
s3Credentials:
25+
accessKeyId:
26+
name: minio
27+
key: ACCESS_KEY_ID
28+
secretAccessKey:
29+
name: minio
30+
key: ACCESS_SECRET_KEY

‎docs/src/samples/cluster-example-trigger-backup.yaml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
apiVersion: postgresql.cnpg.io/v1
2+
kind: Backup
3+
metadata:
4+
name: cluster-example-trigger-backup
5+
spec:
6+
cluster:
7+
name: cluster-example-with-backup

‎docs/src/samples/cluster-example-with-backup.yaml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
apiVersion: postgresql.cnpg.io/v1
2+
kind: Cluster
3+
metadata:
4+
name: cluster-example-with-backup
5+
spec:
6+
instances: 3
7+
primaryUpdateStrategy: unsupervised
8+
9+
# Persistent storage configuration
10+
storage:
11+
storageClass: standard
12+
size: 1Gi
13+
14+
# Backup properties
15+
# This assumes a local minio setup
16+
backup:
17+
barmanObjectStore:
18+
destinationPath: s3://backups/
19+
endpointURL: http://minio:9000
20+
s3Credentials:
21+
accessKeyId:
22+
name: minio
23+
key: ACCESS_KEY_ID
24+
secretAccessKey:
25+
name: minio
26+
key: ACCESS_SECRET_KEY
27+
wal:
28+
compression: gzip

‎docs/src/samples/cluster-pvc-template.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ spec:
1414

1515
# Persistent storage configuration
1616
storage:
17+
size: 1Gi
1718
pvcTemplate:
1819
accessModes:
1920
- ReadWriteOnce

0 commit comments

Comments
 (0)