Merge pull request #31 from spotahome/devops-695-improve-documentation

[DEVOPS-695] improve documentation
spotahome · Feb 20, 2018 · 431e8a5 · 431e8a5
2 parents 968ad79 + e74320a
commit 431e8a5
Show file tree

Hide file tree

Showing 7 changed files with 167 additions and 134 deletions.
diff --git a/README.md b/README.md
@@ -1,131 +1,74 @@
-# redis-operator [![Build Status](https://travis-ci.org/spotahome/redis-operator.png)](https://travis-ci.org/spotahome/redis-operator) [![Go Report Card](http://goreportcard.com/badge/spotahome/redis-operator)](http://goreportcard.com/report/spotahome/redis-operator)
-Redis Operator creates/configures/manages redis failovers atop Kubernetes.
+# redis-operator
+[![Build Status](https://travis-ci.org/spotahome/redis-operator.png)](https://travis-ci.org/spotahome/redis-operator)
+[![Go Report Card](http://goreportcard.com/badge/spotahome/redis-operator)](http://goreportcard.com/report/spotahome/redis-operator)
+
+**NOTE**: This is an alpha-status project. We do regular tests on the code and functionality, but we can not assure a production-ready stability.
+
+Redis Operator creates/configures/manages redis-failovers atop Kubernetes.
 
 ## Requirements
 Redis Operator is meant to be run on Kubernetes 1.8+.
 All dependecies have been vendored, so there's no need to any additional download.
 
-### Images
-#### Redis Operator
+### Versions deployed
+The image versions deployed by the operator can be found on the [constants file](operator/redisfailover/service/constants.go) for the RedisFailover service.
+
+## Images
+### Redis Operator
 [![Redis Operator Image](https://quay.io/repository/spotahome/redis-operator/status "Redis Operator Image")](https://quay.io/repository/spotahome/redis-operator)
 
 ## Operator deployment on kubernetes
-In order to create Redis failovers inside a Kubernetes cluster, the operator has to be deployed:
-~~~~
-apiVersion: extensions/v1beta1
-kind: Deployment
-metadata:
-  labels:
-    app: redisoperator
-  name: redisoperator
-spec:
-  replicas: 1
-  selector:
-    matchLabels:
-      app: redisoperator
-  strategy:
-    type: RollingUpdate
-  template:
-    metadata:
-      labels:
-        app: redisoperator
-    spec:
-      containers:
-      - image: quay.io/spotahome/redis-operator:0.2.0
-        imagePullPolicy: IfNotPresent
-        name: app
-        resources:
-          limits:
-            cpu: 100m
-            memory: 50Mi
-          requests:
-            cpu: 10m
-            memory: 50Mi
-      restartPolicy: Always
-~~~~
+In order to create Redis failovers inside a Kubernetes cluster, the operator has to be deployed. It can be done with a [deployment](example/operator.yaml) or with the provided [Helm chart](charts/redisoperator).
+
+### Using a Deployment
+To create the operator, you can directly create it with kubectl:
+```
+kubectl create -f https://raw.githubusercontent.com/spotahome/redis-operator/master/example/operator.yaml
+```
+This will create a deployment named `redisoperator`.
+
+### Using the Helm chart
+From the root folder of the project, execute the following:
+```
+helm install --name redisfailover charts/redisfailover
+```
 
 ## Usage
-In order to deploy a new redis-failover inside kubernetes, a specification has to be created. Here is a template:
-~~~~
-apiVersion: storage.spotahome.com/v1alpha2
-kind: RedisFailover
-metadata:
-  name: myredisfailover
-  namespace: mynamespace
-spec:
-  hardAntiAffinity: false  # Optional. Value by default. If true, the pods will not be scheduled on the same node.
-  sentinel:
-    replicas: 3            # Optional. Value by default, can be set higher.
-    resources:             # Optional. If not set, it won't be defined on created reosurces
-      requests:
-        cpu: 100m
-      limits:
-        memory: 100Mi
-  redis:
-    replicas: 3            # Optional. Value by default, can be set higher.
-    resources:             # Optional. If not set, it won't be defined on created reosurces
-      requests:
-        cpu: 100m
-      limits:
-        memory: 100Mi
-    exporter: false        # Optional. False by default. Adds a redis-exporter container to export metrics.
-~~~~
-
-## Creation pipeline
-The redis-operator creates a redis failover, with all the needed pieces. It does this in two separated steps:
-* Ensure: checks that all the pieces needed are created.
-    * Redis statefulset
-    * Sentinel Deployment
-    * Sentinel service
-    * Redis service (if exporter enabled)
-* Check & Heal: checks that the failover is working and configured as spected.
-    * Number of redis is equal as the set on the RF spec
-    * Number of sentinel is equal as the set on the RF spec
-    * Only one redis working as a master
-    * All redis slaves have the same master
-    * All redis slaves are connected to the master
-    * All sentinels points to the same redis master
-    * Sentinel has not death nodes
-    * Sentinel knows the correct slave number
-
-## Code folder structure
-* api: definition of the RedisFailover CRD.
-* client: autogenerated client to interact with redis-failovers.
-* cmd: contains the starting point of the application.
-* log: wrapper of logrus, created to be able to mock it.
-* metrics: exposer of status of the failovers created.
-* mocks: contains the mocked interfaces for testing the application.
-* operator: the main logic. Manages the requests from k8s and creates/updates/deletes the pieces as needed.
-* service: services/clients to interact with k8s and redises.
-* vendor: vendored packages used by the application.
-
-## Non-code folder structure
-* charts: helm chart to deploy the TPR.
-* docker: Dockerfiles to generate redis-failover docker images.
-* example: yaml files with spec of redis-failover.
-* hack: scripts to generate the client.
-* scripts: scripts used to build and run the app.
-
-## Development
-### With Make
-You can do the following commands with make:
-* Build the development container.
-`make docker-build`
-* Generate mocks.
-`make go-generate`
-* Generate client
-`make update-codegen`
-* Run tests.
-`make test`
-* Build the executable file.
-`make build`
-* Run the app.
-`make run`
-* Access the docker instance with a shell.
-`make shell`
-* Install dependencies
-`make get-deps`
-* Update dependencies
-`make update-deps`
-* Build the app image.
-`make image`
+Once the operator is deployed inside a Kubernetes cluster, a new API will be accesible, so you'll be able to create, update and delete redisfailovers.
+
+In order to deploy a new redis-failover a [specification](example/redisfailover.yaml) has to be created:
+```
+kubectl create -f https://raw.githubusercontent.com/spotahome/redis-operator/master/example/redisfailover.yaml
+```
+
+This redis-failover will be managed by the operator, resulting in the following elements created inside Kubernetes:
+* `rfr-<NAME>`: Redis configmap
+* `rfr-<NAME>`: Redis statefulset
+* `rfr-<NAME>`: Redis service (if redis-exporter is enabled)
+* `rfs-<NAME>`: Sentinel configmap
+* `rfs-<NAME>`: Sentinel deployment
+* `rfs-<NAME>`: Sentinel service
+
+**NOTE**: `NAME` is the named provided when creating the RedisFailover.
+
+### Connection
+In order to connect to the redis-failover and use it, a [Sentinel-ready](https://redis.io/topics/sentinel-clients) library has to be used. This will connect through the Sentinel service to the Redis node working as a master.
+The connection parameters are the following:
+```
+url: rfs-<NAME>
+port: 26379
+master-name: mymaster
+```
+
+## Cleanup
+If you want to delete the operator from your Kubernetes cluster, the operator deployment should be deleted.
+
+Also, the CRD has to be deleted too:
+```
+kubectl delete crd redisfailovers.storage.spotahome.com
+```
+
+## Documentation
+For the code documentation, you can lookup on the [GoDoc](https://godoc.org/github.com/spotahome/redis-operator).
+
+Also, you can check more deeply information on the [docs folder](docs).
diff --git a/docs/development.md b/docs/development.md
@@ -0,0 +1,43 @@
+# Development
+
+## Folder structure
+### Code folder structure
+* **api**: definition of the RedisFailover CRD.
+* **client**: autogenerated client to interact with redis-failovers.
+* **cmd**: contains the starting point of the application.
+* **log**: wrapper of logrus, created to be able to mock it.
+* **metrics**: exposer of status of the failovers created.
+* **mocks**: contains the mocked interfaces for testing the application.
+* **operator**: the main logic. Manages the requests from k8s and creates/updates/deletes the pieces as needed.
+* **service**: services/clients to interact with k8s and redises.
+* **vendor**: vendored packages used by the application.
+
+### Non-code folder structure
+* **charts**: helm chart to deploy the operator.
+* **docker**: Dockerfiles to generate redis-failover docker images.
+* **example**: yaml files with spec of redis-failover.
+* **hack**: scripts to generate the redis-failover api-client.
+* **scripts**: scripts used to build and run the app.
+
+## Make development commands
+You can do the following commands with make:
+* Build the development container.
+`make docker-build`
+* Generate mocks.
+`make go-generate`
+* Generate client
+`make update-codegen`
+* Run tests.
+`make test`
+* Build the executable file.
+`make build`
+* Run the app.
+`make run`
+* Access the docker instance with a shell.
+`make shell`
+* Install dependencies
+`make get-deps`
+* Update dependencies
+`make update-deps`
+* Build the app image.
+`make image`
diff --git a/docs/logic.md b/docs/logic.md
@@ -0,0 +1,22 @@
+# Controller logic
+
+## Creation pipeline
+The Redis-Operator creates Redis Failovers, with all the needed pieces. So, when a event arrives from Kubernetes (add or sync), the following steps are executed:
+* Ensure: checks that all the pieces needed are created. It is important to notice that if a change is performed manually on the objects created, the operator will override them. This is done to ensure a healthy status. It will create the following:
+    * Redis configmap
+    * Redis statefulset
+    * Redis service (if exporter enabled)
+    * Sentinel configmap
+    * Sentinel deployment
+    * Sentinel service
+* Check & Heal: will connect to every Redis and Sentinel and will ensure that they are working as they are supposed to do. If this is not the case, it will reconfigure the nodes to move them to the desire state. It will check the following:
+    * Number of Redis is equal as the set on the RF spec
+    * Number of Sentinel is equal as the set on the RF spec
+    * Only one Redis working as a master
+    * All Redis slaves have the same master
+    * All Redis slaves are connected to the master
+    * All Sentinels points to the same Redis master
+    * Sentinel has not death nodes
+    * Sentinel knows the correct slave number
+
+Most of the problems that may occur will be treated and tried to fix by the controller, except the case that there are a [split-brain](https://en.wikipedia.org/wiki/Split-brain_(computing)). **If happens to be a split-brain, an error will be logged waiting for manual fix**.
diff --git a/example/minimum.yaml b/example/minimum.yaml
@@ -1,5 +1,4 @@
 apiVersion: storage.spotahome.com/v1alpha2
 kind: RedisFailover
 metadata:
-  name: rfexample
-  namespace: example
+  name: redisfailover
diff --git a/example/namespace.yaml b/example/namespace.yaml
diff --git a/example/operator.yaml b/example/operator.yaml
@@ -0,0 +1,30 @@
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+  labels:
+    app: redisoperator
+  name: redisoperator
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: redisoperator
+  strategy:
+    type: RollingUpdate
+  template:
+    metadata:
+      labels:
+        app: redisoperator
+    spec:
+      containers:
+      - image: quay.io/spotahome/redis-operator:0.2.0
+        imagePullPolicy: IfNotPresent
+        name: app
+        resources:
+          limits:
+            cpu: 100m
+            memory: 50Mi
+          requests:
+            cpu: 10m
+            memory: 50Mi
+      restartPolicy: Always
diff --git a/example/redisfailover.yaml b/example/redisfailover.yaml
@@ -1,23 +1,23 @@
 apiVersion: storage.spotahome.com/v1alpha2
 kind: RedisFailover
 metadata:
-  name: rfexample
-  namespace: example
+  name: redisfailover
 spec:
+  hardAntiAffinity: false  # Optional. Value by default. If true, the pods will not be scheduled on the same node.
   sentinel:
-    replicas: 3
-    resources:
+    replicas: 3            # Optional. 3 by default, can be set higher.
+    resources:             # Optional. If not set, it won't be defined on created reosurces.
       requests:
         cpu: 100m
       limits:
         memory: 100Mi
   redis:
-    replicas: 3
-    resources:
+    replicas: 3            # Optional. 3 by default, can be set higher.
+    resources:             # Optional. If not set, it won't be defined on created reosurces
       requests:
         cpu: 100m
         memory: 100Mi
       limits:
         cpu: 400m
         memory: 500Mi
-    exporter: false
+    exporter: false         # Optional. False by default. Adds a redis-exporter container to export metrics.