Notes and changes for for logging stack upgrade

Adding suggestions from ewolinetz

Adding suggestions from ewolinetz

Updating install documentation and adding information on how to allow cluster-reader to view operations logs

Follow-up to ewolinet's notes on 'rolebinding-reader'

Author: danmacpherson

install_config/aggregate_logging.adoc

@@ -136,6 +136,19 @@ $ oadm policy add-cluster-role-to-user cluster-reader \
 this service account.
 ====
 
+. Enable the Elasticsearch service account to get cluster role bindings so that
+it can verify a user's roles and allow access to operations
+logs:
++
+====
+----
+$ oadm policy add-cluster-role-to-user rolebinding-reader \
+     system:serviceaccount:logging:aggregated-logging-elasticsearch <1>
+----
+<1> Use the project you created earlier (for example, *logging*) when specifying
+this service account.
+====
+
 [[aggregate-logging-specifying-deployer-parameters]]
 == Specifying Deployer Parameters
 
@@ -672,6 +685,21 @@ each new one to deploy it:
 $ oc scale --replicas=1 dc/logging-es-<suffix>
 ----
 
+[[cluster-reader-operations]]
+*Allowing cluster-reader to view operations logs*
+
+By default, only `cluster-admin` users are granted access in Elasticsearch and
+Kibana to view operations logs. To allow `cluster-reader` users to also view these
+logs, update the value of `openshift.operations.allow_cluster_reader` in the
+Elasticsearch configmap to `true`:
+
+----
+$ oc edit configmap/logging-elasticsearch
+----
+
+Please note that changes to the configmap might not appear until after redeploying
+the pods.
+
 [[aggregated-fluentd]]
 === Fluentd
 

install_config/upgrading/manual_upgrades.adoc

@@ -1344,6 +1344,15 @@ $ oadm policy add-cluster-role-to-user oauth-editor \
        system:serviceaccount:logging:logging-deployer
 ----
 
+. Ensure that the cluster role `rolebinding-reader` is assigned to the
+*aggregated-logging-elasticsearch* service account where `logging` is the namespace
+with aggregated logging installed:
++
+----
+$ oadm policy add-cluster-role-to-user rolebinding-reader \
+     system:serviceaccount:logging:aggregated-logging-elasticsearch
+----
+
 . In preparation for running the deployer, ensure that you have the configurations
 for your current deployment in the xref:../aggregate_logging.adoc#aggregate-logging-specifying-deployer-parameters[*logging-deployer* ConfigMap].
 +
@@ -1370,6 +1379,28 @@ of Fluentd pods, the deployer does delete the *logging-fluentd* Daemonset and re
 it from the *logging-fluentd-template* template.
 ====
 
+The latest EFK stack now uses Elasticsearch 2.3 with a common data model. This
+means Fluentd sends logs to Elasticsearch with a new indexing pattern for
+projects. The pattern is:
++
+----
+project.{namespace_name}.{namespace_id}.YYYY.MM.DD
+----
++
+For example:
++
+----
+project.logging.5dad9bd0-a7a1-11e6-94a0-5254000db84b.2016.11.14
+----
+
+The pattern for the `operations` logs remains the same.
+
+[IMPORTANT]
+====
+Downgrading from Elasticsearch 2.3 to Elasticsearch 1.x is not possible due to
+migration to a new data structure.
+====
+
 [[manual-upgrading-cluster-metrics]]
 == Upgrading Cluster Metrics