sample-controller: add usage instructions to README

staging/src/k8s.io/sample-controller/README.md

@@ -3,6 +3,12 @@
 This repository implements a simple controller for watching Foo resources as
 defined with a CustomResourceDefinition (CRD).
 
+This particular example demonstrates how to perform basic operations such as:
+
+* How to register a new custom resource (custom resource type) of type `Foo` using a CustomResourceDefinition.
+* How to create/get/list instances of your new resource type `Foo`.
+* How to setup a controller on resource handling create/update/delete events.
+
 It makes use of the generators in [k8s.io/code-generator](https://github.com/kubernetes/code-generator)
 to generate a typed client, informers, listers and deep-copy functions. You can
 do this yourself using the `./hack/update-codegen.sh` script.
@@ -17,16 +23,68 @@ Changes should not be made to these files manually, and when creating your own
 controller based off of this implementation you should not copy these files and
 instead run the `update-codegen` script to generate your own.
 
-# Purpose
+## Purpose
 
 This is an example of how to build a kube-like controller with a single type.
 
-# Compatibility
+## Running
+
+```sh
+# assumes you have a working kubeconfig, not required if operating in-cluster
+$ go run *.go -kubeconfig=$HOME/.kube/config
+
+# create a CustomResourceDefinition
+$ kubectl create -f artifacts/examples/crd.yaml
+
+# create a custom resource of type Foo
+$ kubectl create -f artifacts/examples/example-foo.yaml
+
+# check deployments created through the custom resource
+$ kubectl get deployments
+```
+
+## Use Cases
+
+CustomResourceDefinitions can be used to implement custom resource types for your Kubernetes cluster.
+These act like most other Resources in Kubernetes, and may be `kubectl apply`'d, etc.
+
+Some example use cases:
+
+* Provisioning/Management of external datastores/databases (eg. CloudSQL/RDS instances)
+* Higher level abstractions around Kubernetes primitives (eg. a single Resource to define an etcd cluster, backed by a Service and a ReplicationController)
+
+## Defining types
+
+Each instance of your custom resource has an attached Spec, which should be defined via a `struct{}` to provide data format validation.
+In practice, this Spec is arbitrary key-value data that specifies the configuration/behavior of your Resource.
+
+For example, if you were implementing a custom resource for a Database, you might provide a DatabaseSpec like the following:
+
+``` go
+type DatabaseSpec struct {
+	Databases []string `json:"databases"`
+	Users     []User   `json:"users"`
+	Version   string   `json:"version"`
+}
+
+type User struct {
+	Name     string `json:"name"`
+	Password string `json:"password"`
+}
+```
+
+## Cleanup
+
+You can clean up the created CustomResourceDefinition with:
+
+    $ kubectl delete crd foos.samplecontroller.k8s.io
+
+## Compatibility
 
 HEAD of this repository will match HEAD of k8s.io/apimachinery and
 k8s.io/client-go.
 
-# Where does it come from?
+## Where does it come from?
 
 `sample-controller` is synced from
 https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/sample-controller.