diff --git a/charts/postgres-operator/Chart.yaml b/charts/postgres-operator/Chart.yaml index 1817bf411..14ecf8c47 100644 --- a/charts/postgres-operator/Chart.yaml +++ b/charts/postgres-operator/Chart.yaml @@ -3,7 +3,7 @@ name: postgres-operator version: 1.2.0 appVersion: 1.2.0 home: https://github.com/zalando/postgres-operator -description: Postgres operator creates and manages PostgreSQL clusters running in Kubernetes +description: Postgres Operator creates and manages PostgreSQL clusters running in Kubernetes keywords: - postgres - operator diff --git a/docker/Dockerfile b/docker/Dockerfile index 196ac93d3..520fd2d07 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -7,7 +7,7 @@ RUN apk --no-cache add ca-certificates COPY build/* / RUN addgroup -g 1000 pgo -RUN adduser -D -u 1000 -G pgo -g 'Postgres operator' pgo +RUN adduser -D -u 1000 -G pgo -g 'Postgres Operator' pgo USER 1000:1000 diff --git a/docker/logical-backup/dump.sh b/docker/logical-backup/dump.sh index d74c7653b..fea3161e5 100755 --- a/docker/logical-backup/dump.sh +++ b/docker/logical-backup/dump.sh @@ -7,7 +7,7 @@ set -o pipefail IFS=$'\n\t' # make script trace visible via `kubectl logs` -set -o xtrace +set -o xtrace ALL_DB_SIZE_QUERY="select sum(pg_database_size(datname)::numeric) from pg_database;" PG_BIN=$PG_DIR/$PG_VERSION/bin @@ -35,7 +35,7 @@ function aws_upload { # mimic bucket setup from Spilo # to keep logical backups at the same path as WAL - # NB: $LOGICAL_BACKUP_S3_BUCKET_SCOPE_SUFFIX already contains the leading "/" when set by the Postgres operator + # NB: $LOGICAL_BACKUP_S3_BUCKET_SCOPE_SUFFIX already contains the leading "/" when set by the Postgres Operator PATH_TO_BACKUP=s3://$LOGICAL_BACKUP_S3_BUCKET"/spilo/"$SCOPE$LOGICAL_BACKUP_S3_BUCKET_SCOPE_SUFFIX"/logical_backups/"$(date +%s).sql.gz if [ -z "$EXPECTED_SIZE" ]; then diff --git a/docs/administrator.md b/docs/administrator.md index 4629d1284..510d2814c 100644 --- a/docs/administrator.md +++ b/docs/administrator.md @@ -278,7 +278,7 @@ operator will respectively do noting with the existing source ranges. ## Running periodic 'autorepair' scans of Kubernetes objects -The Postgres operator periodically scans all Kubernetes objects belonging to +The Postgres Operator periodically scans all Kubernetes objects belonging to each cluster and repairs all discrepancies between them and the definitions generated from the current cluster manifest. There are two types of scans: diff --git a/docs/developer.md b/docs/developer.md index 28bad2e9f..f7c7a1fbc 100644 --- a/docs/developer.md +++ b/docs/developer.md @@ -1,120 +1,20 @@ -## Intro +# Developer Guide -See [minikube installation guide](https://github.com/kubernetes/minikube/releases) - -Make sure you use the latest version of Minikube. - -After the installation, issue - -```bash - $ minikube start -``` - -Note: if you are running on a Mac, you may also use Docker for Mac Kubernetes -instead of a docker-machine. - -Once 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` - -## Deploying the operator - -### Kubernetes manifest - -A ConfigMap is used to store the configuration of the operator. Alternatively, -a CRD-based configuration can be used, as described [here](reference/operator_parameters). - -```bash - $ kubectl --context minikube create -f manifests/configmap.yaml -``` - -First you need to install the service account definition in your Minikube cluster. - -```bash - $ kubectl --context minikube create -f manifests/operator-service-account-rbac.yaml -``` - -Next deploy the postgres-operator from the docker image Zalando is using: - -```bash - $ kubectl --context minikube create -f manifests/postgres-operator.yaml -``` - -If you prefer to build the image yourself follow up down below. - -### Helm chart - -Alternatively, the operator can be installed by using the provided [Helm](https://helm.sh/) -chart which saves you the manual 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. -You can define a release name that is prepended to the operator resource's -names. - -Use `--name zalando` to match with the default service account name as older -operator versions do not support custom names for service accounts. When relying -solely on the CRD-based configuration edit the `serviceAccount` section in the -[values yaml file](../charts/values.yaml) by setting the name to `"operator"`. - -```bash - $ helm init - $ helm install --name zalando ./charts/postgres-operator -``` - -## Check if CustomResourceDefinition has been registered - -```bash - $ kubectl --context minikube get crd - - NAME KIND - postgresqls.acid.zalan.do CustomResourceDefinition.v1beta1.apiextensions.k8s.io -``` - -## Create a new Spilo cluster - -```bash - $ kubectl --context minikube create -f manifests/minimal-postgres-manifest.yaml -``` - -## Watch pods being created - -```bash - $ 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-minimal-cluster` master running in Minikube: - -```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 --context minikube get secret postgres.acid-minimal-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. +Reed this guide if you want to debug the operator, fix bugs or contribute new +features and tests. ## 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/). +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 +Given the schema above, the Postgres Operator source code located at `github.com/zalando/postgres-operator` should be put at -`~/go/src/github.com/zalando/postgres-operator`. @@ -173,7 +73,7 @@ minikube. The following steps will get you the docker image built and deployed. $ sed -e "s/\(image\:.*\:\).*$/\1$TAG/" manifests/postgres-operator.yaml|kubectl --context minikube create -f - ``` -# Code generation +## Code generation The operator employs k8s-provided code generation to obtain deep copy methods and Kubernetes-like APIs for its custom resource definitons, namely the Postgres @@ -199,7 +99,7 @@ operator itself with `--v=8` to log all REST API requests). To attach a debugger to the operator, use the `-outofcluster` option to run the operator locally on the developer's laptop (and not in a docker container). -# Debugging the operator +## Debugging the operator 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 @@ -325,10 +225,10 @@ kubectl logs acid-minimal-cluster-0 ## End-to-end tests The operator provides reference e2e (end-to-end) tests to ensure various infra parts work smoothly together. -Each e2e execution tests a Postgres operator image built from the current git branch. The test runner starts a [kind](https://kind.sigs.k8s.io/) (local k8s) cluster and Docker container with tests. The k8s API client from within the container connects to the `kind` cluster using the standard Docker `bridge` network. +Each e2e execution tests a Postgres Operator image built from the current git branch. The test runner starts a [kind](https://kind.sigs.k8s.io/) (local k8s) cluster and Docker container with tests. The k8s API client from within the container connects to the `kind` cluster using the standard Docker `bridge` network. The tests utilize examples from `/manifests` (ConfigMap is used for the operator configuration) to avoid maintaining yet another set of configuration files. The kind cluster is deleted if tests complete successfully. -End-to-end tests are executed automatically during builds; to invoke them locally use `make e2e-run` from the project's top directory. Run `make e2e-tools e2e-build` to install `kind` and build the tests' image locally before the first run. +End-to-end tests are executed automatically during builds; to invoke them locally use `make e2e-run` from the project's top directory. Run `make e2e-tools e2e-build` to install `kind` and build the tests' image locally before the first run. End-to-end tests are written in Python and use `flake8` for code quality. Please run flake8 [before submitting a PR](http://flake8.pycqa.org/en/latest/user/using-hooks.html). diff --git a/docs/quickstart.md b/docs/quickstart.md index 4c8b565b1..bc4e42eb8 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,25 +1,26 @@ # Quickstart +This guide aims to give you a quick look and feel for using the Postgres +Operator on a local Kubernetes environment. + ## Prerequisites The Postgres Operator runs on Kubernetes (K8s) which you have to setup first. -For local tests we recommend to use solutions such as [minikube](https://github.com/kubernetes/minikube/releases) -or [kind](https://kind.sigs.k8s.io/). This quickstart guide uses minikube. +For local tests we recommend to use one of the following solutions: + +* [minikube](https://github.com/kubernetes/minikube/releases), which creates a + single-node K8s cluster inside a VM (requires KVM or VirtualBox), +* [kind](https://kind.sigs.k8s.io/), which allows creating multi-nodes K8s + clusters running on Docker (requires Docker) + To interact with the K8s infrastructure install it's CLI runtime [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 +This quickstart assumes that you haved started minikube or created a local kind +cluster. 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 actions for the Docker built-in Kubernetes support. -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 -``` ## Configuration Options @@ -28,17 +29,41 @@ Postgres cluster. This can happen in two ways: Via a ConfigMap or a custom `OperatorConfiguration` object. More details on configuration can be found [here](reference/operator_parameters.md). -## Manual deployment setup -The Postgres Operator can be installed simply by applying yaml manifests. +## Deployment options + +The Postgres Operator can be deployed in different way: + +* Manual deployment +* Helm chart +* Operator Lifecycle Manager (OLM) + +### Manual deployment setup + +The Postgres Operator can be installed simply by applying yaml manifests. Note, +we provide the `/manifests` directory as an example only; you should consider +adjusting the manifests to your particular setting (e.g. namespaces). ```bash +# First, clone the repository and change to the directory +git clone https://github.com/zalando/postgres-operator.git +cd postgres-operator + +# apply the manifests in the following order 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 +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 +``` + +### Helm chart Alternatively, the operator can be installed by using the provided [Helm](https://helm.sh/) chart which saves you the manual steps. Therefore, you would need to install @@ -59,6 +84,21 @@ helm init helm install --name zalando ./charts/postgres-operator ``` +### Operator Lifecycle Manager (OLM) + +The [Operator Lifecycle Manager (OLM)](https://github.com/operator-framework/operator-lifecycle-manager) +has been designed to facilitate the management of K8s operators. You have to +install it in your K8s environment. When OLM is set up you can simply download +and deploy the Postgres Operator with the following command: + +```bash +kubectl create -f https://operatorhub.io/install/postgres-operator.yaml +``` + +This installs the operator in the `operators` namespace. More information can be +found on [operatorhub.io](https://operatorhub.io/operator/postgres-operator). + + ## Create a Postgres cluster Starting the operator may take a few seconds. Check if the operator pod is @@ -96,6 +136,7 @@ kubectl get pods -l application=spilo -L spilo-role 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. @@ -109,29 +150,19 @@ export PGPASSWORD=$(kubectl get secret postgres.acid-minimal-cluster.credentials psql -U postgres ``` + ## Delete a Postgres cluster -To delete a Postgres cluster simply delete the postgresql custom resource. +To delete a Postgres cluster simply delete the `postgresql` custom resource. ```bash kubectl delete postgresql acid-minimal-cluster - -# tear down cleanly -minikube delete ``` -## 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. +This should remove the associated StatefulSet, database Pods, Services and +Endpoints. The PersistentVolumes are released and the PodDisruptionBudget is +deleted. Secrets however are not deleted. When deleting a cluster while it is +still starting up it can [happen](https://github.com/zalando/postgres-operator/issues/551) +the `postgresql` resource is deleted leaving orphaned components behind. This +can cause troubles when creating a new Postgres cluster. For a fresh setup you +can delete your local minikube and kind cluster and start again. diff --git a/docs/user.md b/docs/user.md index 4cce153aa..b9368d6b5 100644 --- a/docs/user.md +++ b/docs/user.md @@ -1,3 +1,8 @@ +# User Guide + +Learn how to work with the Postgres Operator in a production Kubernetes +environment. + ## Create a manifest for a new PostgreSQL cluster As an example you can take this @@ -75,7 +80,7 @@ $ psql -U postgres -p 6432 # Defining database roles in the operator -Postgres operator allows defining roles to be created in the resulting database +Postgres Operator allows defining roles to be created in the resulting database cluster. It covers three use-cases: * `manifest roles`: create application roles specific to the cluster described in the manifest. diff --git a/run_operator_locally.sh b/run_operator_locally.sh index ee0768354..2b2fa59df 100755 --- a/run_operator_locally.sh +++ b/run_operator_locally.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash # -# Deploy a Postgres operator to a minikube aka local Kubernetes cluster +# Deploy a Postgres Operator to a minikube aka local Kubernetes cluster # Optionally re-build the operator binary beforehand to test local changes # Known limitations: @@ -213,7 +213,7 @@ function submit_postgresql_manifest(){ function main(){ if ! [[ $(basename "$PWD") == "postgres-operator" ]]; then - echo "Please execute the script only from the root directory of the Postgres operator repo." + echo "Please execute the script only from the root directory of the Postgres Operator repo." exit 1 fi