updated docs and write Postgres Operator in capital letters
This commit is contained in:
Felix Kunde
parent
7cdf376b69
commit
c1d7d0623f
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue