updated quickstart and link from README
This commit is contained in:
Felix Kunde
parent
6778c3c03c
commit
0ac4afee03
69
README.md
69
README.md
|
|
@ -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.
|
||||
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)
|
||||
tutorial.
|
||||
|
||||
# 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.
|
||||
|
|
@ -48,7 +53,7 @@ The Postgres Operator made it to the [Google Summer of Code 2019](https://summer
|
|||
|
||||
The rest of this document is a tutorial to get you up and running locally with the operator on Minikube.
|
||||
|
||||
## Overview of involved entities
|
||||
## Overview of involved entities
|
||||
|
||||
Here is a diagram, that summarizes what would be created by the operator, when a
|
||||
new Postgres cluster CRD is submitted:
|
||||
|
|
@ -64,69 +69,9 @@ These two diagrams should help you to understand the basics of what kind of
|
|||
functionality the operator provides.
|
||||
|
||||
There is a browser-friendly version of this documentation at [postgres-operator.readthedocs.io](https://postgres-operator.readthedocs.io)
|
||||
|
||||
|
||||
## Community
|
||||
|
||||
There are two places to get in touch with the community:
|
||||
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)
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,73 +1,129 @@
|
|||
## 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)
|
||||
* [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
|
||||
`minikube start` and `minikube delete` with your launch actions for the Docker
|
||||
built-in Kubernetes support.
|
||||
|
||||
## Local execution
|
||||
Clone the the repository and change to the directory. Then start minikube.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zalando/postgres-operator.git
|
||||
cd postgres-operator
|
||||
|
||||
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
|
||||
helm init
|
||||
# 2) install postgres-operator chart
|
||||
helm install --name postgres-operator ./charts/postgres-operator
|
||||
```
|
||||
|
||||
# - install postgres-operator with yaml manifests.
|
||||
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
|
||||
|
||||
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
|
||||
# check if operator pod is running
|
||||
|
||||
# - 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
|
||||
```bash
|
||||
# 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 pod -l app.kubernetes.io/name=postgres-operator
|
||||
|
||||
# create a Postgres cluster
|
||||
kubectl create -f manifests/minimal-postgres-manifest.yaml
|
||||
```
|
||||
|
||||
# connect to the Postgres master via psql
|
||||
# operator creates the relevant k8s secret
|
||||
After the cluster manifest is submitted a StatefulSet will be created which
|
||||
rolls out the database instances (Pods and Services). They 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 service resources, 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 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
|
||||
```
|
||||
|
||||
## 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
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
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.yaml) for details.
|
||||
|
|
|
|||
Loading…
Reference in New Issue