Updated quickstart and link from README (#527)

* updated quickstart and link from README
* added/updated Helm chart description in other docs

docs/administrator.md

@@ -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.
 
+### - 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
 
 ```bash
@@ -312,7 +323,7 @@ generated from the current cluster manifest. There are two types of scans:
 * `sync scan`, running every `resync_period` seconds for every cluster
 
 * `repair scan`, coming every `repair_period` only for those clusters that didn't
-report success as a result of the last operation applied to them. 
+report success as a result of the last operation applied to them.
 
 ## Postgres roles supported by the operator
 
@@ -329,8 +340,8 @@ Postgres database cluster:
 
 ## Understanding rolling update of Spilo pods
 
-The operator logs reasons for a rolling update with the `info` level and 
-a diff between the old and new StatefulSet specs with the `debug` level. 
+The operator logs reasons for a rolling update with the `info` level and
+a diff between the old and new StatefulSet specs with the `debug` level.
 To read the latter log entry with the escaped characters rendered, view it
 in CLI with `echo -e`. Note that the resultant message will contain some
 noise because the `PodTemplate` used by the operator is yet to be updated

docs/developer.md

@@ -29,14 +29,6 @@ ConfigMap is used to store the configuration of 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
 
 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.
 
+### - 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
 
 ```bash

docs/quickstart.md

@@ -1,73 +1,130 @@
 ## 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 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 the operator will create Service and
+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 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.md) for details.