Reorganize Readme (zalando#142)

removing parts of config.

* chaning secret name pattern to make things shorter.

* Move section on self building docker image.

* Fix typo.

* Bump image.

* bump version for pdb fix.

* Changes in regards to review.

* Fix xhyve driver link.

* Move to new api, remove service account, not needed for minikube.

* Changed minimal manifest and example to use right file.

* Added service account for operator again, it is needed in pods anyways later.

Author: Jan-M

Makefile

@@ -11,14 +11,13 @@ endif
 LOCAL_BUILD_FLAGS ?= $(BUILD_FLAGS)
 LDFLAGS ?= -X=main.version=$(VERSION)
 DOCKERFILE = docker/Dockerfile
-IMAGE ?= pierone.example.com/acid/$(BINARY)
+IMAGE ?= registry.opensource.zalan.do/acid/$(BINARY)
 TAG ?= $(VERSION)
 GITHEAD = $(shell git rev-parse --short HEAD)
 GITURL = $(shell git config --get remote.origin.url)
 GITSTATUS = $(shell git status --porcelain || echo "no changes")
 SOURCES = cmd/main.go
 VERSION ?= $(shell git describe --tags --always --dirty)
-IMAGE ?= pierone.example.com/acid/$(BINARY)
 DIRS := cmd pkg
 PKG := `go list ./... | grep -v /vendor/`
 

README.md

@@ -27,48 +27,7 @@ it manages and updates them with the new docker images; afterwards, all pods fro
 This project is currently in development. It is used internally by Zalando in order to run staging databases on Kubernetes.
 Please, report any issues discovered to https://github.com/zalando-incubator/postgres-operator/issues.
 
-## Setting up Go
-
-Postgres operator is written in Go. Use the [installation instructions](https://golang.org/doc/install#install) if you don't have Go on your system.
-You won't be able to compile the operator with Go older than 1.7. We recommend installing [the latest one](https://golang.org/dl/).
-
-Go projects expect their source code and all the dependencies to be located under the [GOPATH](https://github.com/golang/go/wiki/GOPATH).
-Normally, one would create a directory for the GOPATH (i.e. ~/go) and place the source code under the ~/go/src subdirectories.
-
-Given the schema above, the postgres operator source code located at `github.com/zalando-incubator/postgres-operator` should be put at
--`~/go/src/github.com/zalando-incubator/postgres-operator`.
-
-    $ export GOPATH=~/go
-    $ mkdir -p ${GOPATH}/src/github.com/zalando-incubator/
-    $ cd ${GOPATH}/src/github.com/zalando-incubator/ && git clone https://github.com/zalando-incubator/postgres-operator.git
-
-
-## Building the operator
-
-You need Glide to fetch all dependencies. Install it with:
-
-    $ make tools
-
-Next, install dependencies with glide by issuing:
-
-    $ make deps
-
-This would take a while to complete. You have to redo `make deps` every time you dependencies list changes, i.e. after adding a new library dependency.
-
-Build the operator docker image and pushing it to Pier One:
-
-    $ make docker push
-
-You may define the TAG variable to assign an explicit tag to your docker image and the IMAGE to set the image name.
-By default, the tag is computed with `git describe --tags --always --dirty` and the image is `pierone.stups.zalan.do/acid/postgres-operator`
-
-Building the operator binary (for testing the out-of-cluster option):
-
-    $ make
-
-The binary will be placed into the build directory.
-
-## Testing the operator
+## Running and testing the operator
 
 The best way to test the operator is to run it in minikube. Minikube is a tool to run Kubernetes cluster locally.
 
@@ -81,51 +40,31 @@ After the installation, issue the
 
     $ minikube start
 
-Note: if you are running on a Mac, make sure to use the [xhyve driver](https://github.com/kubernetes/minikube/blob/master/DRIVERS.md#xhyve-driver)
+Note: if you are running on a Mac, make sure to use the [xhyve driver](https://github.com/kubernetes/minikube/blob/master/docs/drivers.md#xhyve-driver)
 instead of the default docker-machine one for performance reasons.
 
 One you have it started successfully, use [the quickstart guide](https://github.com/kubernetes/minikube#quickstart) in order
 to test your that your setup is working.
 
 Note: if you use multiple kubernetes clusters, you can switch to minikube with `kubectl config use-context minikube`
 
-### Deploy etcd
-
-Etcd is required to deploy the operator.
-
-    $ kubectl --context minikube  create -f https://raw.githubusercontent.com/coreos/etcd/master/hack/kubernetes-deploy/etcd.yml
-
 ### Create ConfigMap
 
 ConfigMap is used to store configuration of the operator
 
     $ kubectl --context minikube  create -f manifests/configmap.yaml
 
-### Deploy fake Teams API
-
-Teams API is used as a source of human users.
-
-    $ kubectl --context minikube  create -f manifests/fake-teams-api.yaml
-
 ### Deploying the operator
 
-You need to install the service account definition in your minikube cluster. You can run without it, but then you
-have to change the service account references in the postgres-operator manifest as well.
+First you need to install the service account definition in your minikube cluster.
 
     $ kubectl --context minikube create -f manifests/serviceaccount.yaml
 
-The fastest way to run your docker image locally is to reuse the docker from minikube. That way, there is no need to
-pull docker images from pierone or push them, as the image is essentially there once you build it. The following steps
-will get you the docker image built and deployed.
+Next deploy the postgers-operator from the Docker image Zalando is using:
 
-    $ eval $(minikube docker-env)
-    $ export TAG=$(git describe --tags --always --dirty)
-    $ make docker
-    $ sed -e "s/\(image\:.*\:\).*$/\1$TAG/" manifests/postgres-operator.yaml|kubectl --context minikube create  -f -
+    $ kubectl --context minikube create -f manifests/postgres-operator.yaml
 
-The last line changes the docker image tag in the manifest to the one the operator image has been built with and removes
-the serviceAccountName definition, as the ServiceAccount is not defined in minikube (neither it should, as one has admin
-permissions there).
+If you perfer to build the image yourself follow up down below.
 
 ### Check if CustomResourceDefinition has been registered
 
@@ -137,33 +76,89 @@ permissions there).
 
 ### Create a new spilo cluster
 
-    $ kubectl --context minikube  create -f manifests/testpostgresql.yaml
+    $ kubectl --context minikube  create -f manifests/minimal-postgres-manifest.yaml
 
 ### Watch Pods being created
 
     $ kubectl --context minikube  get pods -w --show-labels
 
 ### Connect to PostgreSQL
 
-We can use the generated secret of the `postgres` robot user to connect to our `acid-testcluster` master running in Minikube:
+We can use the generated secret of the `postgres` robot user to connect to our `acid-test-cluster` master running in Minikube:
 
-    $ export HOST_PORT=$(minikube service acid-testcluster --url | sed 's,.*/,,')
+    $ export HOST_PORT=$(minikube service acid-test-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 --context minikube get secret postgres.acid-testcluster.credentials.postgresql.acid.zalan.do -o 'jsonpath={.data.password}' | base64 -d)
+    $ export PGPASSWORD=$(kubectl --context minikube get secret postgres.acid-test-cluster.credentials -o 'jsonpath={.data.password}' | base64 -d)
     $ psql -U postgres
 
+
+# Setup development environment
+
+The following steps guide you through the setup to work on the operator itself.
+
+## Setting up Go
+
+Postgres operator is written in Go. Use the [installation instructions](https://golang.org/doc/install#install) if you don't have Go on your system.
+You won't be able to compile the operator with Go older than 1.7. We recommend installing [the latest one](https://golang.org/dl/).
+
+Go projects expect their source code and all the dependencies to be located under the [GOPATH](https://github.com/golang/go/wiki/GOPATH).
+Normally, one would create a directory for the GOPATH (i.e. ~/go) and place the source code under the ~/go/src subdirectories.
+
+Given the schema above, the postgres operator source code located at `github.com/zalando-incubator/postgres-operator` should be put at
+-`~/go/src/github.com/zalando-incubator/postgres-operator`.
+
+    $ export GOPATH=~/go
+    $ mkdir -p ${GOPATH}/src/github.com/zalando-incubator/
+    $ cd ${GOPATH}/src/github.com/zalando-incubator/ && git clone https://github.com/zalando-incubator/postgres-operator.git
+
+
+## Building the operator
+
+You need Glide to fetch all dependencies. Install it with:
+
+    $ make tools
+
+Next, install dependencies with glide by issuing:
+
+    $ make deps
+
+This would take a while to complete. You have to redo `make deps` every time you dependencies list changes, i.e. after adding a new library dependency.
+
+Build the operator docker image and pushing it to Pier One:
+
+    $ make docker push
+
+You may define the TAG variable to assign an explicit tag to your docker image and the IMAGE to set the image name.
+By default, the tag is computed with `git describe --tags --always --dirty` and the image is `pierone.stups.zalan.do/acid/postgres-operator`
+
+Building the operator binary (for testing the out-of-cluster option):
+
+    $ make
+
+The binary will be placed into the build directory.
+
+### Deploying self build image
+
+The fastest way to run your docker image locally is to reuse the docker from minikube.
+The following steps will get you the docker image built and deployed.
+
+    $ eval $(minikube docker-env)
+    $ export TAG=$(git describe --tags --always --dirty)
+    $ make docker
+    $ sed -e "s/\(image\:.*\:\).*$/\1$TAG/" manifests/postgres-operator.yaml|kubectl --context minikube create  -f -
+
 ### Debugging the operator itself
 
 There is a web interface in the operator to observe its internal state. The operator listens on port 8080. It is possible to expose it to the localhost:8080 by doing:
 
     $ kubectl --context minikube port-forward $(kubectl --context minikube get pod -l name=postgres-operator -o jsonpath={.items..metadata.name}) 8080:8080
-    
+
 The inner 'query' gets the name of the postgres operator pod, and the outer enables port forwarding. Afterwards, you can access the operator API with:
 
     $ curl http://127.0.0.1:8080/$endpoint| jq .
 
-The available endpoints are listed below. Note that the worker ID is an integer from 0 up to 'workers' - 1 (value configured in the operator configuration and defaults to 4) 
+The available endpoints are listed below. Note that the worker ID is an integer from 0 up to 'workers' - 1 (value configured in the operator configuration and defaults to 4)
 
 * /workers/all/queue - state of the workers queue (cluster events to process)
 * /workers/$id/queue - state of the queue for the worker $id
@@ -181,5 +176,3 @@ The operator also supports pprof endpoints listed at the [pprof package](https:/
 * /debug/pprof/profile
 * /debug/pprof/symbol
 * /debug/pprof/trace
-
-

manifests/testpostgresql.yaml renamed to manifests/complete-postgres-manifest.yaml

@@ -2,7 +2,7 @@ apiVersion: "acid.zalan.do/v1"
 kind: postgresql
 
 metadata:
-  name: acid-testcluster17
+  name: acid-test-cluster
 spec:
   teamId: "ACID"
   volume:
@@ -18,7 +18,7 @@ spec:
     foo: zalando
 #Expert section
   postgresql:
-    version: "9.6"
+    version: "10"
     parameters:
       shared_buffers: "32MB"
       max_connections: "10"

manifests/configmap.yaml

@@ -11,8 +11,8 @@ data:
   debug_logging: "true"
   dns_name_format: '{cluster}.{team}.staging.{hostedzone}'
   docker_image: registry.opensource.zalan.do/acid/demospilo-10:1.3-p3
+  secret_name_template: '{username}.{cluster}.credentials'
   etcd_host: ""
-  secret_name_template: '{username}.{cluster}.credentials.{tprkind}.{tprgroup}'
   infrastructure_roles_secret_name: postgresql-infrastructure-roles
   oauth_token_secret_name: postgresql-operator
   pam_configuration: |

manifests/minimal-postgres-manifest.yaml

@@ -0,0 +1,23 @@
+apiVersion: "acid.zalan.do/v1"
+kind: postgresql
+metadata:
+  name: acid-minimal-cluster
+spec:
+  teamId: "ACID"
+  volume:
+    size: 1Gi
+  numberOfInstances: 2
+  users:
+    # database owner
+    zalando:
+    - superuser
+    - createdb
+
+    # role for application foo
+    foo_user:
+  
+  #databases: name->owner
+  databases:
+    foo: zalando
+  postgresql:
+    version: "10"

manifests/postgres-operator.yaml

@@ -1,4 +1,4 @@
-apiVersion: extensions/v1beta1
+apiVersion: apps/v1beta1
 kind: Deployment
 metadata:
   name: postgres-operator
@@ -12,7 +12,7 @@ spec:
       serviceAccountName: operator
       containers:
       - name: postgres-operator
-        image: pierone.stups.zalan.do/acid/postgres-operator:workerassgn
+        image: registry.opensource.zalan.do/acid/postgres-operator:c17aabb
         imagePullPolicy: IfNotPresent
         env:
         - name: WATCH_NAMESPACE

manifests/serviceaccount.yaml

@@ -2,5 +2,3 @@ apiVersion: v1
 kind: ServiceAccount
 metadata:
   name: operator
-imagePullSecrets:
-- name: pierone.example.com