Add Restik docs (#15)

README.md

@@ -1,7 +1,46 @@
-[Website](https://appscode.com) • [Slack](https://slack.appscode.com) • [Forum](https://discuss.appscode.com) • [Twitter](https://twitter.com/AppsCodeHQ)
 
-# restik
-Backup your Kubernetes Volumes
 
-## Status
-We are actively working on this project. You can read the proposal here: https://github.com/appscode/restik/issues/1 . If you have any comments give your feedback there.
+## Restik
+ Restik provides support to backup your Kubernetes Volumes
+
+**Feautures**
+ - Support backup for any kubernetes [volumes](https://kubernetes.io/docs/concepts/storage/volumes/).
+## Supported Versions
+Kubernetes 1.5+
+
+## Supported Workloads 
+Restik supports backup of following Workloads
+
+* Replication Controller
+* Replica Set 
+* Deployment
+* Daemon Set
+* Stateful Set
+
+## Installation
+Installation and Upgrade process are described [here](docs/user-guide/install.md)
+
+## How to backup
+
+One can start the backup process by following this [guide](docs/user-guide/backup.md)
+
+## How to recover
+
+The recover process will be left to users for now. It can be done by running `$ /restic -r <restik_repo> restore snapshot_id --target <target_dir>` inside the restic-sidecar container. 
+You can find the details [here](https://restic.readthedocs.io/en/stable/Manual/#restore-a-snapshot) 
+
+## Developer Guide
+Want to learn whats happening under the hood, read [the developer guide](docs/developer-guide/README.md).
+
+## Architectural Design
+If you want to know how Backup Controller is working, read this [doc](docs/developer-guide/design.md).
+
+## Contribution
+If you're interested in being a contributor, read [the contribution guide](docs/contribution/README.md).
+
+## Acknowledgement
+ - Restic https://github.com/restic/restic
+
+## Support
+If you have any questions, you can reach out to us.
+[Website](https://appscode.com) • [Slack](https://slack.appscode.com) • [Forum](https://discuss.appscode.com) • [Twitter](https://twitter.com/AppsCodeHQ)

client/clientset/backup.go

@@ -17,6 +17,8 @@ const (
 	ResourceTypeBackup = "backups"
 )
 
+const GroupName = "appscode.com"
+
 type BackupInterface interface {
 	List(opts api.ListOptions) (*aci.BackupList, error)
 	Get(name string) (*aci.Backup, error)

client/clientset/extensions.go

@@ -75,8 +75,8 @@ func setExtensionsDefaults(config *rest.Config) error {
 		config.UserAgent = rest.DefaultKubernetesUserAgent()
 	}
 
-	if config.GroupVersion == nil || config.GroupVersion.Group != "appscode.com" {
-		g, err := registered.Group("appscode.com")
+	if config.GroupVersion == nil || config.GroupVersion.Group != GroupName {
+		g, err := registered.Group(GroupName)
 		if err != nil {
 			return err
 		}

cmd/restik/main.go

@@ -11,6 +11,7 @@ import (
 	"github.com/appscode/restik/pkg/cmd"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
+	_ "k8s.io/kubernetes/pkg/client/clientset_generated/internalclientset/fake"
 )
 
 func main() {

docs/contribution/README.md

@@ -0,0 +1,28 @@
+# Contributing guidelines
+
+
+## Developer Guide
+
+We have a [Developer's Guide](../developer-guide/README.md) that outlines everything you need to know. If you find something undocumented or incorrect along the way,
+please feel free to send a Pull Request.
+
+## Filing issues
+If you have a question about Restik or have a problem using it, please start with contacting us.
+If that doesn't answer your questions, or if you think you found a bug, please [file an issue](https://github.com/appscode/restik/issues/new).
+
+## Submit PR
+If you fix a bug or developed a new feature feel free to submit a PR.
+
+1. Fork the projects
+1. Add Your changes
+1. Add Test Cases to justify the changes
+1. Run the tests
+1. Build the project
+1. Run e2e tests
+1. Submit PR. And you are go. 
+
+### Adding Dependency
+If your patch Depends on new packagees, add that to vendor with glide.
+
+### Building Restik
+Read [build instruction](../developer-guide/build.md) to build Restik.

docs/developer-guide/README.md

@@ -0,0 +1,30 @@
+## Development Guide
+
+### Go development environment
+Restik is written in the go programming language. The release is built and tested on **go 1.8**. If you haven't set up a Go
+development environment, please follow [these instructions](https://golang.org/doc/code.html) to install the go tools.
+
+### Dependency management
+Restik build and test scripts use glide to manage dependencies.
+
+To install glide follow [these instructions](https://github.com/Masterminds/glide#install).
+
+Currently the project includes all its required dependencies inside `vendor` to make things easier.
+
+### Run Test
+#### Run Unit Test by
+```sh
+./hack/make.py test unit
+```
+
+#### Run e2e Test
+```sh
+./hack/make.py test e2e
+```
+
+### Local Build
+To build Restik using your local Go development environment (generate linux binaries):
+```sh
+$ ./hack/make.py
+```
+Read full [Build instructions](build.md).

docs/developer-guide/build.md

@@ -0,0 +1,36 @@
+# Build Instructions
+
+## Requirements
+- go1.5+
+- glide
+
+## Build Binary
+```sh
+# Install/Update dependency (needs glide)
+glide slow
+
+# Build
+./hack/make.py
+```
+
+## Build Docker
+```sh
+# Build Docker image
+# This will build Backup Controller Binary and use it in docker
+./hack/docker/setup.sh
+```
+
+###### Push Docker Image
+```sh
+# This will push docker image to other repositories
+
+# Add docker tag for your repository
+docker tag appscode/restik:<tag> <image>:<tag>
+
+# Push Image
+docker push <image>:<tag>
+
+# Example:
+docker tag appscode/restik:default sauman/restik:default
+docker push sauman/restik:default
+```

docs/developer-guide/design.md

@@ -0,0 +1,32 @@
+#Architecture 
+
+This guide will walk you through the architectural design of Backup Controller.
+
+## Backup Controller:
+Backup Controller collects all information from watcher. This Watcher watches Backup objects. 
+Controller detects following ResourceEventType:
+
+* ADDED
+* UPDATETD
+* DELETED
+
+## Workflow
+User deploys restik TPR controller. This will automatically create TPR if not present.
+User creates a TPR object defining the information needed for taking backups. User adds a label `backup.appscode.com/config:<name_of_tpr>` Replication Controllers, Deployments, Replica Sets, Replication Controllers, Statefulsets that TPR controller watches for. 
+Once TPR controller finds RC etc that has enabled backup, it will add a sidecar container with restik image. So, restik will restart the pods for the first time. In restic-sidecar container backup process will be done through a cron schedule.
+When a snapshot is taken an event will be created under the same namespace. Event name will be `<name_of_tpr>-<backup_count>`. If a backup precess successful event reason will show us `Success` else event reason will be `Failed`
+If the RC, Deployments, Replica Sets, Replication Controllers, and TPR assocation is later removed, TPR controller will also remove the side car container.
+
+## Entrypoint
+
+Since restic process will be run on a scheule, some process will be needed to be running as the entrypoint. 
+This is a loader type process that watches restic TPR and translates that into the restic compatiable config. eg,
+
+* restik run: This is the main TPR controller entrypoint that is run as a single deployment in Kubernetes.
+* restik watch: This will watch Kubernetes restic TPR and start the cron process.
+
+## Restarting pods
+
+As mentioned before, first time side car containers are added, pods will be restarted by controller. Who performs the restart will be done on a case-by-case basis. 
+For example, Kubernetes itself will restarts pods behind a deployment. In such cases, TPR controller will let Kubernetes do that.
+

docs/user-guide/backup.md

@@ -0,0 +1,166 @@
+# How to backup
+
+
+
+## High Level Tasks
+* Create `backup.appscode.com` Third Party Resource
+* Create Backup Deployment
+
+## Deploying Backup
+
+### Create Third Party Resource
+`Backup process` depends on Third Party Resource Object `backup.appscode.com`. This object can be created using following data.
+
+```yaml
+apiVersion: extensions/v1beta1
+kind: ThirdPartyResource
+metadata:
+  name: backup.appscode.com
+description: "Backup and restore support for Kubernetes persistent volumes by AppsCode"
+versions:
+  - name: v1beta1
+```
+
+
+```sh
+# Create Third Party Resource
+$ kubectl apply -f https://raw.githubusercontent.com/appscode/restik/master/api/extensions/backup.yaml
+```
+
+
+### Deploy Controller
+Backup controller communicates with kube-apiserver at inCluster mode if no master or kubeconfig is provided. It watches Backup resource to handle backup process.
+```
+$ kubectl apply -f https://raw.githubusercontent.com/appscode/restik/master/hack/deploy/deployments.yaml
+```
+
+#### Configuration Options
+```
+--master          // The address of the Kubernetes API server (overrides any value in kubeconfig)
+--kubeconfig      // Path to kubeconfig file with authorization information (the master location is set by the master flag)
+--image           // Restik image name with version to be run in restic-sidecar (appscode/restik:latest)
+```
+
+## Backup
+This resource type is backed by a controller which take backup of kubernetes volumes from any running pod in Kubernetes. It can also take backup of host paths from Nodes in Kubernetes.
+
+### Resource
+A AppsCode Backup resource Looks like at the kubernetes level:
+
+```yaml
+apiVersion: appscode.com/v1beta1
+kind: Backup
+metadata:
+  name: test-backup
+  namespace: default
+spec:
+  source:
+    volumeName: "test-volume"
+    path: /mypath
+  destination:
+    path: /restikrepo
+    repositorySecretName: test-secret
+    volume:
+      emptyDir: {}
+      name: restik-volume
+  schedule: "0 * * * * *"
+  tags:
+  - testTag
+  retentionPolicy:
+    keepLastSnapshots: 3
+```
+
+**Line 1-3**: With all other Kubernetes config, AppsCode Backup resource needs `apiVersion`, `kind` and `metadata` fields. `apiVersion` and `kind` needs to be exactly same as `appscode.com/v1beta1`, and, `specific version` currently as `v1beta1`, to identify the resource
+as AppsCode Backup. In metadata the `name` and `namespace` indicates the resource identifying name and its Kubernetes namespace.
+
+**Line 6-20**: Backup spec has all the information needed to configure the backup process. 
+
+* In `source` field user needs to specify the volume name and the path of which he/she wants to take backup.
+* In `destination` field user needs to specify the path and the volume where he/she wants to store the backup snapshots.
+* In `repositorySecretName` user adds name of the secret. In secret user will add a key `password`, which will be used as the password for the backup repository. Secret and Backup must be under the same namespace.
+* User can add tag for the snapshots by using `tags` field. Multiple tags are allowed for a single snapshot.
+* User needs to add the `schedule`. Its the time interval of taking snapshots. It will be in cron format. You can learn about cron format from [here](http://www.nncron.ru/help/EN/working/cron-format.htm).
+* In `retentionPolicy` user adds the policy of keeping snapshots. Retention policy options are below.
+
+```
+# keepLastSnapshots: n --> never delete the n last (most recent) snapshots
+# keepHourlySnapshots: n --> for the last n hours in which a snapshot was made, keep only the last snapshot for each hour.
+# keepDailySnapshots: n --> for the last n days which have one or more snapshots, only keep the last one for that day.
+# keepWeeklySnapshots: n --> for the last n weeks which have one or more snapshots, only keep the last one for that week.
+# keepMonthlySnapshots: n --> for the last n months which have one or more snapshots, only keep the last one for that month.
+# keepYearlySnapshots: n --> for the last n years which have one or more snapshots, only keep the last one for that year.
+# keepTags --> keep all snapshots which have all tags specified by this option.
+```                
+One can restrict removing snapshots to those which have a particular hostname with the `retainHostname` , or tags with the `retainTags` option. 
+When multiple `retainTags` are specified, only the snapshots which have all the tags are considered.
+
+## Enable Backup
+
+For enabling the backup process for a particular kubernetes object like `RC`, `Replica Set`, `Deployment`, `DaemonSet` user adds a label `backup.appscode.com/config: <name_of_tpr>`. `<name_of_tpr>` is the name of backup object. And then user creates the backup object for starting backub.
+In case of StaefulSet user has to add the restic-sidecar container manually.
+
+```yaml
+apiVersion: apps/v1beta1
+kind: StatefulSet
+metadata:
+  labels:
+    backup.appscode.com/config: test-backup
+  name: test-statefulset
+  namespace: default
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: nginx
+  serviceName: test-svc
+  template:
+    metadata:
+      labels:
+        app: nginx
+      name: nginx
+    spec:
+      containers:
+      - image: nginx
+        imagePullPolicy: Always
+        name: nginx
+        volumeMounts:
+        - mountPath: /source_path
+          name: test-volume
+      - args:
+        - watch
+        - --v=10
+        env:
+        - name: RESTIK_NAMESPACE
+          value: default
+        - name: TPR
+          value: test-backup
+        image: appscode/restik:latest
+        imagePullPolicy: Always
+        name: restic-sidecar
+        volumeMounts:
+        - mountPath: /source_path
+          name: test-volume
+        - mountPath: /repo_path
+          name: restik-vol
+      volumes:
+      - emptyDir: {}
+        name: test-volume
+      - emptyDir: {}
+        name: restik-vol
+```
+
+## Backup Nodes
+
+If one interested in take backup of host paths, this can be done by deploying a `DaemonSet` with a do nothing busybox container. 
+Restik TPR controller can use that as a vessel for running restic side card containers.
+
+## Update Backup
+
+One can update the bckup source, retention policy, tags of the backup object. After updating the backup object backup process will follow the new backup strategy.
+If user wants to update the image of restic-sidecar container he/she needs to update the `backup.appscode.com/image` in field annotation in the backup object. This will automatically update the restic-sidecar container.
+In case of Statefulset user needs to update the sidecar container manually.
+
+## Disable Backup
+
+For disabling backup process one needs to delete the corresponding backup object in case of `RC`, `Replica Set`, `Deployment`, `DaemonSet`.
+In case of `Statefulset` user needs to delete the corresponding backup object as well as remove the side container from the Statefulset manually.

docs/user-guide/install.md

@@ -0,0 +1,10 @@
+## Install Restik
+```
+git clone https://github.com/appscode/restik.git
+./hack/make.py
+```
+
+## Upgrade Restik
+```
+To upgrade Restik User needs to pull the particular branch and rebuild it for now.
+```