Uploaded image for project: 'Observability Documentation'
  1. Observability Documentation
  2. OBSDOCS-736

Fix cluster logging deployment documentation

XMLWordPrintable

    • Icon: Bug Bug
    • Resolution: Unresolved
    • Icon: Major Major
    • None
    • None
    • Logging
    • 13

      The cluster logging deployment documentation used to be a full walk through of how to install the cluster logging operator and its dependency, the ElasticSearch operator:
      https://docs.openshift.com/container-platform/4.10/logging/cluster-logging-deploying.html

      Not only was the instruction for installing the dependency removed from newer versions of our documentation:
      https://docs.openshift.com/container-platform/4.14/logging/cluster-logging-deploying.html

      But the new version of the documentation is actually contradicting itself:
      At the top, it states that "For new installations, use Vector and LokiStack. Elasticsearch and Fluentd are deprecated and are planned to be removed in a future release.".
      But then in section "Creating a ClusterLogging object by using the CLI" (https://docs.openshift.com/container-platform/4.14/logging/cluster-logging-deploying.html#create-cluster-logging-cli_cluster-logging-deploying), it lists the example for an elasticsearch configuration, and says under "Prerequisites": "You have installed the OpenShift ElasticSearch Operator for your log store".
      Then, a bit lower on the page, under "Configuring log storage", it says "You have installed the Red Hat OpenShift Logging Operator and an internal log store that is either the LokiStack or Elasticsearch." and gives the deprecation warning again (https://docs.openshift.com/container-platform/4.14/logging/cluster-logging-deploying.html#configuring-log-storage-cr_cluster-logging-deploying)

      IMO good documentation can be read from the top to the bottom by a senior administrator and copied and used by them without the intervention of consulting services.
      The end result is that they will get a basic configuration up and running, without having to jump back and forth through pages of (contradicting) documentation. Once a basic setup is configured, an administrator can then browse more specific subjects and adjust their configuration. That's what the old version of the documentation did.

      Right now, the logging documentation is incohesive and difficult to parse for anybody without thorough experience with the solution. It describes a lot of features, but not a single default working example. If Loki is our default, can we please provide the instructions for installing Loki with minimal dependencies, and the full ClusterLogging CR with Loki configuration, on a single page, with full working example configuration, exactly as we did in OCP 4.10? E.g., think of a fresh deployment with 3 master, 2 worker nodes: what are all the steps that I as an administrator have to take to get a working logging stack up and running?

      Addendum:

      What's also gone from the 4.14 documentation, but is present in the 4.10 documentation, are the GUI and CLI instructions for creating the openshift-operators-redhat namespace and operatorgroup:

      apiVersion: v1
      kind: Namespace
      metadata:
        name: openshift-operators-redhat 
        annotations:
          openshift.io/node-selector: ""
        labels:
          openshift.io/cluster-monitoring: "true" 
      ---
      apiVersion: operators.coreos.com/v1
      kind: OperatorGroup
      metadata:
        name: openshift-operators-redhat
        namespace: openshift-operators-redhat
      spec: {}
      

              Unassigned Unassigned
              akaris@redhat.com Andreas Karis
              Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

                Created:
                Updated: