Just checking how it renders

1 files changed, 39 insertions, 62 deletions

diff --git a/README.md b/README.md
index 0f92d64..4971a84 100644
--- a/README.md
+++ b/README.md
@@ -1,78 +1,55 @@
-_Manifests here require Kubernetes 1.8 now.
-On earlier versions use [v2.1.0](https://github.com/Yolean/kubernetes-kafka/tree/v2.1.0)._
+# Kafka for Kubernetes
 
-# Kafka on Kubernetes
+This community seeks to provide:
+ * Production-worthy setup of Kafka for persistent data, domain and ops, at small scale.
+ * Operational knowledge, skewed towards resilience rather than throughput, encoded into Kubernetes manifest.
+ * A platform for streaming/event-driven microservices design using Kubernetes.
 
-Transparent Kafka setup that you can grow with.
-Good for both experiments and production.
+We suggest you `apply` manifests in the following order:
+ * You choice of storage classes from [./configure/](./configure).
+ * [./rbac-namespace-default](./rbac-namespace-default/)
+ * [./zookeeper](./zookeeper/)
+ * [./kafka](./kafka/)
 
-How to use:
- * Good to know: you'll likely want to fork this repo. It prioritizes clarity over configurability, using plain manifests and .propeties files; no client side logic.
- * Run a Kubernetes cluster, [minikube](https://github.com/kubernetes/minikube) or real.
- * Quickstart: use the `kubectl apply`s below.
- * Have a look at [addon](https://github.com/Yolean/kubernetes-kafka/labels/addon)s, or the official forks:
-   - [kubernetes-kafka-small](https://github.com/Reposoft/kubernetes-kafka-small) for single-node clusters like Minikube.
-   - [StreamingMicroservicesPlatform](https://github.com/StreamingMicroservicesPlatform/kubernetes-kafka) Like Confluent's [platform quickstart](https://docs.confluent.io/current/connect/quickstart.html) but for Kubernetes.
- * Join the discussion in issues and PRs.
+That'll give you client "bootstrap" `bootstrap.kafka.svc.cluster.local:9092`.
 
-No readable readme can properly introduce both [Kafka](http://kafka.apache.org/) and [Kubernetes](https://kubernetes.io/),
-but we think the combination of the two is a great backbone for microservices.
-Back when we read [Newman](http://samnewman.io/books/building_microservices/) we were beginners with both.
-Now we've read [Kleppmann](http://dataintensive.net/), [Confluent](https://www.confluent.io/blog/) and [SRE](https://landing.google.com/sre/book.html) and enjoy this "Streaming Platform" lock-in :smile:.
+## Fork
 
-We also think the plain-yaml approach of this project is easier to understand and evolve than [helm](https://github.com/kubernetes/helm) [chart](https://github.com/kubernetes/charts/tree/master/incubator/kafka)s.
+Our only dependency is `kubectl`. Not because we hate Helm or Operators, but because we think plain manifests make it easier to collaborate.
+If you begin to rely on this kafka setup we recommend you fork, for example to edit [broker config]().
 
-## What you get
+## Version history
 
-Keep an eye on `kubectl --namespace kafka get pods -w`.
+| tag  | k8s >= | highlights |
+|------|----||
+| v3.1 | 1.8|The painstaking path to `min.insync.replicas`=2|
+| v3.0 | 1.8||
+| v2.1 | 1.5 ||
+| v2.0 | 1.5 |[addon](https://github.com/Yolean/kubernetes-kafka/labels/addon)s|
+| v1.0 |  1  |Stateful? In Kubernetes? 2016? Yes.|
 
-The goal is to provide [Bootstrap servers](http://kafka.apache.org/documentation/#producerconfigs): `kafka-0.broker.kafka.svc.cluster.local:9092,kafka-1.broker.kafka.svc.cluster.local:9092,kafka-2.broker.kafka.svc.cluster.local:9092`
-`
+## Monitoring
 
-Zookeeper at `zookeeper.kafka.svc.cluster.local:2181`.
+Have a look at:
+ * [./prometheus](./prometheus/)
+ * [./linkedin-burrow](./linkedin-burrow/)
+ * [or plain JMX](https://github.com/Yolean/kubernetes-kafka/pull/96)
+ * what's happening in the [monitoring](https://github.com/Yolean/kubernetes-kafka/labels/monitoring) label.
+ * Note that this repo is intentionally light on [automation](https://github.com/Yolean/kubernetes-kafka/labels/automation). We think every SRE team must build the operational knowledge first.
 
-## Prepare storage classes
+## Outside (out-of-cluster) access
 
-For Minikube run `kubectl apply -f configure/minikube-storageclass-broker.yml; kubectl apply -f configure/minikube-storageclass-zookeeper.yml`.
+ * [Brokers](./outside-services/)
 
-There's a similar setup for AKS under `configure/aks-*` and for GKE under `configure/gke-*`. You might want to tweak it before creating.
+## Fewer than three nodes?
 
-## Start Zookeeper
+For minikube, youkube etc have a look at:
 
-The [Kafka book](https://www.confluent.io/resources/kafka-definitive-guide-preview-edition/) recommends that Kafka has its own Zookeeper cluster with at least 5 instances.
+ * [Scale 1](https://github.com/Yolean/kubernetes-kafka/pull/44)
+ * [Scale 2](https://github.com/Yolean/kubernetes-kafka/pull/118)
 
-```
-kubectl apply -f ./zookeeper/
-```
+## Stream...
 
-To support automatic migration in the face of availability zone unavailability we mix persistent and ephemeral storage.
-
-## Start Kafka
-
-```
-kubectl apply -f ./kafka/
-```
-
-You might want to verify in logs that Kafka found its own DNS name(s) correctly. Look for records like:
-```
-kubectl -n kafka logs kafka-0 | grep "Registered broker"
-# INFO Registered broker 0 at path /brokers/ids/0 with addresses: PLAINTEXT -> EndPoint(kafka-0.broker.kafka.svc.cluster.local,9092,PLAINTEXT)
-```
-
-That's it. Just add business value :wink:.
-
-## RBAC
-
-For clusters that enforce [RBAC](https://kubernetes.io/docs/admin/authorization/rbac/) there's a minimal set of policies in
-```
-kubectl apply -f rbac-namespace-default/
-```
-
-## Tests
-
-Tests are based on the [kube-test](https://github.com/Yolean/kube-test) concept.
-Like the rest of this repo they have `kubectl` as the only local dependency.
-
-Run self-tests or not. They do generate some load, but indicate if the platform is working or not.
- * To include tests, replace `apply -f` with `apply -R -f` in your `kubectl`s above.
- * Anything that isn't READY in `kubectl get pods -l test-type=readiness --namespace=test-kafka` is a failed test.
+ * [Kubernetes events to kafka](./events-kube/)
+ * [Container logs to Kafka](https://github.com/Yolean/kubernetes-kafka/pull/131)
+ * [Heapster metrics to Kafka](https://github.com/Yolean/kubernetes-kafka/pull/120)