From 9575c9d35e09aef56f79e79a6f21b3df126becd4 Mon Sep 17 00:00:00 2001 From: Sergey Dudoladov Date: Tue, 15 May 2018 17:39:47 +0200 Subject: [PATCH 01/11] Create Quickstart section for the docs --- README.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/README.md b/README.md index 88100e9bc..c4b270d77 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,36 @@ Update example: After changing the Docker image inside the operator's configurat it manages and updates them with the new Docker image; afterwards, all pods from each StatefulSet are killed one by one and the replacements are spawned automatically by each StatefulSet with the new Docker image. This is called the Rolling update. + +## Quickstart + +Prerequisites: [minikube](https://github.com/kubernetes/minikube/releases) and [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl-binary-via-native-package-management) + +### Local execution + +```bash +git clone https://github.com/zalando-incubator/postgres-operator.git +cd postgres-operator + +minikube start +kubectl config set-context minikube + +kubectl create -f manifests/configmap.yaml # operator config +kubectl create -f manifests/serviceaccount.yaml # operator pod identity +kubectl create -f manifests/postgres-operator.yaml # start the operator + +# startup may last a few seconds + +kubectl create -f manifests/minimal-postgres-manifest.yaml # submit a PG cluster +minikube delete # tear down cleanly +``` + +We have automated these steps for you: +```bash +cd postgres-operator +./run_operator_locally.sh +``` + ## Scope The scope of the postgres operator is on provisioning, modifying configuration and cleaning up Postgres clusters that use Patroni, basically to make it easy and convenient to run Patroni based clusters on Kubernetes. From ca8542185a618a62917edfa6cac175335aef7be6 Mon Sep 17 00:00:00 2001 From: Sergey Dudoladov Date: Wed, 16 May 2018 11:01:16 +0200 Subject: [PATCH 02/11] Add RBAC to Quickstart guide --- README.md | 16 +++++++++------- manifests/postgres-operator.yaml | 2 +- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index c4b270d77..0f328a6da 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ and the replacements are spawned automatically by each StatefulSet with the new ## Quickstart -Prerequisites: [minikube](https://github.com/kubernetes/minikube/releases) and [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl-binary-via-native-package-management) +Prerequisites: [minikube](https://github.com/kubernetes/minikube/releases) and [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl-binary-via-curl) ### Local execution @@ -38,16 +38,13 @@ git clone https://github.com/zalando-incubator/postgres-operator.git cd postgres-operator minikube start -kubectl config set-context minikube kubectl create -f manifests/configmap.yaml # operator config -kubectl create -f manifests/serviceaccount.yaml # operator pod identity -kubectl create -f manifests/postgres-operator.yaml # start the operator - -# startup may last a few seconds +kubectl create -f manifests/operator-rbac.yaml # operator pod identity +kubectl create -f manifests/postgres-operator.yaml # create postgres-operator deployment +# operator startup may last a few seconds kubectl create -f manifests/minimal-postgres-manifest.yaml # submit a PG cluster -minikube delete # tear down cleanly ``` We have automated these steps for you: @@ -56,6 +53,11 @@ cd postgres-operator ./run_operator_locally.sh ``` +Tear down cleanly: +```bash +minikube delete +``` + ## Scope The scope of the postgres operator is on provisioning, modifying configuration and cleaning up Postgres clusters that use Patroni, basically to make it easy and convenient to run Patroni based clusters on Kubernetes. diff --git a/manifests/postgres-operator.yaml b/manifests/postgres-operator.yaml index a7a8dde49..54e65210f 100644 --- a/manifests/postgres-operator.yaml +++ b/manifests/postgres-operator.yaml @@ -9,7 +9,7 @@ spec: labels: name: postgres-operator spec: - serviceAccountName: operator + serviceAccountName: zalando-postgres-operator containers: - name: postgres-operator image: registry.opensource.zalan.do/acid/postgres-operator:4c8dfd7 From a9265155307a67c68aefdcb238d86f19b5485598 Mon Sep 17 00:00:00 2001 From: Sergey Dudoladov Date: Wed, 16 May 2018 15:28:45 +0200 Subject: [PATCH 03/11] Employ RBAC when run on minikube --- README.md | 10 +++++----- manifests/operator-rbac.yaml | 7 +++++++ manifests/serviceaccount.yaml | 4 ---- run_operator_locally.sh | 2 +- 4 files changed, 13 insertions(+), 10 deletions(-) delete mode 100644 manifests/serviceaccount.yaml diff --git a/README.md b/README.md index 0f328a6da..10bd8a513 100644 --- a/README.md +++ b/README.md @@ -47,17 +47,17 @@ kubectl create -f manifests/postgres-operator.yaml # create postgres-operator d kubectl create -f manifests/minimal-postgres-manifest.yaml # submit a PG cluster ``` +Tear down cleanly: +```bash +minikube delete +``` + We have automated these steps for you: ```bash cd postgres-operator ./run_operator_locally.sh ``` -Tear down cleanly: -```bash -minikube delete -``` - ## Scope The scope of the postgres operator is on provisioning, modifying configuration and cleaning up Postgres clusters that use Patroni, basically to make it easy and convenient to run Patroni based clusters on Kubernetes. diff --git a/manifests/operator-rbac.yaml b/manifests/operator-rbac.yaml index f659da615..e20a2ecd4 100644 --- a/manifests/operator-rbac.yaml +++ b/manifests/operator-rbac.yaml @@ -112,6 +112,13 @@ rules: - create - delete - get +- apiGroups: + - "" + resources: + - serviceaccounts + verbs: + - get + - create --- apiVersion: rbac.authorization.k8s.io/v1 diff --git a/manifests/serviceaccount.yaml b/manifests/serviceaccount.yaml deleted file mode 100644 index 5b9d50558..000000000 --- a/manifests/serviceaccount.yaml +++ /dev/null @@ -1,4 +0,0 @@ -apiVersion: v1 -kind: ServiceAccount -metadata: - name: operator diff --git a/run_operator_locally.sh b/run_operator_locally.sh index 6c5f15a9f..4fcbe46e2 100755 --- a/run_operator_locally.sh +++ b/run_operator_locally.sh @@ -134,7 +134,7 @@ function start_operator(){ # the order of resource initialization is significant local file - for file in "configmap.yaml" "serviceaccount.yaml" + for file in "configmap.yaml" "operator-rbac.yaml" do retry "kubectl create -f manifests/\"$file\"" "attempt to create $file resource" done From b067ec788a68094e4dd8c5800165853f72068a5a Mon Sep 17 00:00:00 2001 From: Sergey Dudoladov Date: Wed, 16 May 2018 16:01:16 +0200 Subject: [PATCH 04/11] Minor edits --- README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 10bd8a513..0dc2d2126 100644 --- a/README.md +++ b/README.md @@ -39,12 +39,13 @@ cd postgres-operator minikube start +# start the operator; may take a few seconds kubectl create -f manifests/configmap.yaml # operator config -kubectl create -f manifests/operator-rbac.yaml # operator pod identity -kubectl create -f manifests/postgres-operator.yaml # create postgres-operator deployment -# operator startup may last a few seconds +kubectl create -f manifests/operator-rbac.yaml # operator identity and persmissions +kubectl create -f manifests/postgres-operator.yaml # operator deployment -kubectl create -f manifests/minimal-postgres-manifest.yaml # submit a PG cluster +# submit a Postgres cluster +kubectl create -f manifests/minimal-postgres-manifest.yaml ``` Tear down cleanly: From 631748cd59f128fdeebcd582882d47deabb41dda Mon Sep 17 00:00:00 2001 From: Sergey Dudoladov Date: Wed, 16 May 2018 16:10:49 +0200 Subject: [PATCH 05/11] Simplify layout --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index 0dc2d2126..a811d485c 100644 --- a/README.md +++ b/README.md @@ -46,10 +46,8 @@ kubectl create -f manifests/postgres-operator.yaml # operator deployment # submit a Postgres cluster kubectl create -f manifests/minimal-postgres-manifest.yaml -``` -Tear down cleanly: -```bash +# tear down cleanly minikube delete ``` From bfc1950df86fd0bfcb0007ab4f6e958fd4032e4e Mon Sep 17 00:00:00 2001 From: Sergey Dudoladov Date: Wed, 16 May 2018 17:25:03 +0200 Subject: [PATCH 06/11] Shorten the introduction --- README.md | 23 ++++++----------------- 1 file changed, 6 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index a811d485c..fc32ebc00 100644 --- a/README.md +++ b/README.md @@ -4,27 +4,15 @@ [![Coverage Status](https://coveralls.io/repos/github/zalando-incubator/postgres-operator/badge.svg)](https://coveralls.io/github/zalando-incubator/postgres-operator) [![Go Report Card](https://goreportcard.com/badge/github.com/zalando-incubator/postgres-operator)](https://goreportcard.com/report/github.com/zalando-incubator/postgres-operator) -The Postgres operator manages PostgreSQL clusters on Kubernetes using the [operator pattern](https://coreos.com/blog/introducing-operators.html). -During the initial run it registers the [Custom Resource Definition (CRD)](https://kubernetes.io/docs/concepts/api-extension/custom-resources/#customresourcedefinitions) for Postgres. -The `postgresql` CRD is essentially the schema that describes the contents of the manifests for deploying individual -Postgres clusters using StatefulSets and [Patroni](https://github.com/zalando/patroni). +## Introduction -Once the operator is running, it performs the following actions: +The Postgres [operator](https://coreos.com/blog/introducing-operators.html) manages PostgreSQL clusters on Kubernetes: -* watches for new `postgresql` manifests and deploys new clusters -* watches for updates to existing manifests and changes corresponding properties of the running clusters -* watches for deletes of the existing manifests and deletes corresponding clusters -* acts on an update to the operator configuration itself and changes the running clusters when necessary - (i.e. the Docker image changes for a minor release update) -* periodically checks running clusters against the manifests and syncs changes +1. The operator watches additions, updates and deletions of Postgresql manifests (cluster descriptions) and changes the running clusters accordingly. For example, when a user submits a new manifest, the operator fetches that object and spawns a new Postgres cluster, including all necessary entities such as Kubernetes StatefulSets and Postgres roles. The [`postgresql` Custom Resource Definition](https://kubernetes.io/docs/concepts/api-extension/custom-resources/#customresourcedefinitions) defines settings that a cluster manifest may contain (see example). -Example: When a user creates a new custom object of type ``postgresql`` by submitting a new manifest with -``kubectl``, the operator fetches that object and creates the required Kubernetes entities to spawn a new Postgres cluster -(StatefulSets, Services, Secrets). +2. The operator also watches updates to its own configuration and alters running Postgres clusters if necessary. For instance, if a pods' Docker image is changed, the operator carries out the rolling update. That is, it re-spawns one-by-one pods from each StatefulSet it manages with the new Docker image. -Update example: After changing the Docker image inside the operator's configuration, the operator first goes to all StatefulSets -it manages and updates them with the new Docker image; afterwards, all pods from each StatefulSet are killed one by one -and the replacements are spawned automatically by each StatefulSet with the new Docker image. This is called the Rolling update. +3. Finally, the operator periodically synchronizes the actual state of each Postgres cluster with the desired state defined in the cluster's manifest. ## Quickstart @@ -55,6 +43,7 @@ We have automated these steps for you: ```bash cd postgres-operator ./run_operator_locally.sh +minikube delete ``` ## Scope From 08919fed57472feac4917b6e03a2021e6b0ebe4c Mon Sep 17 00:00:00 2001 From: Sergey Dudoladov Date: Thu, 17 May 2018 10:56:54 +0200 Subject: [PATCH 07/11] Fix links and typos --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index fc32ebc00..754b9315a 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,9 @@ The Postgres [operator](https://coreos.com/blog/introducing-operators.html) manages PostgreSQL clusters on Kubernetes: -1. The operator watches additions, updates and deletions of Postgresql manifests (cluster descriptions) and changes the running clusters accordingly. For example, when a user submits a new manifest, the operator fetches that object and spawns a new Postgres cluster, including all necessary entities such as Kubernetes StatefulSets and Postgres roles. The [`postgresql` Custom Resource Definition](https://kubernetes.io/docs/concepts/api-extension/custom-resources/#customresourcedefinitions) defines settings that a cluster manifest may contain (see example). +1. The operator watches additions, updates, and deletions of PostgreSQL cluster manifests (descriptions) and changes the running clusters accordingly. For example, when a user submits a new manifest, the operator fetches that object and spawns a new Postgres cluster along with all necessary entities such as Kubernetes StatefulSets and Postgres roles. See this [Postgres cluster manifest](manifests/complete-postgres-manifest.yaml) for settings that a manifest may contain. -2. The operator also watches updates to its own configuration and alters running Postgres clusters if necessary. For instance, if a pods' Docker image is changed, the operator carries out the rolling update. That is, it re-spawns one-by-one pods from each StatefulSet it manages with the new Docker image. +2. The operator also watches updates to [its own configuration](manifests/configmap.yaml) and alters running Postgres clusters if necessary. For instance, if a pods' Docker image is changed, the operator carries out the rolling update. That is, the operator re-spawns one-by-one pods of each StatefulSet it manages with the new Docker image. 3. Finally, the operator periodically synchronizes the actual state of each Postgres cluster with the desired state defined in the cluster's manifest. @@ -29,7 +29,7 @@ minikube start # start the operator; may take a few seconds kubectl create -f manifests/configmap.yaml # operator config -kubectl create -f manifests/operator-rbac.yaml # operator identity and persmissions +kubectl create -f manifests/operator-rbac.yaml # operator identity and permissions kubectl create -f manifests/postgres-operator.yaml # operator deployment # submit a Postgres cluster From 83a26fb78bf4cb97c62de52295f58c0a47b71650 Mon Sep 17 00:00:00 2001 From: Sergey Dudoladov Date: Thu, 17 May 2018 12:05:31 +0200 Subject: [PATCH 08/11] Rename RBAC file --- README.md | 6 +++--- ...perator-rbac.yaml => operator-service-account-rbac.yaml} | 0 run_operator_locally.sh | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) rename manifests/{operator-rbac.yaml => operator-service-account-rbac.yaml} (100%) diff --git a/README.md b/README.md index 754b9315a..b70c601fe 100644 --- a/README.md +++ b/README.md @@ -28,9 +28,9 @@ cd postgres-operator minikube start # start the operator; may take a few seconds -kubectl create -f manifests/configmap.yaml # operator config -kubectl create -f manifests/operator-rbac.yaml # operator identity and permissions -kubectl create -f manifests/postgres-operator.yaml # operator deployment +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 # submit a Postgres cluster kubectl create -f manifests/minimal-postgres-manifest.yaml diff --git a/manifests/operator-rbac.yaml b/manifests/operator-service-account-rbac.yaml similarity index 100% rename from manifests/operator-rbac.yaml rename to manifests/operator-service-account-rbac.yaml diff --git a/run_operator_locally.sh b/run_operator_locally.sh index 4fcbe46e2..8e020c76d 100755 --- a/run_operator_locally.sh +++ b/run_operator_locally.sh @@ -134,7 +134,7 @@ function start_operator(){ # the order of resource initialization is significant local file - for file in "configmap.yaml" "operator-rbac.yaml" + for file in "configmap.yaml" "operator-service-account-rbac.yaml" do retry "kubectl create -f manifests/\"$file\"" "attempt to create $file resource" done From cbbbd6915754f0e9ca431ec31ecd2cd7e9803863 Mon Sep 17 00:00:00 2001 From: Sergey Dudoladov Date: Thu, 17 May 2018 15:46:21 +0200 Subject: [PATCH 09/11] Respond to review --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b70c601fe..1545e1b12 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,9 @@ The Postgres [operator](https://coreos.com/blog/introducing-operators.html) manages PostgreSQL clusters on Kubernetes: -1. The operator watches additions, updates, and deletions of PostgreSQL cluster manifests (descriptions) and changes the running clusters accordingly. For example, when a user submits a new manifest, the operator fetches that object and spawns a new Postgres cluster along with all necessary entities such as Kubernetes StatefulSets and Postgres roles. See this [Postgres cluster manifest](manifests/complete-postgres-manifest.yaml) for settings that a manifest may contain. +1. The operator watches additions, updates, and deletions of PostgreSQL cluster manifests and changes the running clusters accordingly. For example, when a user submits a new manifest, the operator fetches that manifest and spawns a new Postgres cluster along with all necessary entities such as Kubernetes StatefulSets and Postgres roles. See this [Postgres cluster manifest](manifests/complete-postgres-manifest.yaml) for settings that a manifest may contain. -2. The operator also watches updates to [its own configuration](manifests/configmap.yaml) and alters running Postgres clusters if necessary. For instance, if a pods' Docker image is changed, the operator carries out the rolling update. That is, the operator re-spawns one-by-one pods of each StatefulSet it manages with the new Docker image. +2. The operator also watches updates to [its own configuration](manifests/configmap.yaml) and alters running Postgres clusters if necessary. For instance, if a pod docker image is changed, the operator carries out the rolling update. That is, the operator re-spawns one-by-one pods of each StatefulSet it manages with the new Docker image. 3. Finally, the operator periodically synchronizes the actual state of each Postgres cluster with the desired state defined in the cluster's manifest. @@ -32,7 +32,7 @@ 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 -# submit a Postgres cluster +# create a Postgres cluster kubectl create -f manifests/minimal-postgres-manifest.yaml # tear down cleanly From 8b4dc02b2b905a5c13fda3e705e679fb0585d03b Mon Sep 17 00:00:00 2001 From: Sergey Dudoladov Date: Thu, 17 May 2018 15:51:29 +0200 Subject: [PATCH 10/11] Remove further mentions of service account --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 1545e1b12..297688b79 100644 --- a/README.md +++ b/README.md @@ -128,7 +128,7 @@ ConfigMap is used to store the configuration of the operator First you need to install the service account definition in your Minikube cluster. - $ kubectl --context minikube create -f manifests/serviceaccount.yaml + $ kubectl --context minikube create -f manifests/operator-service-account-rbac.yaml Next deploy the postgres-operator from the docker image Zalando is using: @@ -173,8 +173,7 @@ kubectl create -f manifests/postgres-operator.yaml kubectl create -f manifests/minimal-postgres-manifest.yaml ``` -Note that the service account in `operator-rbac.yaml` is named `zalando-postgres-operator` and not -the `operator` default that is created in the `serviceaccount.yaml`. So you will have to change the `service_account_name` in the operator configmap and `serviceAccountName` in the postgres-operator deployment appropriately. +Note that the service account in `operator-rbac.yaml` is named `zalando-postgres-operator`. You may have to change the `service_account_name` in the operator configmap and `serviceAccountName` in the postgres-operator deployment appropriately. This is done intentionally, as to avoid breaking those setups that already work with the default `operator` account. In the future the operator should ideally be run under the From d6438bf54b44fc76712670ebae2cb2d08ca20bb5 Mon Sep 17 00:00:00 2001 From: Sergey Dudoladov Date: Thu, 17 May 2018 16:10:02 +0200 Subject: [PATCH 11/11] Insert line breaks in Introduction --- README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 297688b79..6197619f0 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,13 @@ The Postgres [operator](https://coreos.com/blog/introducing-operators.html) manages PostgreSQL clusters on Kubernetes: -1. The operator watches additions, updates, and deletions of PostgreSQL cluster manifests and changes the running clusters accordingly. For example, when a user submits a new manifest, the operator fetches that manifest and spawns a new Postgres cluster along with all necessary entities such as Kubernetes StatefulSets and Postgres roles. See this [Postgres cluster manifest](manifests/complete-postgres-manifest.yaml) for settings that a manifest may contain. +1. The operator watches additions, updates, and deletions of PostgreSQL cluster manifests and changes the running clusters accordingly. +For example, when a user submits a new manifest, the operator fetches that manifest and spawns a new Postgres cluster along with all necessary entities such as Kubernetes StatefulSets and Postgres roles. +See this [Postgres cluster manifest](manifests/complete-postgres-manifest.yaml) for settings that a manifest may contain. -2. The operator also watches updates to [its own configuration](manifests/configmap.yaml) and alters running Postgres clusters if necessary. For instance, if a pod docker image is changed, the operator carries out the rolling update. That is, the operator re-spawns one-by-one pods of each StatefulSet it manages with the new Docker image. +2. The operator also watches updates to [its own configuration](manifests/configmap.yaml) and alters running Postgres clusters if necessary. +For instance, if a pod docker image is changed, the operator carries out the rolling update. +That is, the operator re-spawns one-by-one pods of each StatefulSet it manages with the new Docker image. 3. Finally, the operator periodically synchronizes the actual state of each Postgres cluster with the desired state defined in the cluster's manifest.