Updated Redis doc for 0.9.0

docs/concepts/catalog/redis.md

@@ -0,0 +1,73 @@
+---
+title: RedisVersion
+menu:
+  docs_0.8.0:
+    identifier: redis-version
+    name: RedisVersion
+    parent: catalog
+    weight: 30
+menu_name: docs_0.8.0
+section_menu_id: concepts
+---
+
+# RedisVersion
+
+## What is RedisVersion
+
+`RedisVersion` is a Kubernetes `Custom Resource Definitions` (CRD). It provides a declarative configuration to specify the docker images to be used for [Redis](https://redis.io/) database deployed with KubeDB in Kubernetes native way.
+
+When you install KubeDB, `RedisVersion` crd will be created automatically for every supported Redis versions. You have to specify the name of `RedisVersion` crd in `spec.version` field of [Redis](/docs/concepts/databases/redis.md) crd. Then, KubeDB will use the docker images specified in the `RedisVersion` crd to create your expected database.
+
+Using a separate crd for specifying respective docker images allows us to modify the images independent of KubeDB operator. This will also allow the users to use a custom image for the database.
+
+## RedisVersion Specification
+
+As with all other Kubernetes objects, a RedisVersion needs `apiVersion`, `kind`, and `metadata` fields. It also needs a `.spec` section.
+
+```yaml
+apiVersion: catalog.kubedb.com/v1alpha1
+kind: RedisVersion
+metadata:
+  name: "4.0-v1"
+  labels:
+    app: kubedb
+spec:
+  version: "4.0"
+  db:
+    image: "${KUBEDB_DOCKER_REGISTRY}/redis:4.0-v1"
+  exporter:
+    image: "${KUBEDB_DOCKER_REGISTRY}/redis_exporter:v0.21.1"
+```
+
+### metadata.name
+
+`metadata.name` is a required field that specify the name of the `RedisVersion` crd. You have to specify this name in `spec.version` field of [Redis](/docs/concepts/databases/redis.md) crd.
+
+We follow this convention for naming RedisVersion crd:
+
+- Name format: `{Original PosgreSQL image verion}-{modification tag}`
+
+We modify original Redis docker image to support Redis clustering and re-tag the image with v1,v2 etc. modification tag. An image with higher modification tag will have more feature than the images with lower modification tag. Hence, it is recommended to use RedisVersion crd with highest modification tag to enjoy the latest features.
+
+### spec.version
+
+`spec.version` is a required field that specifies the original version of Redis database that has been used to build the docker image specified in `spec.db.image` field.
+
+### spec.deprecated
+
+`spec.deprecated` is an optional field that specifies whether the docker images specified here is supported by the current KubeDB operator.
+
+The default value of this field is `false`. If `spec.depcrecated` is set to `true`, KubeDB operator will skip processing this CRD object and will add a event to the CRD object specifying that the DB version is deprecated.
+
+### spec.db.image
+
+`spec.db.image` is a required field that specifies the docker image which will be used to create Statefulset by KubeDB operator to create expected Redis database.
+
+### spec.exporter.image
+
+`spec.exporter.image` is required field that specifies the image which will be used to export Prometheus metrics.
+
+## Next Steps
+
+- Learn about Redis crd [here](/docs/concepts/databases/redis.md).
+- Deploy your first Redis database with KubeDB by following the guide [here](/docs/guides/redis/quickstart/quickstart.md).

docs/concepts/databases/redis.md

@@ -37,38 +37,63 @@ spec:
     resources:
       requests:
         storage: 50Mi
-  nodeSelector:
-    disktype: ssd
-  doNotPause: true
-  configSource:
-      configMap:
-        name: rd-custom-config
-  env:
-    - name:  MY_ENV
-      value: "env-example"
   monitor:
-    agent: coreos-prometheus-operator
+    agent: prometheus.io/coreos-operator
     prometheus:
       namespace: demo
       labels:
         app: kubedb
       interval: 10s
-  resources:
-    requests:
-      memory: "64Mi"
-      cpu: "250m"
-    limits:
-      memory: "128Mi"
-      cpu: "500m"
+  configSource:
+    configMap:
+      name: rd-custom-config
+  podTemplate:
+    annotation:
+      passMe: ToDatabasePod
+    controller:
+      annotation:
+        passMe: ToStatefulSet
+    spec:
+      schedulerName: my-scheduler
+      nodeSelector:
+        disktype: ssd
+      imagePullSecrets:
+      - name: myregistrykey
+      args:
+      - "--loglevel verbose"
+      env:
+      - name: ENV_VARIABLE
+        value: "value"
+      resources:
+        requests:
+          memory: "64Mi"
+          cpu: "250m"
+        limits:
+          memory: "128Mi"
+          cpu: "500m"
+  serviceTemplate:
+    annotation:
+      passMe: ToService
+    spec:
+      type: NodePort
+      ports:
+      - name:  http
+        port:  9200
+        targetPort: http
+  terminationPolicy: Pause
+  updateStrategy:
+    type: RollingUpdate
 ```
 
 ### spec.version
 
-`spec.version` is a required field specifying the version of Redis database. Official [Redis docker images](https://hub.docker.com/r/library/redis/tags/) will be used for the specific version.
+`spec.version` is a required field specifying the name of the [RedisVersion](/docs/concepts/catalog/redis.md) crd where the docker images are specified. Currently, when you install KubeDB, it creates the following `RedisVersion` crd,
+
+- `4.0.6-v1`, `4.0.6`, `4.0-v1`, `4.0`, `4-v1`, `4`
 
 ### spec.storage
 
-Since 0.8.0, `spec.storage` is a required 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.
+Since 0.9.0, If you set `spec.storageType:` to `Durable`, then  `spec.storage` is a required 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.
 
 - `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.
 - `spec.storage.accessModes` uses the same conventions as Kubernetes PVCs when requesting storage with specific access modes.
@@ -78,25 +103,52 @@ To learn how to configure `spec.storage`, please visit the links below:
 
 - https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims
 
-### spec.nodeSelector
+### spec.monitor
 
-`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) .
+Redis managed by KubeDB can be monitored with builtin-Prometheus and CoreOS-Prometheus operator out-of-the-box. To learn more,
 
-### spec.doNotPause
+- [Monitor Redis with builtin Prometheus](/docs/guides/redis/monitoring/using-builtin-prometheus.md)
+- [Monitor Redis with CoreOS Prometheus operator](/docs/guides/redis/monitoring/using-coreos-prometheus-operator.md)
 
-`spec.doNotPause` is an optional field that tells KubeDB operator that if this Redis 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 Redis 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.configSource
 
-### spec.imagePullSecret
+`spec.configSource` is an optional field that allows users to provide custom configuration for Redis. This field accepts a [`VolumeSource`](https://github.com/kubernetes/api/blob/release-1.11/core/v1/types.go#L47). So you can use any kubernetes supported volume source such as `configMap`, `secret`, `azureDisk` etc. To learn more about how to use a custom configuration file see [here](/docs/guides/redis/custom-config/using-custom-config.md).
 
-`KubeDB` provides the flexibility of deploying Redis database from a private Docker registry. To learn how to deploy Redis from a private registry, please visit [here](/docs/guides/redis/private-registry/using-private-registry.md).
+### spec.podTemplate
 
-### spec.configSource
+KubeDB allows providing a template for database pod through `spec.podTemplate`. KubeDB operator will pass the information provided in `spec.podTemplate` to the StatefulSet created for Redis database.
 
-`spec.configSource` is an optional field that allows users to provide custom configuration for Redis. This field accepts a [`VolumeSource`](https://github.com/kubernetes/api/blob/release-1.11/core/v1/types.go#L47). So you can use any kubernetes supported volume source such as `configMap`, `secret`, `azureDisk` etc. To learn more about how to use a custom configuration file see [here](/docs/guides/redis/custom-config/using-custom-config.md).
+KubeDB accept following fields to set in `spec.podTemplate:`
+
+- metadata:
+  - annotations (pod's annotation)
+- controller:
+  - annotations (statefulset's annotation)
+- spec:
+  - args
+  - env
+  - resources
+  - initContainers
+  - imagePullSecrets
+  - nodeSelector
+  - affinity
+  - schedulerName
+  - tolerations
+  - priorityClassName
+  - priority
+  - securityContext
+  - livenessProbe
+  - readinessProbe
+  - lifecycle
 
-### spec.env
+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 Redis docker image.
+#### spec.podTemplate.spec.args
+ `spec.podTemplate.spec.args` is an optional field. This can be used to provide additional arguments to database installation.
+
+### spec.podTemplate.spec.env
+
+`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,
 
@@ -106,26 +158,72 @@ Error from server (BadRequest): error when applying patch:
 for: "./redis.yaml": admission webhook "redis.validators.kubedb.com" denied the request: precondition failed for:
 ...
 At least one of the following was changed:
-	apiVersion
-	kind
-	name
-	namespace
-	spec.version
-	spec.storage
-	spec.nodeSelector
-	spec.env
+apiVersion
+kind
+name
+namespace
+spec.storage
+spec.podTemplate.spec.nodeSelector
+spec.podTemplate.spec.env
 ```
 
-### spec.monitor
+#### spec.podTemplate.spec.imagePullSecret
 
-Redis managed by KubeDB can be monitored with builtin-Prometheus and CoreOS-Prometheus operator out-of-the-box. To learn more,
+`KubeDB` provides the flexibility of deploying Redis database from a private Docker registry. To learn how to deploy Redis from a private registry, please visit [here](/docs/guides/redis/private-registry/using-private-registry.md).
 
-- [Monitor Redis with builtin Prometheus](/docs/guides/redis/monitoring/using-builtin-prometheus.md)
-- [Monitor Redis with CoreOS Prometheus operator](/docs/guides/redis/monitoring/using-coreos-prometheus-operator.md)
+#### spec.podTemplate.spec.nodeSelector
+
+`spec.podTemplate.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.podTemplate.spec.resources
+
+`spec.podTemplate.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.serviceTemplate
+
+You can also provide a template for the services created by KubeDB operator for Redis database through `spec.serviceTemplate`. This will allow you to set the type and other properties of the services.
+
+KubeDB allows following fields to set in `spec.serviceTemplate`:
+
+- metadata:
+  - annotations
+- spec:
+  - type
+  - ports
+  - clusterIP
+  - externalIPs
+  - loadBalancerIP
+  - loadBalancerSourceRanges
+  - externalTrafficPolicy
+  - healthCheckNodePort
+
+### spec.updateStrategy
+
+You can specify [update strategy](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#update-strategies) of StatefulSet created by KubeDB for Redis 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.
+
+### spec.terminationPolicy
+
+`terminationPolicy` gives flexibility whether to `nullify`(reject) the delete operation of `Redis` crd or which resources KubeDB should keep or delete when you delete `Redis` crd. KubeDB provides following four termination policies:
+
+- DoNotTerminate
+- Pause (`Default`)
+- Delete
+- WipeOut
+
+When, `terminationPolicy` is `DoNotTerminate`, KubeDB takes advantage of `ValidationWebhook` feature in Kubernetes 1.9.0 or later clusters to implement `DoNotTerminate` feature. If admission webhook is enabled, `DoNotTerminate` prevents users from deleting the database as long as the `spec.terminationPolicy` is set to `DoNotTerminate`.
+
+Following table show what KubeDB does when you delete Redis crd for different termination policies,
 
-### spec.resources
+|          Behaviour          | DoNotTerminate |  Pause   |  Delete  | WipeOut  |
+| --------------------------- | :------------: | :------: | :------: | :------: |
+| 1. Block Delete operation   |    ✓    | ✗ | ✗ | ✗ |
+| 2. Create Dormant Database  |    ✗    | ✓ | ✗ | ✗ |
+| 3. Delete StatefulSet       |    ✗    | ✓ | ✓ | ✓ |
+| 4. Delete Services          |    ✗    | ✓ | ✓ | ✓ |
+| 5. Delete PVCs              |    ✗    | ✗ | ✓ | ✓ |
+| 6. Delete Secrets           |    ✗    | ✗ | ✗ | ✓ |
 
-`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/).
+If you don't specify `spec.terminationPolicy` KubeDB uses `Pause` termination policy by default.
 
 ## Next Steps
 

