updated quickstart and link from README

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.
-
-

docs/quickstart.md

@@ -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.
+## 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
 kubectl create -f manifests/minimal-postgres-manifest.yaml
+```
 
-# connect to the Postgres master via psql
+After the cluster manifest is submitted a StatefulSet will be created which
-# operator creates the relevant k8s secret
+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.