chore(Adapter): Completed Adapter description

Author: rhuss

README.adoc

@@ -56,7 +56,7 @@ link:structural/InitContainer/README.adoc[Init Container]::
 link:structural/Sidecar/README.adoc[Sidecar]::
   Git polling example for a sidecar
 link:structural/Adapter/README.adoc[Adapter]::
-  Adapter for exporting timing information from the sample random-generator application in a Prometheus format [*]
+  Adapter for exporting timing information from the sample random-generator application in a Prometheus format
 link:structural/Ambassador/README.adoc[Ambassador]::
   Ambassador for moving on the log of the random-generator [*]
 

foundational/HealthProbe/README.adoc

@@ -2,19 +2,18 @@
 
 For this example we need a Kubernetes installation as described in link:../../INSTALL.adoc[INSTALLATION.adoc].
 
-For our example for this pattern we are reusing our https://github.com/k8spatterns/random-generator[random-generator] which also includes support for health checks.
+Here we are reusing our https://github.com/k8spatterns/random-generator[random-generator] which also includes support for health checks.
 
-To apply a Deployment with liveness and readiness check enables, use
+To apply a Deployment with liveness and readiness check enabled, use
 
 [source, bash]
 ----
-kubectl create -f deployment.yml
+kubectl create -f https://k8spatterns.io/HealthProbe/deployment.yml
 ----
 
 This deployment introduces an artificial pause of 20 seconds before the application becomes ready.
 To monitor the readiness and liveness states you best open an extra terminal with running
 
-
 [source, bash]
 ----
 kubectl get pods -w
@@ -24,7 +23,7 @@ random-generator-5856b5f774-54h6b   1/1     Running       0          38s
 ----
 
 The example apps expose to endpoints with which you can switch the state of the readiness and liveness checks.
-For simplicity reasons, we haven't installed a Service or Ingress (but of course, you are free to do so of course !)
+For simplicity reasons, we haven't installed a Service or Ingress (but of course, you are free to do so!)
 
 Instead we are using a simple port-forwarding directly to the pod to trigger the toggles:
 
@@ -34,29 +33,23 @@ Instead we are using a simple port-forwarding directly to the pod to trigger the
 kubectl port-forward $(pod random-generator) 8080:8080 &
 ----
 
-Now you can switch the readiness/liveness checks:
+Now you can switch on/off the readiness/liveness checks and see how the cluster manages your pods:
 
 [source, bash]
 ----
-# Check liveness
+# Check liveness probe by querying the actuator
 curl -s http://localhost:8080/actuator/health | jq .
-{
-  "status": "UP"
-}
 
-# Switch liveness checks
+# Toggle liveness check to off
 curl -s http://localhost:8080/toggle-live
 
-# Check liveness again
+# Check liveness probe again
 curl -s http://localhost:8080/actuator/health | jq .
-{
-  "status": "DOWN"
-}
 
-# Wait a bit and watch the pods. What happens after 2-3 mins ?
+# Watch the pods and wait a bit. What happens after 2-3 mins ?
 kubectl get pods -w
 
-# Switch readiness off
+# Now switch readiness off
 curl -s http://localhost:8080/toggle-ready
 
 # Watch the pods for 1-2 mins

structural/Adapter/README.adoc

@@ -2,6 +2,65 @@
 
 IMPORTANT: The instructions have not been written/finished, but the resource file has been verified. Instructions will be added soon.
 
+In this example we will see how we can expose a the metrics created by the random generator REST service in a Prometheus conformant format.
+
+By intention the metrics created by the the random-generator service is written is an own format which can't be used by Prometheus directly.
+Also the metrics are not exposed via a network port but is written into the filesystem.
+We are using an _Adapter_ sidecar container to convert and expose data written in that custom proprietary format over HTTP so that it can be scraped by Prometheus.
+
+Let's see how this works.
+
+We are using a bare Pod for simplicities sake (in real world scenarios this would be of course e.g. a Deployment).
+
+Please have a look into the `pod.yml` descriptor which
+
+* Create two containers: One is our `random-generator` the other is the _Adapter_, `k8spatterns/random-generator-exporter`. This is a simple Perl script (yeah, Perl ;) which does the transformation. You find the Dockerfile and script for this image in the link::image/[image] directory.
+* Create a volume which is shared between the main application container and the adapter. The main container writes the metrics file into this shared directory, and the Prometheus _Adapter_ picks it up when queried over HTTP
+
+The Pod can be created with
+
+[source, bash]
+----
+kubectl create -f https://k8spatterns.io/Adapter/pod.yml
+----
+
+For easy access of random generator, let's create a Service:
+
+[source, bash]
+----
+kubectl create -f https://k8spatterns.io/Adapter/service.yml
+----
+
+This Service uses a `nodePort` to expose it on every node of the cluster.
+For Minikube this works nicely.
+However, if your cluster nodes are not exposed, you might either use our `kubectl port-forward` hack used in other examples or use a full ingress or loadbalancer exposed route as described in the _Service Discovery_ pattern.
+
+Let's assume that you are using Minikube for now, so that we can access the
+Then let's access our Service with
+
+[source, bash]
+----
+port=$(kubectl get svc random-generator -o jsonpath={.spec.ports[0].nodePort})
+curl http://$(minikube ip):$port
+----
+
+When we now jump into the Pod we can examine the generated metrics file
+
+[source, bash]
+----
+kubectl exec -it random-generator -c main bash
+cat /logs/random.log
+----
+
+NOTE: You could also have entered the `adapter` container which mounts the same directory at `/logs/`, too
+
+The metrics extracted from that data can now be accessed in a Prometheus conformant way:
+
+[source, bash]
+----
+prom_port=$(kubectl get svc random-generator -o jsonpath={.spec.ports[1].nodePort})
+curl http://$(minikube ip):$prom_port
+----
 
 === More Information
 

structural/Adapter/image/Dockerfile

@@ -1,4 +1,4 @@
-# Imagename: k8spatterns/random-generator-exporter
+# Imagename: k8spatterns/random-generator-exporter:1.0
 # Simple image for exposing the log file created by random-exporter
 
 # Yes, I know. But still the best language for quick and small system related tasks

structural/Adapter/pod.yml

@@ -25,7 +25,8 @@ spec:
     - mountPath: /logs
       name: log-volume
   # ------------------------------------------------
-  # Prometheus adapter
+  # Prometheus adapter. You find the source to this image
+  # in the "image/" directory.
   - image: k8spatterns/random-generator-exporter
     name: adapter
     env: