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

Updated quickstart and link from README (#527) 

* updated quickstart and link from README
* added/updated Helm chart description in other docs
This commit is contained in:
Felix Kunde 2019-04-01 15:39:18 +02:00 committed by GitHub
parent 6778c3c03c
commit c243074083
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 114 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
README.md
View File

@ -32,6 +32,11 @@ manages PostgreSQL clusters on Kubernetes:
4. The operator aims to be hands free and configuration happens only via manifests and its own config. 4. The operator aims to be hands free and configuration happens only via manifests and its own config.
This enables easy integration in automated deploy pipelines with no access to Kubernetes directly. This enables easy integration in automated deploy pipelines with no access to Kubernetes directly.
# Getting started
For a quick first impression follow the instructions of [this](docs/quickstart.md)
tutorial.
# Google Summer of Code # Google Summer of Code
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. 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.
@ -70,63 +75,3 @@ There is a browser-friendly version of this documentation at [postgres-operator.
There are two places to get in touch with the community: There are two places to get in touch with the community:
1. The [GitHub issue tracker](https://github.com/zalando/postgres-operator/issues) 1. The [GitHub issue tracker](https://github.com/zalando/postgres-operator/issues)
2. The #postgres-operator slack channel under [Postgres Slack](https://postgres-slack.herokuapp.com) 2. The #postgres-operator slack channel under [Postgres Slack](https://postgres-slack.herokuapp.com)
## Quickstart
Prerequisites:
* [minikube](https://github.com/kubernetes/minikube/releases)
* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl-binary-via-curl)
Note that you can also use built-in Kubernetes support in the Docker Desktop
for Mac to follow the steps of this tutorial. You would have to replace
`minikube start` and `minikube delete` with your launch actionsfor the Docker
built-in Kubernetes support.
### Local execution
```bash
git clone https://github.com/zalando/postgres-operator.git
cd postgres-operator
minikube start
# start the operator; may take a few seconds
kubectl create -f manifests/configmap.yaml # configuration
kubectl create -f manifests/operator-service-account-rbac.yaml # identity and permissions
kubectl create -f manifests/postgres-operator.yaml # deployment
# create a Postgres cluster in a non-default namespace
kubectl create namespace test
kubectl config set-context minikube --namespace=test
kubectl create -f manifests/minimal-postgres-manifest.yaml
# connect to the Postgres master via psql
# operator creates the relevant k8s secret
export HOST_PORT=$(minikube service --namespace test acid-minimal-cluster --url | sed 's,.*/,,')
export PGHOST=$(echo $HOST_PORT | cut -d: -f 1)
export PGPORT=$(echo $HOST_PORT | cut -d: -f 2)
export PGPASSWORD=$(kubectl get secret postgres.acid-minimal-cluster.credentials -o 'jsonpath={.data.password}' | base64 -d)
psql -U postgres
# tear down cleanly
minikube delete
```
We have automated starting the operator and submitting the `acid-minimal-cluster` for you:
```bash
cd postgres-operator
./run_operator_locally.sh
```
Note we provide the `/manifests` directory as an example only; you should consider adjusting the manifests to your particular setting.
## Running and testing the operator
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.
### Configuration Options
The operator can be configured with the provided ConfigMap(`manifests/configmap.yaml`) or the operator's own CRD.

11
docs/administrator.md
View File

@ -22,6 +22,17 @@ Next deploy the postgres-operator from the docker image Zalando is using:
If you prefer to build the image yourself follow up down below. If you prefer to build the image yourself follow up down below.
### - Helm chart
You can install postgres-operator also with a [Helm](https://helm.sh/) chart.
This requires installing the Helm CLI first and then initializing it in the
cluster.
```bash
$ helm init
$ helm install --name my-release ./charts/postgres-operator
```
## Check if CustomResourceDefinition has been registered ## Check if CustomResourceDefinition has been registered
```bash ```bash

19
docs/developer.md
View File

@ -29,14 +29,6 @@ ConfigMap is used to store the configuration of the operator
## Deploying the operator ## Deploying the operator
### - Helm chart
You can install postgres-operator with helm chart.
```bash
$ helm install --name my-release ./charts/postgres-operator
```
### - Kubernetes manifest ### - Kubernetes manifest
First you need to install the service account definition in your Minikube cluster. 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:
If you prefer to build the image yourself follow up down below. If you prefer to build the image yourself follow up down below.
### - Helm chart
You can install postgres-operator also with a [Helm](https://helm.sh/) chart.
This requires installing the Helm CLI first and then initializing it in the
cluster.
```bash
$ helm init
$ helm install --name my-release ./charts/postgres-operator
```
## Check if CustomResourceDefinition has been registered ## Check if CustomResourceDefinition has been registered
```bash ```bash

105
docs/quickstart.md
View File

@ -1,6 +1,7 @@
## Prerequisites: ## Prerequisites:
In order to run the Postgres operator locally in minikube you need to install the following tools: In order to run the Postgres Operator locally in minikube you need to install
the following tools:
* [minikube](https://github.com/kubernetes/minikube/releases) * [minikube](https://github.com/kubernetes/minikube/releases)
* [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl-binary-via-curl) * [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl-binary-via-curl)
@ -10,64 +11,120 @@ for Mac to follow the steps of this tutorial. You would have to replace
`minikube start` and `minikube delete` with your launch actions for the Docker `minikube start` and `minikube delete` with your launch actions for the Docker
built-in Kubernetes support. built-in Kubernetes support.
## Local execution Clone the repository and change to the directory. Then start minikube.
```bash ```bash
git clone https://github.com/zalando/postgres-operator.git git clone https://github.com/zalando/postgres-operator.git
cd postgres-operator cd postgres-operator
minikube start minikube start
```
# start the operator using one of helm chart or yaml manifests; ## Manual deployment setup
# - install postgres-operator with helm chart. The Postgres Operator can be installed simply by applying yaml manifests.
```bash
kubectl create -f manifests/configmap.yaml # configuration
kubectl create -f manifests/operator-service-account-rbac.yaml # identity and permissions
kubectl create -f manifests/postgres-operator.yaml # deployment
```
## Helm chart
Another possibility is using a provided [Helm](https://helm.sh/) chart which
saves you these steps. Therefore, you would need to install the helm CLI on your
machine. After initializing helm (and its server component Tiller) in your local
cluster you can install the operator chart.
```bash
# 1) initialize helm # 1) initialize helm
helm init helm init
# 2) install postgres-operator chart # 2) install postgres-operator chart
helm install --name postgres-operator ./charts/postgres-operator helm install --name postgres-operator ./charts/postgres-operator
```
# - install postgres-operator with yaml manifests. ## Create a Postgres cluster
kubectl create -f manifests/configmap.yaml # configuration
kubectl create -f manifests/operator-service-account-rbac.yaml # identity and permissions
kubectl create -f manifests/postgres-operator.yaml # deployment
Starting the operator may take a few seconds. Check if the operator pod is
running before applying a Postgres cluster manifest.
# starting the operator may take a few seconds ```bash
# check if operator pod is running # if you've created the operator using yaml manifests
kubectl get pod -l name=postgres-operator
# - if you've created the operator using helm chart
kubectl get po -l app.kubernetes.io/name=postgres-operator
# - if you've created the operator using yaml manifests
kubectl get po -l name=postgres-operator
# if you've created the operator using helm chart
kubectl get pod -l app.kubernetes.io/name=postgres-operator
# create a Postgres cluster # create a Postgres cluster
kubectl create -f manifests/minimal-postgres-manifest.yaml kubectl create -f manifests/minimal-postgres-manifest.yaml
```
# connect to the Postgres master via psql After the cluster manifest is submitted the operator will create Service and
# operator creates the relevant k8s secret Endpoint resources and a StatefulSet which spins up new Pod(s) given the number
of instances specified in the manifest. All resources are named like the
cluster. The database pods can be identified by their number suffix, starting
from `-0`. They run the [Spilo](https://github.com/zalando/spilo) container
image by Zalando. As for the services and endpoints, there will be one for the
master pod and another one for all the replicas (`-repl` suffix). Check if all
components are coming up. Use the label `application=spilo` to filter and list
the label `spilo-role` to see who is currently the master.
```bash
# check the deployed cluster
kubectl get postgresql
# check created database pods
kubectl get pods -l application=spilo -L spilo-role
# check created service resources
kubectl get svc -l application=spilo -L spilo-role
```
## Connect to the Postgres cluster via psql
You can retrieve the host and port of the Postgres master from minikube.
Retrieve the password from the Kubernetes Secret that is created in your cluster.
```bash
export HOST_PORT=$(minikube service acid-minimal-cluster --url | sed 's,.*/,,') export HOST_PORT=$(minikube service acid-minimal-cluster --url | sed 's,.*/,,')
export PGHOST=$(echo $HOST_PORT | cut -d: -f 1) export PGHOST=$(echo $HOST_PORT | cut -d: -f 1)
export PGPORT=$(echo $HOST_PORT | cut -d: -f 2) export PGPORT=$(echo $HOST_PORT | cut -d: -f 2)
export PGPASSWORD=$(kubectl get secret postgres.acid-minimal-cluster.credentials -o 'jsonpath={.data.password}' | base64 -d) export PGPASSWORD=$(kubectl get secret postgres.acid-minimal-cluster.credentials -o 'jsonpath={.data.password}' | base64 -d)
psql -U postgres psql -U postgres
```
## Delete a Postgres cluster
To delete a Postgres cluster simply delete the postgresql custom resource.
```bash
kubectl delete postgresql acid-minimal-cluster
# tear down cleanly # tear down cleanly
minikube delete minikube delete
``` ```
We have automated starting the operator and submitting the `acid-minimal-cluster` for you:
```bash
cd postgres-operator
./run_operator_locally.sh
```
## Running and testing the operator ## Running and testing the operator
The best way to test the operator is to run it in [minikube](https://kubernetes.io/docs/getting-started-guides/minikube/). The best way to test the operator is to run it in [minikube](https://kubernetes.io/docs/getting-started-guides/minikube/).
Minikube is a tool to run Kubernetes cluster locally. Minikube is a tool to run Kubernetes cluster locally.
For convenience, we have automated starting the operator and submitting the
`acid-minimal-cluster`. From inside the cloned repository execute the
`run_operator_locally` shell script.
```bash
./run_operator_locally.sh
```
Note we provide the `/manifests` directory as an example only; you should
consider adjusting the manifests to your particular setting.
### Configuration Options ### Configuration Options
The operator can be configured with the provided ConfigMap (`manifests/configmap.yaml`). The operator can be configured with the provided ConfigMap
(`manifests/configmap.yaml`) or the operator's own CRD. See
[developer docs](developer.md) for details.