public_git
/
postgres-operator
mirror of https://github.com/zalando/postgres-operator.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

updated docs and write Postgres Operator in capital letters

This commit is contained in:
Felix Kunde 2019-06-18 15:54:43 +02:00
parent 7cdf376b69
commit c1d7d0623f
8 changed files with 89 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
charts/postgres-operator/Chart.yaml
View File

@ -3,7 +3,7 @@ name: postgres-operator
version: 1.2.0 version: 1.2.0
appVersion: 1.2.0 appVersion: 1.2.0
home: https://github.com/zalando/postgres-operator 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: keywords:
- postgres - postgres
- operator - operator

2
docker/Dockerfile
View File

@ -7,7 +7,7 @@ RUN apk --no-cache add ca-certificates
COPY build/* / COPY build/* /
RUN addgroup -g 1000 pgo 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 USER 1000:1000

2
docker/logical-backup/dump.sh
View File

@ -35,7 +35,7 @@ function aws_upload {
# mimic bucket setup from Spilo # mimic bucket setup from Spilo
# to keep logical backups at the same path as WAL # 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 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 if [ -z "$EXPECTED_SIZE" ]; then

2
docs/administrator.md
View File

@ -278,7 +278,7 @@ operator will respectively do noting with the existing source ranges.
## Running periodic 'autorepair' scans of Kubernetes objects ## 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 each cluster and repairs all discrepancies between them and the definitions
generated from the current cluster manifest. There are two types of scans: generated from the current cluster manifest. There are two types of scans:

120
docs/developer.md
View File

@ -1,120 +1,20 @@
## Intro # Developer Guide
See [minikube installation guide](https://github.com/kubernetes/minikube/releases) Reed this guide if you want to debug the operator, fix bugs or contribute new
features and tests.
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.
## Setting up Go ## Setting up Go
Postgres operator is written in Go. Use the [installation Postgres Operator is written in Go. Use the [installation instructions](https://golang.org/doc/install#install)
instructions](https://golang.org/doc/install#install) if you don't have Go on if you don't have Go on your system. You won't be able to compile the operator
your system. You won't be able to compile the operator with Go older than 1.7. with Go older than 1.7. We recommend installing [the latest one](https://golang.org/dl/).
We recommend installing [the latest one](https://golang.org/dl/).
Go projects expect their source code and all the dependencies to be located 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 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 would create a directory for the GOPATH (i.e. ~/go) and place the source code
under the ~/go/src subdirectories. 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 `github.com/zalando/postgres-operator` should be put at
-`~/go/src/github.com/zalando/postgres-operator`. -`~/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 - $ 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 The operator employs k8s-provided code generation to obtain deep copy methods
and Kubernetes-like APIs for its custom resource definitons, namely the Postgres 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 to the operator, use the `-outofcluster` option to run the operator locally on
the developer's laptop (and not in a docker container). 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 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 operator listens on port 8080. It is possible to expose it to the
@ -325,7 +225,7 @@ kubectl logs acid-minimal-cluster-0
## End-to-end tests ## End-to-end tests
The operator provides reference e2e (end-to-end) tests to ensure various infra parts work smoothly together. 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. 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.

99
docs/quickstart.md
View File

@ -1,25 +1,26 @@
# Quickstart # Quickstart
This guide aims to give you a quick look and feel for using the Postgres
Operator on a local Kubernetes environment.
## Prerequisites ## Prerequisites
The Postgres Operator runs on Kubernetes (K8s) which you have to setup first. 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) For local tests we recommend to use one of the following solutions:
or [kind](https://kind.sigs.k8s.io/). This quickstart guide uses minikube.
* [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). 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 This quickstart assumes that you haved started minikube or created a local kind
for Mac to follow the steps of this tutorial. You would have to replace 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 `minikube start` and `minikube delete` with your launch actions for the Docker
built-in Kubernetes support. 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 ## 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 `OperatorConfiguration` object. More details on configuration can be found
[here](reference/operator_parameters.md). [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 ```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/configmap.yaml # configuration
kubectl create -f manifests/operator-service-account-rbac.yaml # identity and permissions kubectl create -f manifests/operator-service-account-rbac.yaml # identity and permissions
kubectl create -f manifests/postgres-operator.yaml # deployment 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/) 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 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 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 ## Create a Postgres cluster
Starting the operator may take a few seconds. Check if the operator pod is 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 kubectl get svc -l application=spilo -L spilo-role
``` ```
## Connect to the Postgres cluster via psql ## Connect to the Postgres cluster via psql
You can retrieve the host and port of the Postgres master from minikube. 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 psql -U postgres
``` ```
## Delete a Postgres cluster ## 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 ```bash
kubectl delete postgresql acid-minimal-cluster kubectl delete postgresql acid-minimal-cluster
# tear down cleanly
minikube delete
``` ```
## Running and testing the operator This should remove the associated StatefulSet, database Pods, Services and
Endpoints. The PersistentVolumes are released and the PodDisruptionBudget is
The best way to test the operator is to run it in [minikube](https://kubernetes.io/docs/getting-started-guides/minikube/). deleted. Secrets however are not deleted. When deleting a cluster while it is
Minikube is a tool to run Kubernetes cluster locally. still starting up it can [happen](https://github.com/zalando/postgres-operator/issues/551)
the `postgresql` resource is deleted leaving orphaned components behind. This
For convenience, we have automated starting the operator and submitting the can cause troubles when creating a new Postgres cluster. For a fresh setup you
`acid-minimal-cluster`. From inside the cloned repository execute the can delete your local minikube and kind cluster and start again.
`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.

7
docs/user.md
View File

@ -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 ## Create a manifest for a new PostgreSQL cluster
As an example you can take this As an example you can take this
@ -75,7 +80,7 @@ $ psql -U postgres -p 6432
# Defining database roles in the operator # 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: cluster. It covers three use-cases:
* `manifest roles`: create application roles specific to the cluster described in the manifest. * `manifest roles`: create application roles specific to the cluster described in the manifest.

4
run_operator_locally.sh
View File

@ -1,6 +1,6 @@
#!/usr/bin/env bash #!/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 # Optionally re-build the operator binary beforehand to test local changes
# Known limitations: # Known limitations:
@ -213,7 +213,7 @@ function submit_postgresql_manifest(){
function main(){ function main(){
if ! [[ $(basename "$PWD") == "postgres-operator" ]]; then 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 exit 1
fi fi