Add homebrew install instructions to README

Add homebrew install instructions to README.md
Yay! Many thanks to @aecolley.

Also modernise some other parts of the README and the guestbook
example.

Fixes #68

README.md

@@ -11,9 +11,6 @@ services, and then manage those templates as files in version control.
 The more complex your infrastructure is, the more you will gain from
 using kubecfg.
 
-Status: Basic functionality works, and the tool is usable.  The focus
-now is on clearer error reporting and advanced features.
-
 Yes, Google employees will recognise this as being very similar to a
 similarly-named internal tool ;)
 
@@ -23,6 +20,9 @@ Pre-compiled executables exist for some platforms on
 the [Github releases](https://github.com/ksonnet/kubecfg/releases)
 page.
 
+On macOS, it can also be installed via [Homebrew](https://brew.sh/):
+`brew install kubecfg`
+
 To build from source:
 
 ```console
@@ -57,6 +57,8 @@ To build from source:
 - Best-effort sorts objects before updating, so that dependencies are
   pushed to the server before objects that refer to them.
 - Additional jsonnet builtin functions. See `lib/kubecfg.libsonnet`.
+- Optional "garbage collection" of objects removed from config (see
+  `--gc-tag`).
 
 ## Infrastructure-as-code Philosophy
 

examples/guestbook.jsonnet

@@ -13,9 +13,7 @@
 //    See the License for the specific language governing permissions and
 //    limitations under the License.
 
-// Simple self-contained example to demonstrate kubecfg.
-// This should not necessarily be considered a model jsonnet example
-// to build upon.
+// Simple example to demonstrate kubecfg.
 
 // This is a simple port to jsonnet of the standard guestbook example
 // https://github.com/kubernetes/kubernetes/tree/master/examples/guestbook
@@ -26,69 +24,100 @@
 // kubecfg delete guestbook.jsonnet
 // ```
 
-local example = import "example.libsonnet";
+// This example uses kube.libsonnet from Bitnami.  There are several
+// other Kubernetes libraries available (notably ksonnet/ksonnet-lib),
+// or write your own!
+local kube = import "https://github.com/bitnami-labs/kube-libsonnet/raw/52ba963ca44f7a4960aeae9ee0fbee44726e481f/kube.libsonnet";
 
-{
-  frontend_deployment: example.deployment("frontend") {
-    spec+: {
-      replicas: 3,
-      template+: {
-        spec+: {
-          containers: [
-            example.container(
-              "php-redis", "gcr.io/google-samples/gb-frontend:v4"
-            ) {
-              resources: {
-                requests: { cpu: "100m", memory: "100Mi" },
-              },
-              env_: {
-                GET_HOSTS_FROM: "dns",
-              },
-              ports: [{containerPort: 80}],
-            }]}}}},
-
-  frontend_service: example.service("frontend") {
-    targetPod_: $.frontend_deployment.spec.template,
-    spec+: { type: "LoadBalancer" },
+// A function that returns 2 k8s objects: a redis Deployment and Service
+local redis(name) = {
+  svc: kube.Service(name) {
+    // "$" is an alias for the result value from the current function/file
+    target_pod:: $.deploy.spec.template,
   },
 
-  redis_master_deployment: example.deployment("redis-master") {
+  deploy: kube.Deployment(name) {
     spec+: {
       template+: {
         spec+: {
-          containers: [
-            example.container(
-              "master", "gcr.io/google_containers/redis:e2e"
-            ) {
-              resources: {
-                requests: { cpu: "100m", memory: "100Mi" },
-              },
+          containers_: {
+            redis: kube.Container("redis") {
+              image: "bitnami/redis:4.0.9",
+              resources: {requests: {cpu: "100m", memory: "100Mi"}},
               ports: [{containerPort: 6379}],
-            }]}}}},
 
-  redis_master_service: example.service("redis-master") {
-    targetPod_: $.redis_master_deployment.spec.template,
+              // kube.libsonnet has a few optional "underscore"
+              // helpers to convert k8s API structures into more
+              // natural jsonnet structures.  See kube.libsonnet.
+              env_: {
+                REDIS_REPLICATION_MODE: "master",
+                ALLOW_EMPTY_PASSWORD: "yes",
+              },
+            },
+          },
+        },
+      },
+    },
   },
+};
 
-  redis_slave_deployment: example.deployment("redis-slave") {
-    spec+: {
-      replicas: 2,
-      template+: {
-        spec+: {
-          containers: [
-            example.container(
-              "slave", "gcr.io/google_samples/gb-redisslave:v1"
-            ) {
-              resources: {
-                requests: { cpu: "100m", memory: "100Mi" },
-              },
-              env_: {
-                GET_HOSTS_FROM: "dns",
+// Note the jsonnet file evaluates to the last object in the file.
+// Kubecfg expects this object to be a possibly nested collection
+// (array or object) of Kubernetes API objects.
+{
+  frontend: {
+    svc: kube.Service("frontend") {
+      target_pod: $.frontend.deploy.spec.template,
+      spec+: {type: "LoadBalancer"},
+    },
+
+    deploy: kube.Deployment("frontend") {
+      spec+: {
+        replicas: 3,
+        template+: {
+          spec+: {
+            containers_+: {
+              frontend: kube.Container("php-redis") {
+                image: "gcr.io/google-samples/gb-frontend:v3",
+                resources: {
+                  requests: {cpu: "100m", memory: "100Mi"},
+                },
+                ports: [{containerPort: 80}],
+                readinessProbe: {
+                  httpGet: {path: "/", port: 80},
+                },
+                livenessProbe: self.readinessProbe {
+                  initialDelaySeconds: 10,
+                },
               },
-              ports: [{containerPort: 6379}],
-            }]}}}},
+            },
+          },
+        },
+      },
+    },
+  },
 
-  redis_slave_service: example.service("redis-slave") {
-    targetPod_: $.redis_slave_deployment.spec.template,
+  master: redis("redis-master"),
+
+  // "Override" some parameters in the slave redis Deployment.
+  slave: redis("redis-slave") {
+    deploy+: {
+      spec+: {
+        replicas: 2,
+        template+: {
+          spec+: {
+            containers_+: {
+              redis+: {
+                env_+: {
+                  REDIS_REPLICATION_MODE: "slave",
+                  REDIS_MASTER_HOST: $.master.svc.metadata.name,
+                  REDIS_MASTER_PORT_NUMBER: 6379,
+                },
+              },
+            },
+          },
+        },
+      },
+    },
   },
 }