Updated quickstart and link from README (#527)

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

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.md)
+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/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 
+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. 
+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.
+## 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 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 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.