Merge "Fix error in logging installation"

1 files changed, 24 insertions, 8 deletions

diff --git a/docs/development/design/logging.rst b/docs/development/design/logging.rst
index 05f3f5b..5fbaeb9 100644
--- a/docs/development/design/logging.rst
+++ b/docs/development/design/logging.rst
@@ -9,7 +9,23 @@ Installation
 Currently, we use the `sample configuration`_ in Istio to install fluentd::
 
     cd clover/logging
-    kubectl apply -f install
+
+First, install logging stack Elasticsearch, Fluentd and Kibana::
+
+    kubectl apply -f install/logging-stack.yaml
+
+Then configure fluentd for istio::
+
+    kubectl apply -f install/fluentd-istio.yaml
+
+Note that, it must be done in two steps. If you run ``kubectl apply -f install``
+instead, the mixer adapter may fail to intialize because the target service can
+not be found. You may find an error message from mixer container::
+
+    2018-05-09T02:43:14.435156Z	error	Unable to initialize adapter:
+    snapshot='6', handler='handler.fluentd.istio-system', adapter='fluentd',
+    err='adapter instantiation error: dial tcp: lookup fluentd-es.logging on
+    10.96.0.10:53: no such host'.
 
 .. _sample configuration: https://istio.io/docs/tasks/telemetry/fluentd.html
 
@@ -50,14 +66,14 @@ Istio defines when to log by creating a custom resource ``rule``. For example:
     apiVersion: "config.istio.io/v1alpha2"
     kind: rule
     metadata:
-    name: newlogtofluentd
-    namespace: istio-system
+      name: newlogtofluentd
+      namespace: istio-system
     spec:
-    match: "true" # match for all requests
-    actions:
-    - handler: handler.fluentd
-      instances:
-      - newlog.logentry
+      match: "true" # match for all requests
+      actions:
+      - handler: handler.fluentd
+        instances:
+        - newlog.logentry
 
 This rule specifies that all instances of ``newlog.logentry`` that matches the
 expression will be handled by the specified handler ``handler.fluentd``. We