Skip to content
This repository was archived by the owner on May 30, 2025. It is now read-only.

Commit c243074

Browse files
FxKuFxKu
authored
Updated quickstart and link from README (zalando#527)
* updated quickstart and link from README * added/updated Helm chart description in other docs
1 parent 6778c3c commit c243074

File tree

4 files changed

+113
-97
lines changed

4 files changed

+113
-97
lines changed

‎README.md

Lines changed: 7 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,11 @@ manages PostgreSQL clusters on Kubernetes:
3232
4. The operator aims to be hands free and configuration happens only via manifests and its own config.
3333
This enables easy integration in automated deploy pipelines with no access to Kubernetes directly.
3434

35+
# Getting started
36+
37+
For a quick first impression follow the instructions of [this](docs/quickstart.md)
38+
tutorial.
39+
3540
# Google Summer of Code
3641

3742
The Postgres Operator made it to the [Google Summer of Code 2019](https://summerofcode.withgoogle.com/)! As a brand new mentoring organization, we are now looking for our first mentees. Check [our ideas](https://github.com/zalando/postgres-operator/blob/master/docs/gsoc-2019/ideas.md#google-summer-of-code-2019) and start discussion in [the issue tracker](https://github.com/zalando/postgres-operator/issues). And don't forget to spread a word about our GSoC participation to attract even more students.
@@ -48,7 +53,7 @@ The Postgres Operator made it to the [Google Summer of Code 2019](https://summer
4853

4954
The rest of this document is a tutorial to get you up and running locally with the operator on Minikube.
5055

51-
## Overview of involved entities
56+
## Overview of involved entities
5257

5358
Here is a diagram, that summarizes what would be created by the operator, when a
5459
new Postgres cluster CRD is submitted:
@@ -64,69 +69,9 @@ These two diagrams should help you to understand the basics of what kind of
6469
functionality the operator provides.
6570

6671
There is a browser-friendly version of this documentation at [postgres-operator.readthedocs.io](https://postgres-operator.readthedocs.io)
67-
72+
6873
## Community
6974

7075
There are two places to get in touch with the community:
7176
1. The [GitHub issue tracker](https://github.com/zalando/postgres-operator/issues)
7277
2. The #postgres-operator slack channel under [Postgres Slack](https://postgres-slack.herokuapp.com)
73-
74-
## Quickstart
75-
76-
Prerequisites:
77-
78-
* [minikube](https://github.com/kubernetes/minikube/releases)
79-
* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl-binary-via-curl)
80-
81-
Note that you can also use built-in Kubernetes support in the Docker Desktop
82-
for Mac to follow the steps of this tutorial. You would have to replace
83-
`minikube start` and `minikube delete` with your launch actionsfor the Docker
84-
built-in Kubernetes support.
85-
86-
### Local execution
87-
88-
```bash
89-
git clone https://github.com/zalando/postgres-operator.git
90-
cd postgres-operator
91-
92-
minikube start
93-
94-
# start the operator; may take a few seconds
95-
kubectl create -f manifests/configmap.yaml # configuration
96-
kubectl create -f manifests/operator-service-account-rbac.yaml # identity and permissions
97-
kubectl create -f manifests/postgres-operator.yaml # deployment
98-
99-
# create a Postgres cluster in a non-default namespace
100-
kubectl create namespace test
101-
kubectl config set-context minikube --namespace=test
102-
kubectl create -f manifests/minimal-postgres-manifest.yaml
103-
104-
# connect to the Postgres master via psql
105-
# operator creates the relevant k8s secret
106-
export HOST_PORT=$(minikube service --namespace test acid-minimal-cluster --url | sed 's,.*/,,')
107-
export PGHOST=$(echo $HOST_PORT | cut -d: -f 1)
108-
export PGPORT=$(echo $HOST_PORT | cut -d: -f 2)
109-
export PGPASSWORD=$(kubectl get secret postgres.acid-minimal-cluster.credentials -o 'jsonpath={.data.password}' | base64 -d)
110-
psql -U postgres
111-
112-
# tear down cleanly
113-
minikube delete
114-
```
115-
116-
We have automated starting the operator and submitting the `acid-minimal-cluster` for you:
117-
```bash
118-
cd postgres-operator
119-
./run_operator_locally.sh
120-
```
121-
122-
Note we provide the `/manifests` directory as an example only; you should consider adjusting the manifests to your particular setting.
123-
124-
## Running and testing the operator
125-
126-
The best way to test the operator is to run it locally in [minikube](https://kubernetes.io/docs/getting-started-guides/minikube/). See developer docs(`docs/developer.yaml`) for details.
127-
128-
### Configuration Options
129-
130-
The operator can be configured with the provided ConfigMap(`manifests/configmap.yaml`) or the operator's own CRD.
131-
132-

‎docs/administrator.md

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,17 @@ Next deploy the postgres-operator from the docker image Zalando is using:
2222

2323
If you prefer to build the image yourself follow up down below.
2424

25+
### - Helm chart
26+
27+
You can install postgres-operator also with a [Helm](https://helm.sh/) chart.
28+
This requires installing the Helm CLI first and then initializing it in the
29+
cluster.
30+
31+
```bash
32+
$ helm init
33+
$ helm install --name my-release ./charts/postgres-operator
34+
```
35+
2536
## Check if CustomResourceDefinition has been registered
2637

2738
```bash
@@ -312,7 +323,7 @@ generated from the current cluster manifest. There are two types of scans:
312323
* `sync scan`, running every `resync_period` seconds for every cluster
313324

314325
* `repair scan`, coming every `repair_period` only for those clusters that didn't
315-
report success as a result of the last operation applied to them.
326+
report success as a result of the last operation applied to them.
316327

317328
## Postgres roles supported by the operator
318329

@@ -329,8 +340,8 @@ Postgres database cluster:
329340

330341
## Understanding rolling update of Spilo pods
331342

332-
The operator logs reasons for a rolling update with the `info` level and
333-
a diff between the old and new StatefulSet specs with the `debug` level.
343+
The operator logs reasons for a rolling update with the `info` level and
344+
a diff between the old and new StatefulSet specs with the `debug` level.
334345
To read the latter log entry with the escaped characters rendered, view it
335346
in CLI with `echo -e`. Note that the resultant message will contain some
336347
noise because the `PodTemplate` used by the operator is yet to be updated

‎docs/developer.md

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -29,14 +29,6 @@ ConfigMap is used to store the configuration of the operator
2929

3030
## Deploying the operator
3131

32-
### - Helm chart
33-
34-
You can install postgres-operator with helm chart.
35-
36-
```bash
37-
$ helm install --name my-release ./charts/postgres-operator
38-
```
39-
4032
### - Kubernetes manifest
4133

4234
First you need to install the service account definition in your Minikube cluster.
@@ -53,6 +45,17 @@ Next deploy the postgres-operator from the docker image Zalando is using:
5345

5446
If you prefer to build the image yourself follow up down below.
5547

48+
### - Helm chart
49+
50+
You can install postgres-operator also with a [Helm](https://helm.sh/) chart.
51+
This requires installing the Helm CLI first and then initializing it in the
52+
cluster.
53+
54+
```bash
55+
$ helm init
56+
$ helm install --name my-release ./charts/postgres-operator
57+
```
58+
5659
## Check if CustomResourceDefinition has been registered
5760

5861
```bash

‎docs/quickstart.md

Lines changed: 81 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,73 +1,130 @@
11
## Prerequisites:
22

3-
In order to run the Postgres operator locally in minikube you need to install the following tools:
3+
In order to run the Postgres Operator locally in minikube you need to install
4+
the following tools:
45

56
* [minikube](https://github.com/kubernetes/minikube/releases)
67
* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl-binary-via-curl)
78

89
Note that you can also use built-in Kubernetes support in the Docker Desktop
910
for Mac to follow the steps of this tutorial. You would have to replace
10-
`minikube start` and `minikube delete` with your launch actionsfor the Docker
11+
`minikube start` and `minikube delete` with your launch actions for the Docker
1112
built-in Kubernetes support.
1213

13-
## Local execution
14+
Clone the repository and change to the directory. Then start minikube.
1415

1516
```bash
1617
git clone https://github.com/zalando/postgres-operator.git
1718
cd postgres-operator
1819

1920
minikube start
21+
```
2022

21-
# start the operator using one of helm chart or yaml manifests;
23+
## Manual deployment setup
2224

23-
# - install postgres-operator with helm chart.
24-
# 1) initialize helm
25-
helm init
26-
# 2) install postgres-operator chart
27-
helm install --name postgres-operator ./charts/postgres-operator
25+
The Postgres Operator can be installed simply by applying yaml manifests.
2826

29-
# - install postgres-operator with yaml manifests.
27+
```bash
3028
kubectl create -f manifests/configmap.yaml # configuration
3129
kubectl create -f manifests/operator-service-account-rbac.yaml # identity and permissions
3230
kubectl create -f manifests/postgres-operator.yaml # deployment
31+
```
3332

33+
## Helm chart
3434

35-
# starting the operator may take a few seconds
36-
# check if operator pod is running
35+
Another possibility is using a provided [Helm](https://helm.sh/) chart which
36+
saves you these steps. Therefore, you would need to install the helm CLI on your
37+
machine. After initializing helm (and its server component Tiller) in your local
38+
cluster you can install the operator chart.
3739

38-
# - if you've created the operator using helm chart
39-
kubectl get po -l app.kubernetes.io/name=postgres-operator
40+
```bash
41+
# 1) initialize helm
42+
helm init
43+
# 2) install postgres-operator chart
44+
helm install --name postgres-operator ./charts/postgres-operator
45+
```
46+
47+
## Create a Postgres cluster
4048

41-
# - if you've created the operator using yaml manifests
42-
kubectl get po -l name=postgres-operator
49+
Starting the operator may take a few seconds. Check if the operator pod is
50+
running before applying a Postgres cluster manifest.
51+
52+
```bash
53+
# if you've created the operator using yaml manifests
54+
kubectl get pod -l name=postgres-operator
4355

56+
# if you've created the operator using helm chart
57+
kubectl get pod -l app.kubernetes.io/name=postgres-operator
4458

4559
# create a Postgres cluster
4660
kubectl create -f manifests/minimal-postgres-manifest.yaml
61+
```
62+
63+
After the cluster manifest is submitted the operator will create Service and
64+
Endpoint resources and a StatefulSet which spins up new Pod(s) given the number
65+
of instances specified in the manifest. All resources are named like the
66+
cluster. The database pods can be identified by their number suffix, starting
67+
from `-0`. They run the [Spilo](https://github.com/zalando/spilo) container
68+
image by Zalando. As for the services and endpoints, there will be one for the
69+
master pod and another one for all the replicas (`-repl` suffix). Check if all
70+
components are coming up. Use the label `application=spilo` to filter and list
71+
the label `spilo-role` to see who is currently the master.
72+
73+
```bash
74+
# check the deployed cluster
75+
kubectl get postgresql
76+
77+
# check created database pods
78+
kubectl get pods -l application=spilo -L spilo-role
4779

48-
# connect to the Postgres master via psql
49-
# operator creates the relevant k8s secret
80+
# check created service resources
81+
kubectl get svc -l application=spilo -L spilo-role
82+
```
83+
84+
## Connect to the Postgres cluster via psql
85+
86+
You can retrieve the host and port of the Postgres master from minikube.
87+
Retrieve the password from the Kubernetes Secret that is created in your cluster.
88+
89+
```bash
5090
export HOST_PORT=$(minikube service acid-minimal-cluster --url | sed 's,.*/,,')
5191
export PGHOST=$(echo $HOST_PORT | cut -d: -f 1)
5292
export PGPORT=$(echo $HOST_PORT | cut -d: -f 2)
5393
export PGPASSWORD=$(kubectl get secret postgres.acid-minimal-cluster.credentials -o 'jsonpath={.data.password}' | base64 -d)
5494
psql -U postgres
95+
```
96+
97+
## Delete a Postgres cluster
98+
99+
To delete a Postgres cluster simply delete the postgresql custom resource.
100+
101+
```bash
102+
kubectl delete postgresql acid-minimal-cluster
55103

56104
# tear down cleanly
57105
minikube delete
58106
```
59107

60-
We have automated starting the operator and submitting the `acid-minimal-cluster` for you:
61-
```bash
62-
cd postgres-operator
63-
./run_operator_locally.sh
64-
```
65108

66109
## Running and testing the operator
67110

68111
The best way to test the operator is to run it in [minikube](https://kubernetes.io/docs/getting-started-guides/minikube/).
69112
Minikube is a tool to run Kubernetes cluster locally.
70113

114+
For convenience, we have automated starting the operator and submitting the
115+
`acid-minimal-cluster`. From inside the cloned repository execute the
116+
`run_operator_locally` shell script.
117+
118+
```bash
119+
./run_operator_locally.sh
120+
```
121+
122+
Note we provide the `/manifests` directory as an example only; you should
123+
consider adjusting the manifests to your particular setting.
124+
125+
71126
### Configuration Options
72127

73-
The operator can be configured with the provided ConfigMap (`manifests/configmap.yaml`).
128+
The operator can be configured with the provided ConfigMap
129+
(`manifests/configmap.yaml`) or the operator's own CRD. See
130+
[developer docs](developer.md) for details.

0 commit comments

Comments
 (0)