Merge remote-tracking branch 'mssola/logging' into master

adoc/admin-centralized-logging.adoc → adoc/admin-logging-centralized.adoc

@@ -1,3 +1,4 @@
+[#centralized-logging]
 = Centralized Logging
 
 Centralized Logging is a means of collecting logs from the {productname} for centralized management.

adoc/admin-logging-skuba.adoc

@@ -0,0 +1,39 @@
+[#tee-logging]
+= Logging in skuba
+
+One important part of deploying and maintaining a product is to have reliable
+logs. Tools like `skuba` take the approach of printing the output to the
+standard output directly. This is not just common practice, but it also has the
+advantage that then the user has more flexibility on how to manage said output.
+
+Thus, whenever throughout this guide we write a `skuba` command, take into
+account that the output will be printed into the standard output. If you would
+also like to have the logs stored somewhere else for later inspection, you can
+use tools like `tee`. For example:
+
+[source,bash]
+----
+skuba node bootstrap --user sles --sudo --target <IP/FQDN> <NODE_NAME> | tee <NODE_NAME>-skuba-node-bootstrap.log
+----
+
+Otherwise, you might want to use other tools to manage the logs for later
+inspection. The point being that this guide will never consider how to manage
+these logs because `skuba` itself does not. It's up to you to manage these logs
+in any way you find desirable.
+
+Moreover, `skuba` has also various levels of log verbosity. This is managed by
+the `-v, --verbosity` flag. This flag accepts an integer argument, ranging from
+0 to 5, where a higher number means a higher level of verbosity. If you don't
+pass any arguments, then 0 is assumed. We recommend using the default argument,
+since it will already log warnings and errors, among other relevant output,
+whereas 5 can be a bit overwhelming. Thus, for the above example, we would
+recommend something like:
+
+[source,bash]
+----
+skuba node bootstrap -v --user sles --sudo --target <IP/FQDN> <NODE_NAME> | tee <NODE_NAME>-skuba-node-bootstrap.log
+----
+
+Now the `<NODE_NAME>-skuba-node-bootstrap.log` will have more useful information
+than without the `-v` flag. We *strongly* recommend using this flag in order to
+get as much useful information as possible from a single run.

adoc/admin-logging.adoc

@@ -0,0 +1,17 @@
+== Introduction
+
+Logging is ubiquitous throughout {productname}. Some tools will only print their
+outputs to the currently running session shell and not create a "log file".
+
+If you need to retain the output of these files you can `tee` them into a separate file (refer to <<tee-logging>>).
+
+Many other service components will produce log files or other log info streams.
+You can collect, store and evaluate these logs via <<centralized-logging>> for
+use with the <<monitoring-stack>>.
+
+
+
+[NOTE]
+====
+If you are looking for troubleshooting logs please refer to <<troubleshooting-logs>>.
+====

adoc/admin-troubleshooting.adoc

@@ -73,6 +73,7 @@ tar -czvf cluster.tar.gz /home/user/my-terraform-configuration/
 
 After opening a Service Request (SR), you can upload the `TAR` archive to {suse} Global Technical Support.
 
+[#troubleshooting-logs]
 == Log collection
 
 Some of these information are required for debugging certain cases. The data collected by

adoc/book_admin.adoc

@@ -40,6 +40,10 @@ include::admin-cluster-management.adoc[Cluster management,leveloffset=+1]
 
 include::admin-software-installation.adoc[Software Installation,leveloffset=+2]
 
+== Cluster Updates
+
+include::admin-updates.adoc[Cluster Updates,leveloffset=+1]
+
 == Security
 
 include::admin-security-firewall.adoc[Network Access Considerations,leveloffset=+2]
@@ -62,9 +66,15 @@ include::admin-security-admission.adoc[Admission Controller,leveloffset=+2]
 
 include::admin-security-certificates.adoc[Certificates,leveloffset=+2]
 
-== Cluster Updates
+== Logging
 
-include::admin-updates.adoc[Cluster Updates,leveloffset=+1]
+include::admin-logging.adoc[Logging,leveloffset=+1]
+
+include::admin-logging-skuba.adoc[leveloffset=+2]
+
+include::admin-logging-audit.adoc[leveloffset=+2]
+
+include::admin-logging-centralized.adoc[leveloffset=+2]
 
 == Monitoring
 
@@ -76,12 +86,6 @@ include::admin-monitoring-horizontal-pod-autoscaler.adoc[Horizontal Pod Autoscal
 
 include::admin-stratos-web-console.adoc[Stratos Web Console, leveloffset=+2]
 
-== Logging
-
-include::admin-audit.adoc[leveloffset=+2]
-
-include::admin-centralized-logging.adoc[leveloffset=+2]
-
 == Storage
 
 include::admin-storage-vsphere.adoc[leveloffset=+2]

adoc/book_deployment.adoc

@@ -30,6 +30,7 @@ include::common_intro_feedback.adoc[Feedback,leveloffset=+2]
 
 include::common_intro_typography.adoc[leveloffset=+2]
 
+include::common_log.adoc[Logging,leveloffset=+2]
 
 //System requirements
 include::deployment-sysreqs.adoc[System Requirements]

adoc/deployment-bootstrap.adoc

@@ -527,7 +527,16 @@ This will restart all `kured` pods with the additional configuration flags.
 For `--target` enter the FQDN of your first master node.
 Replace `<NODE_NAME>` with a unique identifier, for example, "master-one".
 +
-.Custom root CA certificate
+.Log retention
+[NOTE]
+====
+By default skuba will only display the events of the bootstrap process in the terminal during execution.
+The examples in the following sections will use the `tee` tool to store a copy of the outputs in a file of your choosing.
+
+For more information on the different logging approaches utilized by {productname} components please refer to: link:{docurl}single-html/caasp-admin/#_logging[SUSE CaaS Platform - Admin Guide: Logging].
+====
++
+.Custom Trusted CA Certificate
 [TIP]
 ====
 During cluster bootstrap, `skuba` automatically generates a root CA certificate.
@@ -546,7 +555,7 @@ cluster to replace.
 [source,bash]
 ----
 cd my-cluster
-skuba node bootstrap --user sles --sudo --target <IP/FQDN> <NODE_NAME>
+skuba node bootstrap --user sles --sudo --target <IP/FQDN> <NODE_NAME> | tee <NODE_NAME>-skuba-node-bootstrap.log
 ----
 This will bootstrap the specified node as the first master in the cluster.
 The process will generate authentication certificates and the `admin.conf`
@@ -559,7 +568,7 @@ Replace `<NODE_NAME>` with a unique identifier, for example, "master-two".
 +
 [source,bash]
 ----
-skuba node join --role master --user sles --sudo --target <IP/FQDN> <NODE_NAME>
+skuba node join --role master --user sles --sudo --target <IP/FQDN> <NODE_NAME>| tee <NODE_NAME>-skuba-node-join.log
 ----
 . Add a worker to the cluster:
 +
@@ -568,7 +577,7 @@ Replace `<NODE_NAME>` with a unique identifier, for example, "worker-one".
 +
 [source,bash]
 ----
-skuba node join --role worker --user sles --sudo --target <IP/FQDN> <NODE_NAME>
+skuba node join --role worker --user sles --sudo --target <IP/FQDN> <NODE_NAME>| tee <NODE_NAME>-skuba-node-join.log
 ----
 . Verify that the nodes have been added:
 +