From b93abfd756495bf7b54fb93c3f5cc759bbfd2bc5 Mon Sep 17 00:00:00 2001 From: shahriar Date: Mon, 26 Feb 2018 12:12:52 +0600 Subject: [PATCH 1/3] Merge branch 'master' of github.com:kubedb/cli into postgres-docs # Conflicts: # docs/concepts/databases/postgres.md # docs/examples/postgres/clustering/hot-postgres.yaml # docs/guides/postgres/clustering/ha_cluster.md # docs/guides/postgres/clustering/streaming_replication.md --- docs/concepts/databases/postgres.md | 2 +- docs/guides/cli.md | 10 +++++----- docs/guides/postgres/README.md | 10 +++++----- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/concepts/databases/postgres.md b/docs/concepts/databases/postgres.md index a54baea89..74ea3fb7d 100644 --- a/docs/concepts/databases/postgres.md +++ b/docs/concepts/databases/postgres.md @@ -79,7 +79,7 @@ spec: ### spec.version `spec.version` is a required field specifying the version of PostgreSQL database. Currently the supported versions are: - - `9.6.5`, `9.6` + - `9.6.7`, `9.6` ### spec.replicas `spec.replicas` specifies the total number of primary and standby nodes in Postgres database cluster configuration. One pod is selected as Primary and others are acted as standby replicas. diff --git a/docs/guides/cli.md b/docs/guides/cli.md index 2c53d4325..fbb9d06c3 100644 --- a/docs/guides/cli.md +++ b/docs/guides/cli.md @@ -69,7 +69,7 @@ metadata: spec: databaseSecret: secretName: postgres-demo-auth - version: 9.6.5 + version: 9.6.7 status: creationTime: 2017-12-12T05:46:16Z phase: Running @@ -90,10 +90,10 @@ NAME VERSION STATUS AGE es/elasticsearch-demo 2.3.1 Running 17m NAME VERSION STATUS AGE -pg/postgres-demo 9.6.5 Running 3h -pg/postgres-dev 9.6.5 Running 3h -pg/postgres-prod 9.6.5 Running 3h -pg/postgres-qa 9.6.5 Running 3h +pg/postgres-demo 9.6.7 Running 3h +pg/postgres-dev 9.6.7 Running 3h +pg/postgres-prod 9.6.7 Running 3h +pg/postgres-qa 9.6.7 Running 3h NAME DATABASE BUCKET STATUS AGE snap/postgres-demo-20170605-073557 pg/postgres-demo gs:bucket-name Succeeded 9m diff --git a/docs/guides/postgres/README.md b/docs/guides/postgres/README.md index a5d5819ef..b01231b85 100644 --- a/docs/guides/postgres/README.md +++ b/docs/guides/postgres/README.md @@ -2,11 +2,11 @@ ## PostgreSQL versions supported by KubeDB -| KubeDB Version | Postgres:9.5 | Postgres:9.6 | -|----------------|:------------:|:------------:| -| 0.1.0 - 0.7.0 | ✓ | ✗ | -| 0.8.0-beta.0 | ✗ | ✓ | -| 0.8.0-beta.1 | ✗ | ✓ | +| KubeDB Version | Postgres:9.5 | Postgres:9.6 | Postgres:10.2 | +|----------------|:------------:|:------------:|:-------------:| +| 0.1.0 - 0.7.0 | ✓ | ✗ | ✗ | +| 0.8.0-beta.0 | ✗ | ✓ | ✗ | +| 0.8.0-beta.1 | ✗ | ✓ | ✓ |
From 9ac5e78abd21cfc9431efc601341b13aa69c92a9 Mon Sep 17 00:00:00 2001 From: shahriar Date: Mon, 26 Feb 2018 13:18:27 +0600 Subject: [PATCH 2/3] fixed --- .../clustering/streaming_replication.md | 17 +++++++++-------- .../postgres/initialization/script_source.md | 4 ++-- .../postgres/initialization/snapshot_source.md | 4 ++-- docs/guides/postgres/quickstart/quickstart.md | 16 ++++++++-------- docs/guides/postgres/snapshot/instant_backup.md | 2 +- 5 files changed, 22 insertions(+), 21 deletions(-) diff --git a/docs/guides/postgres/clustering/streaming_replication.md b/docs/guides/postgres/clustering/streaming_replication.md index bf20aa735..f8ad0ae79 100644 --- a/docs/guides/postgres/clustering/streaming_replication.md +++ b/docs/guides/postgres/clustering/streaming_replication.md @@ -65,7 +65,8 @@ Streaming Replication is **asynchronous** by default. As a result, there is a sm Following parameters are set in `postgresql.conf` for both *primary* and *standby* server ```console -archive_mode = always +wal_level = replica +max_wal_senders = 99 wal_keep_segments = 32 ``` @@ -119,20 +120,20 @@ And two services for Postgres `ha-postgres` are created. $ kubectl get svc -n demo --selector="kubedb.com/name=ha-postgres" NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ha-postgres ClusterIP 10.106.9.219 5432/TCP 4m -ha-postgres-primary ClusterIP 10.104.95.105 5432/TCP 4m +ha-postgres-replicas ClusterIP 10.104.95.105 5432/TCP 4m ``` ```console $ kubectl get svc -n demo --selector="kubedb.com/name=ha-postgres" -o=custom-columns=NAME:.metadata.name,SELECTOR:.spec.selector -NAME SELECTOR -ha-postgres map[kubedb.com/kind:Postgres kubedb.com/name:ha-postgres] -ha-postgres-primary map[kubedb.com/kind:Postgres kubedb.com/name:ha-postgres kubedb.com/role:primary] +NAME SELECTOR +ha-postgres map[kubedb.com/kind:Postgres kubedb.com/name:ha-postgres kubedb.com/role:primary] +ha-postgres-replicas map[kubedb.com/kind:Postgres kubedb.com/name:ha-postgres] ``` Here, -- Service `ha-postgres` targets all Pods (*`ha-postgres-0`*, *`ha-postgres-1`* and *`ha-postgres-2`*) with label `kubedb.com/kind=Postgres,kubedb.com/name=ha-postgres`. -- Service `ha-postgres-primary` targets Pod `ha-postgres-0`, which is *primary* server, by selector `kubedb.com/kind=Postgres,kubedb.com/name=ha-postgres,kubedb.com/role=primary`. +- Service `ha-postgres` targets Pod `ha-postgres-0`, which is *primary* server, by selector `kubedb.com/kind=Postgres,kubedb.com/name=ha-postgres,kubedb.com/role=primary`. +- Service `ha-postgres-replicas` targets all Pods (*`ha-postgres-0`*, *`ha-postgres-1`* and *`ha-postgres-2`*) with label `kubedb.com/kind=Postgres,kubedb.com/name=ha-postgres`. > These *standby* servers are asynchronous *warm standby* server. @@ -143,7 +144,7 @@ Now connect to this *primary* server Pod `ha-postgres-0` using pgAdmin installed Connection information: - address: you can use any of these - - Service `ha-postgres-primary.demo` + - Service `ha-postgres.demo` - Pod IP (`$ kubectl get pods ha-postgres-0 -n demo -o yaml | grep podIP`) - port: `5432` - database: `postgres` diff --git a/docs/guides/postgres/initialization/script_source.md b/docs/guides/postgres/initialization/script_source.md index f5be81568..6238f250c 100644 --- a/docs/guides/postgres/initialization/script_source.md +++ b/docs/guides/postgres/initialization/script_source.md @@ -86,7 +86,7 @@ Volume: Capacity: 50Mi Access Modes: RWO StatefulSet: script-postgres -Service: script-postgres, script-postgres-primary +Service: script-postgres, script-postgres-replicas Secrets: script-postgres-auth Topology: @@ -111,7 +111,7 @@ Now lets connect to our Postgres `script-postgres` using pgAdmin we have instal Connection information: -- address: use Service `script-postgres-primary.demo` +- address: use Service `script-postgres.demo` - port: `5432` - database: `postgres` - username: `postgres` diff --git a/docs/guides/postgres/initialization/snapshot_source.md b/docs/guides/postgres/initialization/snapshot_source.md index d58665dd0..bba050648 100644 --- a/docs/guides/postgres/initialization/snapshot_source.md +++ b/docs/guides/postgres/initialization/snapshot_source.md @@ -139,7 +139,7 @@ Volume: Capacity: 50Mi Access Modes: RWO StatefulSet: recovered-postgres -Service: recovered-postgres, recovered-postgres-primary +Service: recovered-postgres, recovered-postgres-replicas Secrets: script-postgres-auth Topology: @@ -166,7 +166,7 @@ Now lets connect to our Postgres `recovered-postgres` using pgAdmin we have ins Connection information: -- address: use Service `recovered-postgres-primary.demo` +- address: use Service `recovered-postgres.demo` - port: `5432` - database: `postgres` - username: `postgres` diff --git a/docs/guides/postgres/quickstart/quickstart.md b/docs/guides/postgres/quickstart/quickstart.md index 4783d1237..c42d0e19b 100644 --- a/docs/guides/postgres/quickstart/quickstart.md +++ b/docs/guides/postgres/quickstart/quickstart.md @@ -133,7 +133,7 @@ Service: Port: api 5432/TCP Service: - Name: quick-postgres-primary + Name: quick-postgres-replicas Type: ClusterIP IP: 10.96.98.122 Port: api 5432/TCP @@ -165,15 +165,15 @@ Events: ```console $ kubectl get service -n demo --selector=kubedb.com/kind=Postgres,kubedb.com/name=quick-postgres -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -quick-postgres ClusterIP 10.104.43.68 5432/TCP 5m -quick-postgres-primary ClusterIP 10.96.98.122 5432/TCP 5m +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +quick-postgres ClusterIP 10.104.43.68 5432/TCP 5m +quick-postgres-replicas ClusterIP 10.96.98.122 5432/TCP 5m ``` Two services for each Postgres object. - - Service *`quick-postgres`* targets all Pods created by StatefulSet - - Service *`quick-postgres-primary`* targets only one Pod which is acting as *primary* server + - Service *`quick-postgres`* targets only one Pod which is acting as *primary* server + - Service *`quick-postgres-replicas`* targets all Pods created by StatefulSet KubeDB supports PostgreSQL clustering where Pod can be either *primary* or *standby*. To learn how to configure highly available PostgreSQL cluster, click [here](/docs/guides/postgres/clustering/ha_cluster.md). @@ -204,12 +204,12 @@ This Secret contains `postgres` superuser password as `POSTGRES_PASSWORD` key. > Note: Auth Secret name format: `{postgres-name}-auth` -Now, you can connect to this database from the pgAdmin dashboard using Service `quick-postgres-primary.demo` and `postgres` superuser password . +Now, you can connect to this database from the pgAdmin dashboard using Service `quick-postgres.demo` and `postgres` superuser password . Connection information: - address: you can use any of these - - Service `quick-postgres-primary.demo` + - Service `quick-postgres.demo` - Pod IP (`$ kubectl get pods quick-postgres-0 -n demo -o yaml | grep podIP`) - port: `5432` - database: `postgres` diff --git a/docs/guides/postgres/snapshot/instant_backup.md b/docs/guides/postgres/snapshot/instant_backup.md index da0eb5b39..894126833 100644 --- a/docs/guides/postgres/snapshot/instant_backup.md +++ b/docs/guides/postgres/snapshot/instant_backup.md @@ -226,7 +226,7 @@ Volume: Capacity: 50Mi Access Modes: RWO StatefulSet: script-postgres -Service: script-postgres, script-postgres-primary +Service: script-postgres, script-postgres-replicas Secrets: script-postgres-auth Topology: From ed072d0fa73556b127defbdee78685c86db35825 Mon Sep 17 00:00:00 2001 From: shahriar Date: Mon, 26 Feb 2018 13:25:46 +0600 Subject: [PATCH 3/3] fixed --- docs/concepts/databases/postgres.md | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/docs/concepts/databases/postgres.md b/docs/concepts/databases/postgres.md index 74ea3fb7d..dd6103157 100644 --- a/docs/concepts/databases/postgres.md +++ b/docs/concepts/databases/postgres.md @@ -19,6 +19,7 @@ section_menu_id: concepts `Postgres` is a Kubernetes `Custom Resource Definitions` (CRD). It provides declarative configuration for [PostgreSQL](https://www.postgresql.org/) in a Kubernetes native way. You only need to describe the desired database configuration in a Postgres object, and the KubeDB operator will create Kubernetes objects in the desired state for you. ## Postgres Spec + As with all other Kubernetes objects, a Postgres needs `apiVersion`, `kind`, and `metadata` fields. It also needs a `.spec` section. Below is an example Postgres object. @@ -78,16 +79,22 @@ spec: ``` ### spec.version + `spec.version` is a required field specifying the version of PostgreSQL database. Currently the supported versions are: + - `9.6.7`, `9.6` + - `10.2` ### spec.replicas + `spec.replicas` specifies the total number of primary and standby nodes in Postgres database cluster configuration. One pod is selected as Primary and others are acted as standby replicas. ### spec.standby + `spec.standby` is an optional field that specifies standby mode (_warm/hot_) supported by Postgres. **Hot standby** can run read-only queries where **Warm standby** can't accept connect and only used for replication purpose. ### spec.archiver + `spec.archiver` is an optional field which specifies storage information that will be used by `wal-g`. - `spec.archiver.storage.storageSecretName` points to the Secret containing the credentials for cloud storage destination. @@ -96,6 +103,7 @@ spec: Continuous archiving data will be stored in a folder called `{bucket}/{prefix}/kubedb/{namespace}/{postgres-name}/archive/`. ### spec.databaseSecret + `spec.databaseSecret` is an optional field that points to a Secret used to hold credentials for `postgres` super user. If not set, KubeDB operator creates a new Secret `{postgres-name}-auth` for storing the password for `postgres` superuser for each Postgres object. If you want to use an existing secret please specify that when creating the Postgres object using `spec.databaseSecret.secretName`. @@ -103,6 +111,7 @@ If you want to use an existing secret please specify that when creating the Post This Secret contains `postgres` superuser password as `POSTGRES_PASSWORD` key. ### spec.storage + `spec.storage` is an optional field that specifies the StorageClass of PVCs dynamically allocated to store data for the database. This storage spec will be passed to the StatefulSet created by KubeDB operator to run database pods. You can specify any StorageClass available in your cluster with appropriate resource requests. If no storage spec is given, an `emptyDir` is used. - `spec.storage.storageClassName` is the name of the StorageClass used to provision PVCs. PVCs don’t necessarily have to request a class. A PVC with its storageClassName set equal to "" is always interpreted to be requesting a PV with no class, so it can only be bound to PVs with no class (no annotation or one set equal to ""). A PVC with no storageClassName is not quite the same and is treated differently by the cluster depending on whether the DefaultStorageClass admission plugin is turned on. @@ -115,13 +124,16 @@ To learn how to configure `spec.storage`, please visit the links below: - https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims ### spec.nodeSelector + `spec.nodeSelector` is an optional field that specifies a map of key-value pairs. For the pod to be eligible to run on a node, the node must have each of the indicated key-value pairs as labels (it can have additional labels as well). To learn more, see [here](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#nodeselector) . ### spec.init + `spec.init` is an optional section that can be used to initialize a newly created Postgres database. PostgreSQL databases can be initialized in one of three ways: #### Initialize via Script + To initialize a PostgreSQL database using a script (shell script, db migrator, etc.), set the `spec.init.scriptSource` section when creating a Postgres object. ScriptSource must have following information: - [VolumeSource](https://kubernetes.io/docs/concepts/storage/volumes/#types-of-volumes): Where your script is loaded from. @@ -144,8 +156,8 @@ spec: In the above example, Postgres will execute provided script once database is running. `directory: .` is used to get repository contents directly in mount path. - #### Initialize from Snapshots + To initialize from prior Snapshot, set the `spec.init.snapshotSource` section when creating a Postgres object. In this case, SnapshotSource must have following information: - `name:` Name of the Snapshot @@ -172,6 +184,7 @@ When initializing from Snapshot, superuser `postgres` must have to match with pr #### Initialize from WAL archive + To initialize from WAL archive, set the `spec.init.postgresWAL` section when creating a Postgres object. Below is an example showing how to initialize a PostgreSQL database from WAL archive. @@ -199,8 +212,8 @@ In the above example, PostgreSQL database will be initialized from WAL archive. When initializing from WAL archive, superuser `postgres` must have to match with previous one. For example, lets say, we want to initialize this database from `postgres-old` WAL archive. In this case, superuser of new Postgres should use same password as `postgres-old`. Otherwise, restoration process will be failed. - ### spec.backupSchedule + KubeDB supports taking periodic snapshots for Postgres database. This is an optional section in `.spec`. When `spec.backupSchedule` section is added, KubeDB operator immediately takes a backup to validate this information. After that, at each tick kubeDB operator creates a [Snapshot](/docs/concepts/snapshot.md) object. This triggers operator to create a Job to take backup. If used, set the various sub-fields accordingly. - `spec.backupSchedule.cronExpression` is a required [cron expression](https://github.com/robfig/cron/blob/v2/doc.go#L26). This specifies the schedule for backup operations. @@ -211,18 +224,19 @@ KubeDB supports taking periodic snapshots for Postgres database. This is an opti ### spec.doNotPause -`spec.doNotPause` is an optional field that tells KubeDB operator that if this Postgres object is deleted, whether it should be reverted automatically. This should be set to `true` for production databases to avoid accidental deletion. If not set or set to false, deleting a Postgres object put the database into a dormant state. THe StatefulSet for a DormantDatabase is deleted but the underlying PVCs are left intact. This allows user to resume the database later. +KubeDB takes advantage of `ValidationWebhook` feature in Kubernetes 1.9.0 or later clusters to implement `doNotPause` feature. If admission webhook is enabled, It prevents user from deleting the database as long as the `spec.doNotPause` is set `true`. If not set or set to false, deleting a Postgres object put the database into a dormant state. THe StatefulSet for a DormantDatabase is deleted but the underlying PVCs are left intact. This allows user to resume the database later. ### spec.monitor -To learn how to monitor Postgres databases, please visit [here](/docs/concepts/monitoring.md). +To learn how to monitor Postgres databases, please visit [here](/docs/concepts/monitoring.md). ### spec.resources -`spec.resources` is an optional field. This can be used to request compute resources required by the database pods. To learn more, visit [here](http://kubernetes.io/docs/user-guide/compute-resources/). +`spec.resources` is an optional field. This can be used to request compute resources required by the database pods. To learn more, visit [here](http://kubernetes.io/docs/user-guide/compute-resources/). ## Next Steps + - Learn how to use KubeDB to run a PostgreSQL database [here](/docs/guides/postgres/quickstart/quickstart.md). - See the list of supported storage providers for snapshots [here](/docs/concepts/snapshot.md). - Thinking about monitoring your database? KubeDB works [out-of-the-box with Prometheus](/docs/guides/monitoring.md).