Concept doc updated for Postgres replicaservicetemplate and LeaderEle…

…ction (#398) Fixes https://github.com/kubedb/project/issues/131
kubedb · Feb 20, 2019 · d725366 · d725366
1 parent c9e6eee
commit d725366
Show file tree

Hide file tree

Showing 17 changed files with 81 additions and 32 deletions.
diff --git a/chart/kubedb/README.md b/chart/kubedb/README.md
@@ -45,9 +45,9 @@ The following table lists the configurable parameters of the KubeDB chart and th
 |                Parameter                |                                                                                Description                                                                                 |                          Default                          |
 | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
 | `replicaCount`                          | Number of kubedb operator replicas to create (only 1 is supported)                                                                                                         | `1`                                                       |
-| `kubedb.registry`                       | Docker registry used to pull Kubedb operator image                                                                                                                         | `kubedb`                                                  |
-| `kubedb.repository`                     | Kubedb operator container image                                                                                                                                            | `operator`                                                |
-| `kubedb.tag`                            | Kubedb operator container image tag                                                                                                                                        | `0.9.0`                                                   |
+| `kubedb.registry`                       | Docker registry used to pull KubeDB operator image                                                                                                                         | `kubedb`                                                  |
+| `kubedb.repository`                     | KubeDB operator container image                                                                                                                                            | `operator`                                                |
+| `kubedb.tag`                            | KubeDB operator container image tag                                                                                                                                        | `0.9.0`                                                   |
 | `cleaner.registry`                      | Docker registry used to pull Webhook cleaner image                                                                                                                         | `appscode`                                                |
 | `cleaner.repository`                    | Webhook cleaner container image                                                                                                                                            | `kubectl`                                                 |
 | `cleaner.tag`                           | Webhook cleaner container image tag                                                                                                                                        | `v1.12`                                                   |

diff --git a/chart/kubedb/values.yaml b/chart/kubedb/values.yaml
@@ -3,7 +3,7 @@
 ##
 # Declare variables to be passed into your templates.
 replicaCount: 1
-# Docker registry containing Kubedb images
+# Docker registry containing KubeDB images
 kubedb:
   registry: kubedb
   repository: operator

diff --git a/cmd/kubedb/main.go b/cmd/kubedb/main.go
@@ -8,7 +8,7 @@ import (
 )
 
 func main() {
-	cmd := cmds.NewKubedbCommand(os.Stdin, os.Stdout, os.Stderr)
+	cmd := cmds.NewKubeDBCommand(os.Stdin, os.Stdout, os.Stderr)
 	if err := cmd.Execute(); err != nil {
 		os.Exit(1)
 	}

diff --git a/docs/concepts/databases/elasticsearch.md b/docs/concepts/databases/elasticsearch.md
@@ -363,8 +363,8 @@ A list of the supported environment variables, their permission to use in KubeDB
 | ------------------------------- | :---------------: | -------------------------------------------------------------------------------------------------- |
 | CLUSTER_NAME                    |     `allowed`     | `metadata.name`                                                                                    |
 | NODE_NAME                       |   `not allowed`   | Pod name                                                                                           |
-| NODE_MASTER                     |   `not allowed`   | Kubedb set it based on `Elasticsearch` crd sepcification                                           |
-| NODE_DATA                       |   `not allowed`   | Kubedb set it based on `Elasticsearch` crd sepcification                                           |
+| NODE_MASTER                     |   `not allowed`   | KubeDB sets it based on `Elasticsearch` crd sepcification                                           |
+| NODE_DATA                       |   `not allowed`   | KubeDB sets it based on `Elasticsearch` crd sepcification                                           |
 | NETWORK_HOST                    |     `allowed`     | `_site_`                                                                                           |
 | HTTP_ENABLE                     |     `allowed`     | If `spec.topology` is not specified then `true`. Otherwise, `false` for Master node and Data node. |
 | HTTP_CORS_ENABLE                |     `allowed`     | `true`                                                                                             |

diff --git a/docs/concepts/databases/memcached.md b/docs/concepts/databases/memcached.md
@@ -137,7 +137,7 @@ Uses of some field of `spec.podTemplate` is described below,
 
 `spec.env` is an optional field that specifies the environment variables to pass to the Memcached docker image.
 
-Note that, Kubedb does not allow to update the environment variables. If you try to update environment variables, Kubedb operator will reject the request with following error,
+Note that, KubeDB does not allow to update the environment variables. If you try to update environment variables, KubeDB operator will reject the request with following error,
 
 ```ini
 Error from server (BadRequest): error when applying patch:

diff --git a/docs/concepts/databases/mongodb.md b/docs/concepts/databases/mongodb.md
@@ -306,15 +306,15 @@ Uses of some field of `spec.podTemplate` is described below,
 
 `spec.podTemplate.spec.env` is an optional field that specifies the environment variables to pass to the MongoDB docker image. To know about supported environment variables, please visit [here](https://hub.docker.com/r/_/mongo/).
 
-Note that, Kubedb does not allow `MONGO_INITDB_ROOT_USERNAME` and `MONGO_INITDB_ROOT_PASSWORD` environment variables to set in `spec.podTemplate.spec.env`. If you want to use custom superuser and password, please use `spec.databaseSecret` instead described earlier.
+Note that, KubeDB does not allow `MONGO_INITDB_ROOT_USERNAME` and `MONGO_INITDB_ROOT_PASSWORD` environment variables to set in `spec.podTemplate.spec.env`. If you want to use custom superuser and password, please use `spec.databaseSecret` instead described earlier.
 
 If you try to set `MONGO_INITDB_ROOT_USERNAME` or `MONGO_INITDB_ROOT_PASSWORD` environment variable in MongoDB crd, Kubed operator will reject the request with following error,
 
 ```ini
 Error from server (Forbidden): error when creating "./mongodb.yaml": admission webhook "mongodb.validators.kubedb.com" denied the request: environment variable MONGO_INITDB_ROOT_USERNAME is forbidden to use in MongoDB spec
 ```
 
-Also, note that Kubedb does not allow to update the environment variables as updating them does not have any effect once the database is created.  If you try to update environment variables, Kubedb operator will reject the request with following error,
+Also, note that KubeDB does not allow to update the environment variables as updating them does not have any effect once the database is created.  If you try to update environment variables, KubeDB operator will reject the request with following error,
 
 ```ini
 Error from server (BadRequest): error when applying patch:

diff --git a/docs/concepts/databases/mysql.md b/docs/concepts/databases/mysql.md
@@ -284,15 +284,15 @@ Uses of some field of `spec.podTemplate` is described below,
 
 `spec.podTemplate.spec.env` is an optional field that specifies the environment variables to pass to the MySQL docker image. To know about supported environment variables, please visit [here](https://hub.docker.com/_/mysql/).
 
-Note that, Kubedb does not allow `MYSQL_ROOT_PASSWORD`, `MYSQL_ALLOW_EMPTY_PASSWORD`, `MYSQL_RANDOM_ROOT_PASSWORD`, and `MYSQL_ONETIME_PASSWORD` environment variables to set in `spec.env`. If you want to set the root password, please use `spec.databaseSecret` instead described earlier.
+Note that, KubeDB does not allow `MYSQL_ROOT_PASSWORD`, `MYSQL_ALLOW_EMPTY_PASSWORD`, `MYSQL_RANDOM_ROOT_PASSWORD`, and `MYSQL_ONETIME_PASSWORD` environment variables to set in `spec.env`. If you want to set the root password, please use `spec.databaseSecret` instead described earlier.
 
 If you try to set any of the forbidden environment variables i.e. `MYSQL_ROOT_PASSWORD` in MySQL crd, Kubed operator will reject the request with following error,
 
 ```ini
 Error from server (Forbidden): error when creating "./mysql.yaml": admission webhook "mysql.validators.kubedb.com" denied the request: environment variable MYSQL_ROOT_PASSWORD is forbidden to use in MySQL spec
 ```
 
-Also note that Kubedb does not allow to update the environment variables as updating them does not have any effect once the database is created.  If you try to update environment variables, Kubedb operator will reject the request with following error,
+Also note that KubeDB does not allow to update the environment variables as updating them does not have any effect once the database is created.  If you try to update environment variables, KubeDB operator will reject the request with following error,
 
 ```ini
 Error from server (BadRequest): error when applying patch:

diff --git a/docs/concepts/databases/postgres.md b/docs/concepts/databases/postgres.md
@@ -35,6 +35,10 @@ spec:
   replicas: 2
   standbyMode: Hot
   streamingMode: asynchronous
+  leaderElection:
+    leaseDurationSeconds: 3
+    renewDeadlineSeconds: 2
+    retryPeriodSeconds: 1
   archiver:
     storage:
       storageSecretName: s3-secret
@@ -101,6 +105,15 @@ spec:
       - name:  http
         port:  5432
         targetPort: http
+  replicaServiceTemplate:
+    annotations:
+      passMe: ToReplicaService
+    spec:
+      type: NodePort
+      ports:
+      - name:  http
+        port:  5432
+        targetPort: http
   updateStrategy:
     type: RollingUpdate
   terminationPolicy: "DoNotTerminate"
@@ -127,6 +140,16 @@ spec:
 
 `spec.streamingMode` is an optional field that specifies the streaming mode (_synchronous / asynchronous_) of the standby replicas. KubeDB currently supports only **asynchronous** streaming mode.
 
+### spec.leaderElection
+
+There are three fields under Postgres CRD's `spec.leaderElection`. These values defines how fast the leader election can happen.
+
+- `leaseDurationSeconds`: This is the duration in seconds that non-leader candidates will wait to force acquire leadership. This is measured against time of last observed ack. Default 15 sec.
+- `renewDeadlineSeconds`: This is the duration in seconds that the acting master will retry refreshing leadership before giving up. Normally, LeaseDuration * 2 / 3. Default 10 sec.
+- `retryPeriodSeconds`: This is the duration in seconds the LeaderElector clients should wait between tries of actions. Normally, LeaseDuration / 3. Default 2 sec.
+
+If the Cluster machine is powerful, user can reduce the times. But, Do not make it so little, in that case Postgres will restarts very often.
+
 ### spec.archiver
 
 `spec.archiver` is an optional field which specifies storage information that will be used by `wal-g`. User can use either s3 or gcs.
@@ -195,7 +218,7 @@ To learn how to configure `spec.storage`, please visit the links below:
   1. Initialize from Script
   2. Initialize from Snapshot
   3. Initialize from WAL archive
-  
+
 #### 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 the following information:
@@ -396,7 +419,11 @@ At least one of the following was changed:
 
 ### spec.serviceTemplate
 
-You can also provide a template for the services created by KubeDB operator for Postgres database through `spec.serviceTemplate`. This will allow you to set the type and other properties of the services.
+KubeDB creates two different services for each Postgres instance. One of them is a master service named `<postgres-name>` and points to the Postgres `Primary` pod/node. Another one is a replica service named `<postgres-name>-replicas` and points to Postgres `replica` pods/nodes.
+
+These `master` and `replica` services can be customized using [spec.serviceTemplate](#spec.servicetemplate) and [spec.replicaServiceTemplate](#specreplicaservicetemplate) respectively.
+
+You can provide template for the `master` service using `spec.serviceTemplate`. This will allow you to set the type and other properties of the service. If `spec.serviceTemplate` is not provided, KubeDB will create a `master` service of type `ClusterIP` with minimal settings.
 
 KubeDB allows following fields to set in `spec.serviceTemplate`:
 
@@ -412,6 +439,28 @@ KubeDB allows following fields to set in `spec.serviceTemplate`:
   - externalTrafficPolicy
   - healthCheckNodePort
 
+See [official v1.13 API documentation](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#servicespec-v1-core) to understand these fields in detail.
+
+### spec.replicaServiceTemplate
+
+You can provide template for the `replica` service using `spec.replicaServiceTemplate`. If `spec.replicaServiceTemplate` is not provided, KubeDB will create a `replica` service of type `ClusterIP` with minimal settings.
+
+The fileds of `spec.replicaServiceTemplate` is similar to `spec.serviceTemplate`, that is:
+
+- metadata:
+  - annotations
+- spec:
+  - type
+  - ports
+  - clusterIP
+  - externalIPs
+  - loadBalancerIP
+  - loadBalancerSourceRanges
+  - externalTrafficPolicy
+  - healthCheckNodePort
+
+See [official v1.13 API documentation](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#servicespec-v1-core) to understand these fields in detail.
+
 ### spec.updateStrategy
 
 You can specify [update strategy](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#update-strategies) of StatefulSet created by KubeDB for Postgres database thorough `spec.updateStrategy` field. The default value of this field is `RollingUpdate`. In future, we will use this field to determine how automatic migration from old KubeDB version to new one should behave.

diff --git a/docs/concepts/databases/redis.md b/docs/concepts/databases/redis.md
@@ -150,7 +150,7 @@ Uses of some field of `spec.podTemplate` is described below,
 
 `spec.podTemplate.spec.env` is an optional field that specifies the environment variables to pass to the Redis docker image.
 
-Note that, Kubedb does not allow to update the environment variables. If you try to update environment variables, Kubedb operator will reject the request with following error,
+Note that, KubeDB does not allow to update the environment variables. If you try to update environment variables, KubeDB operator will reject the request with following error,
 
 ```ini
 Error from server (BadRequest): error when applying patch:

diff --git a/docs/guides/postgres/clustering/streaming_replication.md b/docs/guides/postgres/clustering/streaming_replication.md
@@ -228,13 +228,13 @@ status:
   phase: Running
 ```
 
-There are three fields in Postgres CRD's `spec.LeaderElection`. These values defines how fast the leader election can happen.
+There are three fields under Postgres CRD's `spec.leaderElection`. These values defines how fast the leader election can happen.
 
-- leaseDurationSeconds: LeaseDuration is the duration in second that non-leader candidates will wait to force acquire leadership. This is measured against time of last observed ack. Default 15
-- renewDeadlineSeconds: RenewDeadline is the duration in second that the acting master will retry refreshing leadership before giving up. Normally, LeaseDuration * 2 / 3. Default 10
-- retryPeriodSeconds: RetryPeriod is the duration in second the LeaderElector clients should wait between tries of actions. Normally, LeaseDuration / 3. Default 2
+- leaseDurationSeconds: This is the duration in seconds that non-leader candidates will wait to force acquire leadership. This is measured against time of last observed ack. Default 15 secs.
+- renewDeadlineSeconds: This is the duration in seconds that the acting master will retry refreshing leadership before giving up. Normally, LeaseDuration * 2 / 3. Default 10 secs.
+- retryPeriodSeconds: This is the duration in seconds the LeaderElector clients should wait between tries of actions. Normally, LeaseDuration / 3. Default 2 secs.
 
-If the Cluster machine is powerful, user can reduce the times. But, Do not make it so little, in that case Postgres will restarts very often. 
+If the Cluster machine is powerful, user can reduce the times. But, Do not make it so little, in that case Postgres will restarts very often.
 
 ### Automatic failover
 

diff --git a/docs/guides/postgres/quickstart/quickstart.md b/docs/guides/postgres/quickstart/quickstart.md
@@ -138,7 +138,7 @@ Here,
 Let's create Postgres crd,
 
 ```console
-$ kubectl create -f https://raw.githubusercontent.com/kubedb/cli/doc-upd-mrf/docs/examples/postgres/quickstart/quick-postgres.yaml
+$ kubectl create -f https://raw.githubusercontent.com/kubedb/cli/0.9.0/docs/examples/postgres/quickstart/quick-postgres.yaml
 postgres.kubedb.com/quick-postgres created
 ```
 
@@ -427,7 +427,7 @@ In this tutorial, the DormantDatabase `quick-postgres` can be resumed by creatin
 Let's create the original Postgres object,
 
 ```console
-$ kubectl create -f https://raw.githubusercontent.com/kubedb/cli/doc-upd-mrf/docs/examples/postgres/quickstart/quick-postgres.yaml
+$ kubectl create -f https://raw.githubusercontent.com/kubedb/cli/0.9.0/docs/examples/postgres/quickstart/quick-postgres.yaml
 postgres.kubedb.com/quick-postgres created
 ```
 
@@ -436,7 +436,7 @@ This will resume the previous database. All data that was inserted in previous d
 When the database is resumed, respective DormantDatabase object will be removed. Verify that the DormantDatabase object has been removed,
 
 ```console
-$ kubectl create -f https://raw.githubusercontent.com/kubedb/cli/doc-upd-mrf/docs/examples/postgres/quickstart/quick-postgres.yaml
+$ kubectl create -f https://raw.githubusercontent.com/kubedb/cli/0.9.0/docs/examples/postgres/quickstart/quick-postgres.yaml
 postgres "quick-postgres" created
 ```
 

diff --git a/docs/guides/postgres/quickstart/rbac.md b/docs/guides/postgres/quickstart/rbac.md
@@ -65,7 +65,7 @@ spec:
 Create above Postgres object with following command
 
 ```console
-$ kubectl create -f https://raw.githubusercontent.com/kubedb/cli/doc-upd-mrf/docs/examples/postgres/quickstart/quick-postgres.yaml
+$ kubectl create -f https://raw.githubusercontent.com/kubedb/cli/0.9.0/docs/examples/postgres/quickstart/quick-postgres.yaml
 postgres.kubedb.com/quick-postgres created
 ```
 

diff --git a/docs/guides/postgres/upgrade-manual.md b/docs/guides/postgres/upgrade-manual.md
@@ -76,7 +76,7 @@ metadata:
   name: scheduled-pg
   namespace: demo
 spec:
-  version: "9.6-v2"
+  version: "9.6-v1"
   replicas: 3
   standbyMode: Hot
   storage:
@@ -342,8 +342,8 @@ exit
 For helm, `upgrade` command works fine.
 
 ```console
-$ helm upgrade --install kubedb-operator appscode/kubedb --version 0.10.0
-$ helm install appscode/kubedb-catalog --name kubedb-catalog --version 0.10.0 --namespace default
+$ helm upgrade --install kubedb-operator appscode/kubedb --version 0.10.0 --namespace kube-system
+$ helm upgrade --install kubedb-catalog appscode/kubedb-catalog --version 0.10.0 --namespace kube-system
 
 $ helm ls
 NAME           	REVISION	UPDATED                 	STATUS  	CHART               	APP VERSION	NAMESPACE