Chapter 5. Installing Logging

Procedure

1. In the OpenShift Container Platform web console, click Operators OperatorHub.
2. Type OpenShift Logging in the Filter by keyword box.
3. Choose Red Hat OpenShift Logging from the list of available Operators, and click Install.
4. Ensure that A specific namespace on the cluster is selected under Installation mode.
5. Ensure that Operator recommended namespace is openshift-logging under Installed Namespace.

6. Select Enable operator recommended cluster monitoring on this namespace.

   This option sets the openshift.io/cluster-monitoring: "true" label in the Namespace object. You must select this option to ensure that cluster monitoring scrapes the openshift-logging namespace.

7. Select stable-5.y as the Update channel.

   Note

   The stable channel only provides updates to the most recent release of logging. To continue receiving updates for prior releases, you must change your subscription channel to stable-x.y, where x.y represents the major and minor version of logging you have installed. For example, stable-5.7.

8. Select an Update approval.

   • The Automatic strategy allows Operator Lifecycle Manager (OLM) to automatically update the Operator when a new version is available.
   • The Manual strategy requires a user with appropriate credentials to approve the Operator update.
9. Select Enable or Disable for the Console plugin.
10. Click Install.

Verification

1. Verify that the Red Hat OpenShift Logging Operator is installed by switching to the Operators Installed Operators page.
2. In the Status column, verify that you see green checkmarks with InstallSucceeded and the text Up to date.

Procedure

1. Navigate to the Custom Resource Definitions page.
2. On the Custom Resource Definitions page, click ClusterLogging.
3. On the Custom Resource Definition details page, select View Instances from the Actions menu.
4. On the ClusterLoggings page, click Create ClusterLogging.

5. In the collection section, select a Collector Implementation.

   Note

   Fluentd is deprecated and is planned to be removed in a future release. Red Hat provides bug fixes and support for this feature during the current release lifecycle, but this feature no longer receives enhancements. As an alternative to Fluentd, you can use Vector instead.

6. In the logStore section, select a type.

   Note

   The Logging 5.9 release does not contain an updated version of the OpenShift Elasticsearch Operator. If you currently use the OpenShift Elasticsearch Operator released with Logging 5.8, it will continue to work with Logging until the EOL of Logging 5.8. As an alternative to using the OpenShift Elasticsearch Operator to manage the default log storage, you can use the Loki Operator. For more information on the Logging lifecycle dates, see Platform Agnostic Operators.

7. Click Create.

Procedure

1. Create a Namespace object as a YAML file:

   Example Namespace object

   apiVersion: v1
   kind: Namespace
   metadata:
     name: <name> 1
     annotations:
       openshift.io/node-selector: ""
     labels:
       openshift.io/cluster-monitoring: "true"

   1

   You must specify openshift-logging as the name of the namespace for logging versions 5.7 and earlier versions. For logging 5.8 and later versions, you can use any name.

2. Apply the Namespace object by running the following command:

   $ oc apply -f <filename>.yaml

3. Create an OperatorGroup object as a YAML file:

   Example OperatorGroup object

   apiVersion: operators.coreos.com/v1
   kind: OperatorGroup
   metadata:
     name: cluster-logging
     namespace: openshift-logging 1
   spec:
     targetNamespaces: [ ] 2

   1

   Ensure that the namespace field is set to openshift-logging.

   2

   For logging versions 5.7 and earlier, set targetNamespaces to openshift-logging. For logging versions 5.8 and later, the default installation mode is all namespaces on the cluster, or specify a list of namespaces separated by a comma.

4. Apply the OperatorGroup object by running the following command:

   $ oc apply -f <filename>.yaml

5. Create a Subscription object to subscribe the namespace to the Red Hat OpenShift Logging Operator:

   Example Subscription object

   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: cluster-logging
     namespace: openshift-logging 1
   spec:
     channel: stable 2
     name: cluster-logging
     source: redhat-operators 3
     sourceNamespace: openshift-marketplace

   1

   You must specify the openshift-logging namespace for logging versions 5.7 and older. For logging 5.8 and later versions, you can use any namespace.

   2

   Specify stable or stable-x.y as the channel.

   3

   Specify redhat-operators. If your OpenShift Container Platform cluster is installed on a restricted network, also known as a disconnected cluster, specify the name of the CatalogSource object you created when you configured the Operator Lifecycle Manager (OLM).

6. Apply the subscription by running the following command:

   $ oc apply -f <filename>.yaml

   The Red Hat OpenShift Logging Operator is installed to the openshift-logging namespace.

Verification

1. Run the following command:

   $ oc get csv -n <namespace>

2. Observe the output and confirm that the Red Hat OpenShift Logging Operator exists in the namespace:

   Example output

   NAMESPACE                                               NAME                                         DISPLAY                  VERSION               REPLACES   PHASE
   ...
   openshift-logging                                       clusterlogging.5.8.0-202007012112.p0         OpenShift Logging          5.8.0-202007012112.p0              Succeeded
   ...

Procedure

1. Create a ClusterLogging object as a YAML file:

   Example ClusterLogging object

   apiVersion: logging.openshift.io/v1
   kind: ClusterLogging
   metadata:
     name: instance 1
     namespace: openshift-logging
   spec:
     managementState: Managed 2
     logStore:
       type: elasticsearch 3
       retentionPolicy: 4
         application:
           maxAge: 1d
         infra:
           maxAge: 7d
         audit:
           maxAge: 7d
       elasticsearch:
         nodeCount: 3 5
         storage:
           storageClassName: <storage_class_name> 6
           size: 200G
         resources: 7
             limits:
               memory: 16Gi
             requests:
               memory: 16Gi
         proxy: 8
           resources:
             limits:
               memory: 256Mi
             requests:
               memory: 256Mi
         redundancyPolicy: SingleRedundancy
     visualization:
       type: kibana 9
       kibana:
         replicas: 1
     collection:
       type: fluentd 10
       fluentd: {}

   1

   The name must be instance.

   2

   The OpenShift Logging management state. In some cases, if you change the OpenShift Logging defaults, you must set this to Unmanaged. However, an unmanaged deployment does not receive updates until OpenShift Logging is placed back into a managed state.

   3

   Settings for configuring Elasticsearch. Using the CR, you can configure shard replication policy and persistent storage.

   4

   Specify the length of time that Elasticsearch should retain each log source. Enter an integer and a time designation: weeks(w), hours(h/H), minutes(m) and seconds(s). For example, 7d for seven days. Logs older than the maxAge are deleted. You must specify a retention policy for each log source or the Elasticsearch indices will not be created for that source.

   5

   Specify the number of Elasticsearch nodes. See the note that follows this list.

   6

   Enter the name of an existing storage class for Elasticsearch storage. For best performance, specify a storage class that allocates block storage. If you do not specify a storage class, OpenShift Logging uses ephemeral storage.

   7

   Specify the CPU and memory requests for Elasticsearch as needed. If you leave these values blank, the OpenShift Elasticsearch Operator sets default values that should be sufficient for most deployments. The default values are 16Gi for the memory request and 1 for the CPU request.

   8

   Specify the CPU and memory requests for the Elasticsearch proxy as needed. If you leave these values blank, the OpenShift Elasticsearch Operator sets default values that should be sufficient for most deployments. The default values are 256Mi for the memory request and 100m for the CPU request.

   9

   Settings for configuring Kibana. Using the CR, you can scale Kibana for redundancy and configure the CPU and memory for your Kibana nodes. For more information, see Configuring the log visualizer.

   10

   Settings for configuring Fluentd. Using the CR, you can configure Fluentd CPU and memory limits. For more information, see "Configuring Fluentd".

   Note

   The maximum number of Elasticsearch control plane nodes is three. If you specify a nodeCount greater than 3, OpenShift Container Platform creates three Elasticsearch nodes that are Master-eligible nodes, with the master, client, and data roles. The additional Elasticsearch nodes are created as data-only nodes, using client and data roles. Control plane nodes perform cluster-wide actions such as creating or deleting an index, shard allocation, and tracking nodes. Data nodes hold the shards and perform data-related operations such as CRUD, search, and aggregations. Data-related operations are I/O-, memory-, and CPU-intensive. It is important to monitor these resources and to add more Data nodes if the current nodes are overloaded.

   For example, if nodeCount=4, the following nodes are created:

   $ oc get deployment

   Example output

   NAME                           READY   UP-TO-DATE   AVAILABLE   AGE
   cluster-logging-operator       1/1     1            1           18h
   elasticsearch-cd-x6kdekli-1    1/1     1            1          6m54s
   elasticsearch-cdm-x6kdekli-1   1/1     1            1           18h
   elasticsearch-cdm-x6kdekli-2   1/1     1            1           6m49s
   elasticsearch-cdm-x6kdekli-3   1/1     1            1           6m44s

   The number of primary shards for the index templates is equal to the number of Elasticsearch data nodes.