From 10d4a7492e1e0d210d870672fe35c52cf0574279 Mon Sep 17 00:00:00 2001 From: Felix Kunde Date: Mon, 15 Feb 2021 16:09:22 +0100 Subject: [PATCH] smoe more README updates --- kubectl-pg/README.md | 111 ++++++++++++++++++++----------------------- 1 file changed, 52 insertions(+), 59 deletions(-) diff --git a/kubectl-pg/README.md b/kubectl-pg/README.md index 7d87443a6..78102cf9c 100644 --- a/kubectl-pg/README.md +++ b/kubectl-pg/README.md @@ -1,29 +1,14 @@ # Kubectl Plugin for Zalando's Postgres Operator -## Google Summer of Code 2019 +This plugin is a prototype developed as a part of **Google Summer of Code 2019** under the [Postgres Operator](https://summerofcode.withgoogle.com/archive/2019/organizations/6187982082539520/) organization. -This plugin is a prototype developed as a part of GSoC 2019 under the organisation -**The Postgres Operator** +## Installation of kubectl pg plugin -### GSoC Proposal +This project uses Go Modules for dependency management to build locally. +Install go and enable go modules with ```export GO111MODULE=on```. +From Go >=1.13 Go modules will be enabled by default. -[kubectl pg proposal](https://docs.google.com/document/d/1-WMy9HkfZ1XnnMbzplMe9rCzKrRMGaMz4owLVXXPb7w/edit) - -### Weekly Reports - -https://github.com/VineethReddy02/GSoC-Kubectl-Plugin-for-Postgres-Operator-tracker - - ### Final Project Report - - https://gist.github.com/VineethReddy02/159283bd368a710379eaf0f6bd60a40a - - -### Installtion of kubectl pg plugin - -This project uses Go Modules for dependency management to build locally -Install go and enable go modules ```export GO111MODULE=on``` -From Go >=1.13 Go modules will be enabled by default -``` +```bash # Assumes you have a working KUBECONFIG $ GO111MODULE="on" $ GOPATH/src/github.com/zalando/postgres-operator/kubectl-pg go mod vendor @@ -32,71 +17,66 @@ $ $GOPATH/src/github.com/zalando/postgres-operator/kubectl-pg go install # This will place the kubectl-pg binary in your $GOPATH/bin ``` -### Before using the kubectl pg plugin make sure to set KUBECONFIG env variable +## Before using the kubectl pg plugin make sure to set KUBECONFIG env variable Ideally KUBECONFIG is found in $HOME/.kube/config else specify the KUBECONFIG path here. - ```export KUBECONFIG=$HOME/.kube/config``` -### To list all commands available in kubectl pg +## List all commands available in kubectl pg ```kubectl pg --help``` (or) ```kubectl pg``` -### This basically means the operator pod managed to start, so our operator is installed. +## Check if Postgres Operator is installed and running ```kubectl pg check``` -### To create postgresql cluster using manifest file +## Create a new cluster using manifest file ```kubectl pg create -f acid-minimal-cluster.yaml``` -### To update existing cluster using manifest file - -```kubectl pg update -f acid-minimal-cluster.yaml``` - -### To delete existing cluster using manifest file - -```kubectl pg delete -f acid-minimal-cluster.yaml``` - -### To delete existing cluster using cluster name - -```kubectl pg delete acid-minimal-cluster``` - -Use `--namespace` or `-n` flag to specify namespace if cluster is in other namespace. - -```kubectl pg delete acid-minimal-cluster -n namespace01``` - -### To list postgres resources for the current namespace +## List postgres resources ```kubectl pg list``` -### To list postgres resources across namespaces - +List clusters across namespaces ```kubectl pg list all``` -### To add-user and it's roles to an existing pg cluster +## Update existing cluster using manifest file + +```kubectl pg update -f acid-minimal-cluster.yaml``` + +## Delete existing cluster + +Using the manifest file: +```kubectl pg delete -f acid-minimal-cluster.yaml``` + +Or by specifying the cluster name: +```kubectl pg delete acid-minimal-cluster``` + +Use `--namespace` or `-n` flag if your cluster is in a different namespace to where your current context is pointing to: +```kubectl pg delete acid-minimal-cluster -n namespace01``` + +## Adding manifest roles to an existing cluster ```kubectl pg add-user USER01 -p CREATEDB,LOGIN -c acid-minimal-cluster``` Privileges can only be [SUPERUSER, REPLICATION, INHERIT, LOGIN, NOLOGIN, CREATEROLE, CREATEDB, BYPASSURL] +Note: By default, a LOGIN user is created (unless NOLOGIN is specified). -Note: A login user is created by default unless NOLOGIN is specified, in which case the operator creates a role. - -### To add-db and it's owner to an existing pg cluster +## Adding databases to an existing cluster +You have to specify an owner of the new database and this role must already exist in the cluster: ```kubectl pg add-db DB01 -o OWNER01 -c acid-minimal-cluster``` -### To extend volume for an existing pg cluster +## Extend the volume of an existing pg cluster ```kubectl pg ext-volume 2Gi -c acid-minimal-cluster``` -### To find the version of postgres operator and kubectl plugin +## Print the version of Postgres Operator and kubectl pg plugin ```kubectl pg version``` -Optional `-n NAMESPACE` allows to know specific to a namespace - -### To connect to the shell of a postgres pod +## Connect to the shell of a postgres pod Connect to the master pod: ```kubectl pg connect -c CLUSTER -m``` @@ -107,7 +87,7 @@ Connect to a random replica pod: Connect to a certain replica pod: ```kubectl pg connect -c CLUSTER -r 0``` -### To connect to the psql prompt +## Connect to a database via psql Adding the `-p` flag allows you to directly connect to a given database with the psql client. With `-u` you specify the user. If left out the name of the current OS user is taken. @@ -123,11 +103,11 @@ Connect to a certain replica assuming name of OS user, database role and name ar ```kubectl pg connect -c CLUSTER -r 0 -p``` -### To get the logs of postgres operator +## Access Postgres Operator logs ```kubectl pg logs -o``` -### To get the logs of the postgres cluster +## Access Patroni logs of different database pods Fetch logs of master: ```kubectl pg logs -c CLUSTER -m``` @@ -140,5 +120,18 @@ Fetch logs of specified replica ## Development -When making changes to plugin make sure to change the major or patch version -of plugin in ```build.sh``` and run ```./build.sh``` +When making changes to the plugin make sure to change the (major/patch) version of plugin in `build.sh` script and run `./build.sh`. + +## Google Summer of Code 2019 + +### GSoC Proposal + +[kubectl pg proposal](https://docs.google.com/document/d/1-WMy9HkfZ1XnnMbzplMe9rCzKrRMGaMz4owLVXXPb7w/edit) + +### Weekly Reports + +https://github.com/VineethReddy02/GSoC-Kubectl-Plugin-for-Postgres-Operator-tracker + +### Final Project Report + +https://gist.github.com/VineethReddy02/159283bd368a710379eaf0f6bd60a40a