docs/examples/redis/cli/redis-demo.yaml

@@ -5,7 +5,7 @@ metadata:
   labels:
     kubedb: cli-demo
 spec:
-  version: "4-v1"
+  version: "4.0-v1"
   storage:
     storageClassName: "standard"
     accessModes:

docs/examples/redis/custom-config/redis-custom.yaml

@@ -4,8 +4,7 @@ metadata:
   name: custom-redis
   namespace: demo
 spec:
-  version: "4-v1"
-  doNotPause: true
+  version: "4.0-v1"
   configSource:
       configMap:
         name: rd-custom-config

docs/examples/redis/monitoring/builtin-prometheus/demo-1.yaml

@@ -4,7 +4,7 @@ metadata:
   name: redis-mon-prometheus
   namespace: demo
 spec:
-  version: "4-v1"
+  version: "4.0-v1"
   storage:
     storageClassName: "standard"
     accessModes:

docs/examples/redis/monitoring/coreos-operator/demo-1.yaml

@@ -4,7 +4,7 @@ metadata:
   name: redis-mon-coreos
   namespace: demo
 spec:
-  version: "4-v1"
+  version: "4.0-v1"
   storage:
     storageClassName: "standard"
     accessModes:

docs/examples/redis/private-registry/demo-2.yaml

@@ -4,14 +4,15 @@ metadata:
   name: redis-pvt-reg
   namespace: demo
 spec:
-  version: "4-v1"
-  doNotPause: true
+  version: "4.0-v1"
   storage:
     storageClassName: "standard"
     accessModes:
     - ReadWriteOnce
     resources:
       requests:
         storage: 50Mi
-  imagePullSecrets:
-    - name: myregistrykey
+  podTemplate:
+    spec:
+      imagePullSecrets:
+      - name: myregistrykey

docs/examples/redis/quickstart/demo-1.yaml

@@ -4,12 +4,13 @@ metadata:
   name: redis-quickstart
   namespace: demo
 spec:
-  version: "4-v1"
-  doNotPause: true
+  version: "4.0-v1"
+  storageType: Durable
   storage:
     storageClassName: "standard"
     accessModes:
     - ReadWriteOnce
     resources:
       requests:
         storage: 50Mi
+  terminationPolicy: DoNotTerminate