From a98a7c95c2f069b0643311616fede0a56e60b2f3 Mon Sep 17 00:00:00 2001 From: Jan Mussler Date: Tue, 24 Oct 2017 20:42:22 +0200 Subject: [PATCH] Reorganize Readme (#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. --- Makefile | 3 +- README.md | 143 +++++++++--------- ...l.yaml => complete-postgres-manifest.yaml} | 4 +- manifests/configmap.yaml | 2 +- manifests/minimal-postgres-manifest.yaml | 23 +++ manifests/postgres-operator.yaml | 4 +- manifests/serviceaccount.yaml | 2 - 7 files changed, 97 insertions(+), 84 deletions(-) rename manifests/{testpostgresql.yaml => complete-postgres-manifest.yaml} (95%) create mode 100644 manifests/minimal-postgres-manifest.yaml diff --git a/Makefile b/Makefile index a03d3c2eb..4032c7dfe 100644 --- a/Makefile +++ b/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/` diff --git a/README.md b/README.md index a62ec84dd..59fc51f16 100644 --- a/README.md +++ b/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,7 +40,7 @@ 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 @@ -89,43 +48,23 @@ 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,7 +76,7 @@ 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 @@ -145,25 +84,81 @@ permissions there). ### 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 - - diff --git a/manifests/testpostgresql.yaml b/manifests/complete-postgres-manifest.yaml similarity index 95% rename from manifests/testpostgresql.yaml rename to manifests/complete-postgres-manifest.yaml index d3adb5e30..494cb8cc0 100644 --- a/manifests/testpostgresql.yaml +++ b/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" diff --git a/manifests/configmap.yaml b/manifests/configmap.yaml index d4f845e09..e265c1907 100644 --- a/manifests/configmap.yaml +++ b/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: | diff --git a/manifests/minimal-postgres-manifest.yaml b/manifests/minimal-postgres-manifest.yaml new file mode 100644 index 000000000..c8f486201 --- /dev/null +++ b/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" diff --git a/manifests/postgres-operator.yaml b/manifests/postgres-operator.yaml index 54ee3480e..b71f19f19 100644 --- a/manifests/postgres-operator.yaml +++ b/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 diff --git a/manifests/serviceaccount.yaml b/manifests/serviceaccount.yaml index f98a17b74..5b9d50558 100644 --- a/manifests/serviceaccount.yaml +++ b/manifests/serviceaccount.yaml @@ -2,5 +2,3 @@ apiVersion: v1 kind: ServiceAccount metadata: name: operator -imagePullSecrets: -- name: pierone.example.com