updated documentation

README.md

@@ -1,10 +1,17 @@
 # yosoy
 
-yosoy is a HTTP service for stubbing distributed applications. It is a service which will introduce itself to the caller and print some useful information about its environment. "Yo soy" in español means "I am".
+yosoy is a HTTP service for stubbing and prototyping distributed applications. It is a service which will introduce itself to the caller and print some useful information about its environment. "Yo soy" in español means "I am".
 
 yosoy is extremely useful when creating a distributed application stub and you need to see a more meaningful responses than a default nginx welcome page.
 
-yosoy will provide information like (see example below):
+Typical use cases include:
+
+* testing HTTP routing & ingress
+* testing HTTP load balancing
+* testing HTTP caching
+* stubbing and prototyping the infrastructure
+
+yosoy will provide information like:
 
 * Request URI
 * Hostname
@@ -12,7 +19,10 @@ yosoy will provide information like (see example below):
 * How many times it was called
 * HTTP headers
 * Env variables if `YOSOY_SHOW_ENVS` is set to `true`, `yes`, `on`, or `1`
-* Files contents if `YOSOY_SHOW_FILES` is set to a comma-separated list of (valid) files
+* Files' contents if `YOSOY_SHOW_FILES` is set to a comma-separated list of (valid) files
+
+See [Kubernetes example](#kubernetes-example) below.
+
 
 ## Docker image
 
@@ -26,7 +36,9 @@ It exposes HTTP service on port 80.
 
 ## Kubernetes example
 
-Let's take a look at a sample Kubernetes deployment file. It uses both `YOSOY_SHOW_ENVS` and `YOSOY_SHOW_FILES`. To illustrate `YOSOY_SHOW_FILES` functionality it uses Kubernetes Downward API to expose labels and annotations as volume files which are then read by yosoy.
+Let's take a look at a sample Kubernetes deployment file. It uses both `YOSOY_SHOW_ENVS` and `YOSOY_SHOW_FILES`.
+
+> To illustrate `YOSOY_SHOW_FILES` functionality it uses Kubernetes Downward API to expose labels and annotations as volume files which are then read by yosoy.
 
 ```
 apiVersion: apps/v1
@@ -68,15 +80,40 @@ spec:
               - path: "annotations"
                 fieldRef:
                   fieldPath: metadata.annotations
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: camarero
+  labels:
+    app.kubernetes.io/name: camarero
+spec:
+  type: NodePort
+  selector:
+    app.kubernetes.io/name: camarero
+  ports:
+    - protocol: TCP
+      port: 80
 ```
 
-Execute curl a couple of times and you should see:
+Deploy above service (with 2 replicas) and execute curl to the service a couple of times:
+
+```
+kubectl apply -f test-deployment.yaml
+export NODE_PORT=$(kubectl get services/camarero -o go-template='{{(index .spec.ports 0).nodePort}}')
+curl $(minikube ip):$NODE_PORT
+curl $(minikube ip):$NODE_PORT
+curl $(minikube ip):$NODE_PORT
+curl $(minikube ip):$NODE_PORT
+```
+
+A sample response looks like this:
 
 ```
 Request URI: /
-Hostname: camarero-7fd97dc5f5-545mt
+Hostname: camarero-859d7c6d6b-kb5s5
 Remote IP: 172.18.0.1
-Called: 4
+Called: 2
 
 HTTP headers:
 User-Agent: curl/7.58.0
@@ -84,34 +121,31 @@ Accept: */*
 
 Env variables:
 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
-HOSTNAME=camarero-7fd97dc5f5-545mt
+HOSTNAME=camarero-859d7c6d6b-kb5s5
 YOSOY_SHOW_ENVS=true
 YOSOY_SHOW_FILES=/etc/podinfo/labels,/etc/podinfo/annotations
+CAMARERO_PORT_80_TCP_PORT=80
+CAMARERO_PORT_80_TCP_ADDR=10.105.203.131
 KUBERNETES_PORT=tcp://10.96.0.1:443
+KUBERNETES_PORT_443_TCP_PORT=443
+CAMARERO_SERVICE_HOST=10.105.203.131
 KUBERNETES_PORT_443_TCP_PROTO=tcp
-CAMARERO_SERVICE_HOST=10.96.183.207
 KUBERNETES_SERVICE_HOST=10.96.0.1
 KUBERNETES_SERVICE_PORT=443
 KUBERNETES_SERVICE_PORT_HTTPS=443
-CAMARERO_SERVICE_PORT=80
-CAMARERO_PORT_80_TCP_PROTO=tcp
 KUBERNETES_PORT_443_TCP=tcp://10.96.0.1:443
-CAMARERO_PORT_80_TCP=tcp://10.96.183.207:80
-CAMARERO_PORT_80_TCP_PORT=80
-KUBERNETES_PORT_443_TCP_PORT=443
 KUBERNETES_PORT_443_TCP_ADDR=10.96.0.1
-CAMARERO_PORT=tcp://10.96.183.207:80
-CAMARERO_PORT_80_TCP_ADDR=10.96.183.207
+CAMARERO_PORT=tcp://10.105.203.131:80
+CAMARERO_SERVICE_PORT=80
+CAMARERO_PORT_80_TCP=tcp://10.105.203.131:80
+CAMARERO_PORT_80_TCP_PROTO=tcp
 HOME=/root
 
 File /etc/podinfo/labels:
-app.kubernetes.io/component="api"
 app.kubernetes.io/name="camarero"
-app.kubernetes.io/part-of="camarero"
-app.kubernetes.io/version="0.0.1"
-pod-template-hash="7fd97dc5f5"
+pod-template-hash="859d7c6d6b"
 
 File /etc/podinfo/annotations:
-kubernetes.io/config.seen="2020-11-13T14:36:17.234235115Z"
+kubernetes.io/config.seen="2020-11-17T07:38:15.374049163Z"
 kubernetes.io/config.source="api"
 ```