From ce5d7d43db4d72045db14f3a3156763058808e5a Mon Sep 17 00:00:00 2001
From: Ewa Socala <socaa@google.com>
Date: Mon, 28 Sep 2015 11:06:02 +0200
Subject: [PATCH] added README file to Resource Consumer

---
 test/images/resource-consumer/README.md | 84 +++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 test/images/resource-consumer/README.md

diff --git a/test/images/resource-consumer/README.md b/test/images/resource-consumer/README.md
new file mode 100644
index 0000000000..de2d9ba593
--- /dev/null
+++ b/test/images/resource-consumer/README.md
@@ -0,0 +1,84 @@
+# Resource Consumer
+
+## Overview
+
+Resource Consumer is a tool which allows to generate cpu/memory utilization in a container.
+The reason why it was created is testing kubernetes autoscaling.
+Resource Consumer can help with autoscaling tests for:
+- cluster size autoscaling,
+- horizontal autoscaling of pod - changing the size of replication controller,
+- vertical autoscaling of pod - changing its resource limits.
+
+## Usage
+
+Resource Consumer starts an HTTP server and handle sended requests.
+It listens on port given as a flag (default 8080).
+Action of consuming resources is send to the container by a POST http request.
+Each http request creates new process.
+Http request handler is in file resource_consumer_handler.go 
+
+The container consumes specified amount of resources:
+
+- CPU in millicores,
+- Memory in megabytes.
+
+
+
+###Consume CPU http request
+
+- suffix "ConsumeCPU",
+- parameters "millicores" and "durationSec".
+
+Consumes specified amount of millicores for durationSec seconds.
+Consume CPU uses "./consume-cpu/consume-cpu" binary (file consume-cpu/consume_cpu.go).
+When CPU consumption is too low this binary uses cpu by calculating math.sqrt(0) 10^7 times
+and if consumption is too high binary sleeps for 10 millisecond.
+One replica of Resource Consumer cannot consume more that 1 cpu.
+
+###Consume Memory http request
+
+- suffix "ConsumeMem",
+- parameters "megabytes" and "durationSec".
+
+Consumes specified amount of megabytes for durationSec seconds.
+Consume Memory uses stress tool (stress -m 1 --vm-bytes megabytes --vm-hang 0 -t durationSec).
+Request leading to consumig more memory then container limit will be ignored. 
+
+###CURL example
+```console
+$ kubectl run resource-consumer --image=gcr.io/google_containers/resource_consumer:beta
+$ kubectl expose rc resource-consumer --create-external-load-balancer=true --port=8080 --target-port=8080
+$ kubectl get services resource-consumer
+```
+
+There are two IPs first one is internal, second one is the external load-balanced IP. Both serving port 8080. (Use second one)
+
+```console
+$ curl --data "millicores=300&durationSec=600" http://104.197.103.250:8080/ConsumeCPU.
+```
+
+300 millicores will be consumed for 600 seconds.
+
+## Image
+
+Docker image of Resource Consumer can be found in Google Container Registry as gcr.io/google_containers/resource_consumer:beta
+
+## Use cases
+
+###Cluster size autoscaling
+1. Consume more resources on each node that is specified for autoscaler
+2. Observe that cluster size increased
+
+###Horizontal autoscaling of pod
+1. Create consuming RC and start consuming appropriate amount of resources
+2. Observe that RC has been resized
+3. Observe that usage on each replica decreased
+
+###Vertical autoscaling of pod
+1. Create consuming pod and start consuming appropriate amount of resources
+2. Observed that limits has been increased
+
+
+
+
+[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/test/images/resource-consumer/README.md?pixel)]()