Fix docs

Author: MattiasGees

docs/examples/horizontal-pod-autoscaling.rst

@@ -25,7 +25,7 @@ Prometheus
 
 You need Prometheus to scrape and store metrics from applications in its 
 time series database. These metrics will be used by the HPA to decide if it 
-has to scale the  application. You can use an already running Prometheus in 
+has to scale the application. You can use an already running Prometheus in 
 your environment or opt to set one up with the following steps.
 
 .. warning::
@@ -48,7 +48,7 @@ Prometheus, Alertmanager and configure ServiceMonitors.
     helm install coreos/prometheus-operator --name prometheus-operator --namespace application-monitoring
 
 After installing the Prometheus operator you can install Prometheus. To accomplish
-this you use an yaml values file. This yaml file defines you want 2 Prometheus
+this you use a yaml values file. This yaml file defines you want 2 Prometheus
 pods running, keep data for 14 days and want to have a persistent volume
 of 20 GB per Prometheus pod. You can tweak the Prometheus install further
 by following the official `documentation <https://github.com/coreos/prometheus-operator/tree/master/helm/prometheus>`__.
@@ -88,22 +88,27 @@ You need to create a CA and SSL cert to validate your APIService with Kubernetes
     openssl req -x509 -sha256 -new -nodes -days 365 -newkey rsa:2048 -keyout ${PURPOSE}-ca.key -out ${PURPOSE}-ca.crt -subj "/CN=ca"
     echo '{"signing":{"default":{"expiry":"43800h","usages":["signing","key encipherment","'${PURPOSE}'"]}}}' > "${PURPOSE}-ca-config.json"
 
-    export SERVICE_NAME=prometheus-adapter-prometheus-adapter
-    export ALT_NAMES='"prometheus-adapter-prometheus-adapter.application-monitoring","prometheus-adapter-prometheus-adapter.application-monitoring.svc"'
+    export SERVICE_NAME=prometheus-adapter
+    export ALT_NAMES='"prometheus-adapter.application-monitoring","prometheus-adapter.application-monitoring.svc"'
     echo '{"CN":"'${SERVICE_NAME}'","hosts":['${ALT_NAMES}'],"key":{"algo":"rsa","size":2048}}' | cfssl gencert -ca=server-ca.crt -ca-key=server-ca.key -config=server-ca-config.json - | cfssljson -bare apiserver
 
+
+.. warning::
+   Make sure the ``SERVICE_NAME`` and ``ALT_NAMES`` match your application release
+   name and namespace where it is deployed.
+
 Now create an ``prometheus-adapater.yaml`` with the following content:
 
 .. code-block:: yaml
 
     tls:
         enable: true
         ca: |-
-            <content of server-ca.crt>
+            <replace with content of server-ca.crt>
         key: |-
-            <content of apiserver-key.pem>
+            <replace with content of apiserver-key.pem>
         certificate: |-
-            <content of apiserver.pem>
+            <replace with content of apiserver.pem>
 
     # Change URL and port if you setup your own Prometheus server.
     prometheus:
@@ -117,15 +122,16 @@ Install the Prometheus Adapter:
 .. code-block:: bash
 
     helm repo add incubator https://kubernetes-charts-incubator.storage.googleapis.com/
-    helm install incubator/prometheus-adapter --name prometheus-adapter --namespace application-monitoring -f prometheus-adapter.yaml
+    helm install stable/prometheus-adapter --name prometheus-adapter --namespace application-monitoring -f prometheus-adapter.yaml
 
 
-Now you can test if it works by running the following command against your 
+You can test if HPA works by running the following command against your 
 Kubernetes cluster.
 
 .. code-block:: bash
 
     kubectl get --raw /apis/custom.metrics.k8s.io/v1beta1
+
     {"kind":"APIResourceList","apiVersion":"v1","groupVersion":"custom.metrics.k8s.io/v1beta1","resources":[]}
 
 Usage
@@ -144,7 +150,7 @@ your application with Prometheus.
     kind: ServiceMonitor
     metadata:
         name: <example>
-        namespace: <example_namespace>
+        namespace: application-monitoring
     labels:
         prometheus: prometheus-applications
     spec:
@@ -159,32 +165,31 @@ your application with Prometheus.
             matchLabels:
                 <key>: <value that matches your application>
 
-When adding the following ``ServiceMonitor``, make sure to keep ``prometheus``
-as an key in labels, this is how Prometheus discovers the different 
-ServiceMonitors.
+When adding the ``ServiceMonitor``, make sure to keep ``prometheus`` as an key
+in labels, that is how Prometheus discovers the different ServiceMonitors.
+The ``ServiceMonitor`` has to be deployed in the same namespace as your Prometheus.
 
 After applying the ``ServiceMonitor``, Prometheus should start discovering
 all your application pods and start to monitor them.
 
-Now you can find the correct metric and you can get it out of the custom.metrics
-API endpoint.
+You can find the correct metric by querying the custom.metrics API endpoint.
 
 .. code-block:: bash
 
     kubectl get --raw /apis/custom.metrics.k8s.io/v1beta1 | jq
-    kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta1/namespaces/default/pods/*/requestcount" | jq
-    kubectl get --raw /apis/custom.metrics.k8s.io/v1beta1/namespaces/default/service/example/requestcount | jq
+    kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta1/namespaces/<aplication_namespace>/pods/*/<metric_name>" | jq
+    kubectl get --raw /apis/custom.metrics.k8s.io/v1beta1/namespaces/<aplication_namespace>/service/<service_name>/<metric_name> | jq
 
-When you found the correct metric to scale on, you can create your
+When you found the correct metric to scale on, you can create your 
 ``HorizontalPodAutoscaler``.
 
 .. code-block:: yaml
 
     kind: HorizontalPodAutoscaler
     apiVersion: autoscaling/v2beta1
     metadata:
-        name: example
-        namespace: default
+        name: <example>
+        namespace: <example_namespace>
     spec:
         scaleTargetRef:
             apiVersion: apps/v1beta2
@@ -193,15 +198,12 @@ When you found the correct metric to scale on, you can create your
         minReplicas: 2
         maxReplicas: 4
         metrics:
-        - type: Object
-          object:
-            target:
-                kind: Service
-                name: example
-            metricName: requestcount
-            targetValue: 30
+        - type: Pods
+          pods:
+            metricName: <metric_name>
+            targetAverageValue: <metric_value>
 
-Now you watch the horizontal pod autoscaler:
+Watch the horizontal pod autoscaler:
 
 .. code-block:: bash
     
@@ -212,3 +214,6 @@ More examples can be found in the kubernetes `documentation <https://kubernetes.
 
 .. warning::
     Certainly take a look a types ``Object`` and ``Pods`` for HPA based on custom-metrics.
+
+A fully worked out example with a example application that has metrics can be found in 
+`luxas repo <https://github.com/luxas/kubeadm-workshop/blob/master/demos/monitoring/sample-metrics-app.yaml#L51>`__.