Implement persistence with StatefulSets

README.md

@@ -11,7 +11,7 @@ The Habitat operator is a Kubernetes controller designed to solve running and au
 
 To learn more about Habitat, please visit the [Habitat website](https://www.habitat.sh/).
 
-For a more detailed description of the Habitat operator API have a look at the [API documentation](https://github.com/habitat-sh/habitat-operator/blob/master/docs/api.md).
+For a more detailed description of the Habitat type have a look [here](https://github.com/habitat-sh/habitat-operator/blob/master/pkg/apis/habitat/v1beta1/types.go).
 
 ## Prerequisites
 

examples/persisted/README.md

@@ -0,0 +1,37 @@
+# Persistent Storage example
+
+Habitat objects are translated by the operator into `StatefulSet` objects, which
+provide optional support for persistent storage.
+
+In order to enable persistent storage for your Habitat object, you need to:
+
+* create a
+[`StorageClass`](https://kubernetes.io/docs/concepts/storage/storage-classes/) object in your cluster
+* add the `spec.persistentStorage` key to the Habitat object's manifest
+* specify the `name` of the aforementioned `StorageClass` object under
+`spec.persistence.storageClassName` in the Habitat object's manifest
+
+## Workflow
+
+Before deploying the example, create a `StorageClass` object, specifying the
+type of volume your cluster is able to provision.
+
+**NOTE**: If you're deploying the example on GKE, a standard
+`StorageClass` for `GCEPersistentDisk` has already been defined, so you can skip
+the above step
+
+Once the `StorageClass` has been created, run the example:
+
+    kubectl create -f examples/persisted/habitat.yml
+
+When you want to delete the Habitat, run:
+
+    kubectl delete -f examples/persisted/habitat.yml
+
+**NOTE**: Any `PersistentVolume` created by the operator will **NOT** be
+automatically removed. This is the default behaviour of Kubernetes and is
+intended as a safeguard against accidental data deletion.
+
+If you want to explicitly delete the `PersistentVolume`, run:
+
+    kubectl delete pvc -l habitat-name=example-persistent-habitat

examples/persisted/habitat.yml

@@ -0,0 +1,28 @@
+apiVersion: habitat.sh/v1beta1
+kind: Habitat
+metadata:
+  name: example-persistent-habitat
+spec:
+  # the core/redis habitat service packaged as a Docker image
+  image: kinvolk/redis-hab
+  count: 3
+  # the presence of this key activates persistent storage
+  persistentStorage:
+    # the size of the volume that will be mounted in each Pod
+    size: 1Gi
+    # a StorageClass object with name "standard" must be created beforehand by
+    # the cluster administrator
+    storageClassName: standard
+    # the location under which the volume will be mounted
+    mountPath: /tmp/foobar
+  env:
+    - name: HAB_REDIS
+      # this is needed to make redis accept connections from other hosts
+      # see https://redis.io/topics/security#protected-mode
+      # NOTE: do not use this setting in a production environment
+      value: '{ "protected-mode": "no" }'
+  service:
+    name: redis
+    topology: leader
+    # if not present, defaults to "default"
+    group: foobar

examples/rbac/rbac.yml

@@ -34,7 +34,7 @@ rules:
 - apiGroups:
   - apps
   resources:
-  - deployments
+  - statefulsets
   verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
 - apiGroups: [""]
   resources:

pkg/apis/habitat/v1beta1/types.go

@@ -51,6 +51,20 @@ type HabitatSpec struct {
 	// The EnvVar type is documented at https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.9/#envvar-v1-core.
 	// Optional.
 	Env []corev1.EnvVar `json:"env,omitempty"`
+	// Optional.
+	PersistentStorage *PersistentStorage `json:"persistentStorage,omitempty"`
+}
+
+// PersistentStorage contains the details of the persistent storage that the
+// cluster should provision.
+type PersistentStorage struct {
+	// Size is the volume's size.
+	// It uses the same format as Kubernetes' size fields, e.g. 10Gi
+	Size string `json:"size"`
+	// MountPath is the path at which the PersistentVolume will be mounted.
+	MountPath string `json:"mountPath"`
+	// StorageClassName is the name of the StorageClass that the StatefulSet will request.
+	StorageClassName string `json:"storageClassName"`
 }
 
 type HabitatStatus struct {
@@ -102,6 +116,8 @@ const (
 
 	TopologyStandalone Topology = "standalone"
 	TopologyLeader     Topology = "leader"
+
+	HabitatKind = "Habitat"
 )
 
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object