From c243074083d7cb15eeb17e9ec94899bc51ac37f4 Mon Sep 17 00:00:00 2001 From: Felix Kunde Date: Mon, 1 Apr 2019 15:39:18 +0200 Subject: [PATCH] Updated quickstart and link from README (#527) * updated quickstart and link from README * added/updated Helm chart description in other docs --- README.md | 69 +++------------------------ docs/administrator.md | 17 +++++-- docs/developer.md | 19 ++++---- docs/quickstart.md | 107 ++++++++++++++++++++++++++++++++---------- 4 files changed, 114 insertions(+), 98 deletions(-) diff --git a/README.md b/README.md index 8c6fee81a..61f5c5adc 100644 --- a/README.md +++ b/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. - - diff --git a/docs/administrator.md b/docs/administrator.md index 208e9ddb9..32a749e36 100644 --- a/docs/administrator.md +++ b/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 diff --git a/docs/developer.md b/docs/developer.md index 5857c2266..294d06ebf 100644 --- a/docs/developer.md +++ b/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 diff --git a/docs/quickstart.md b/docs/quickstart.md index bdf5bd5d0..244f45b54 100644 --- a/docs/quickstart.md +++ b/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.