openshift-docs/modules/efk-logging-deploy-subscription.adoc

// Module included in the following assemblies:
//
// * logging/efk-logging-deploy.adoc

[id="efk-logging-deploy-subscription_{context}"]
= Installing the Cluster Logging and Elasticsearch Operators

You can use the {product-title} console to install cluster logging, by deploying,
the Cluster Logging and Elasticsearch Operators.  The Cluster Logging Operator
creates and manages the components of the logging stack.  The Elasticsearch Operator
creates and manages the Elasticsearch cluster used by cluster logging.

[NOTE]
====
The {product-title} cluster logging solution requires that you install both the
Cluster Logging Operator and Elasticsearch Operator. There is no use case
in {product-title} for installing the operators individually.
You *must* install the Elasticsearch Operator using the CLI following the directions below.
You can install the Cluster Logging Operator using the web console or CLI.
====

.Prerequisites

Ensure that you have the necessary persistent storage for Elasticsearch. Note that each Elasticsearch node
requires its own storage volume.
+
Elasticsearch is a memory-intensive application. Each Elasticsearch node needs 16G of memory for both memory requests and CPU limits.
The initial set of {product-title} nodes might not be large enough to support the Elasticsearch cluster. You must add additional nodes to the
{product-title} cluster to run with the recommended or higher memory. Each Elasticsearch node can operate with a lower
memory setting though this is not recommended for production deployments.

[NOTE]
====
You *must* install the Elasticsearch Operator using the CLI following the directions below.
You can install the Cluster Logging Operator using the web console or CLI.
====


.Procedure

. Create Namespaces for the Elasticsearch Operator and Cluster Logging Operator.
+
[NOTE]
====
You can also create the Namespaces in the web console using the *Administration* -> *Namespaces* page.
You must apply the `cluster-logging` and `cluster-monitoring` labels listed in the sample YAML to the namespaces you create.
====

.. Create a Namespace for the Elasticsearch Operator (for example, `eo-namespace.yaml`):
+
----
apiVersion: v1
kind: Namespace
metadata:
  name: openshift-operators-redhat <1>
  annotations:
    openshift.io/node-selector: ""
  labels:
    openshift.io/cluster-logging: "true"
    openshift.io/cluster-monitoring: "true"
----
<1> You must specify the `openshift-operators-redhat` namespace.

.. Run the following command to create the namespace:
+
----
$ oc create -f <file-name>.yaml
----
+
For example:
+
----
$ oc create -f eo-namespace.yaml
----

.. Create a Namespace for the Cluster Logging Operator (for example, `clo-namespace.yaml`):
+
[source,yaml]
----
apiVersion: v1
kind: Namespace
metadata:
  name: openshift-logging
  annotations:
    openshift.io/node-selector: "" <1>
  labels:
    openshift.io/cluster-logging: "true"
    openshift.io/cluster-monitoring: "true"
----
<1> Optionally specify an empty node selector in order for the logging pods to spread
evenly across your cluster. If you want the logging pods to run on specific nodes, you can specify a node selector value here.

.. Run the following command to create the namespace:
+
----
$ oc create -f <file-name>.yaml
----
+
For example:
+
----
$ oc create -f clo-namespace.yaml
----

. Install the Elasticsearch Operator by creating the following objects:

.. Create an Operator Group object YAML file (for example, `eo-og.yaml`) for the Elasticsearch operator:
+
----
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: openshift-operators-redhat
  namespace: openshift-operators-redhat <1>
spec: {}
----
<1> You must specify the `openshift-operators-redhat` namespace.

.. Create an Operator Group object:
+
----
$ oc create -f <file-name>.yaml
----
+
For example:
+
----
$ oc create -f eo-og.yaml
----

.. Use the following command to get the `channel` value required for the next step.
+
----
$ oc get packagemanifest elasticsearch-operator -n openshift-marketplace -o jsonpath='{.status.channels[].name}'

preview
----

.. Create a Subscription object YAML file (for example, `eo-sub.yaml`) to
subscribe a Namespace to an Operator.
+
.Example Subscription
[source,yaml]
----
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  generateName: "elasticsearch-"
  namespace: "openshift-operators-redhat" <1>
spec:
  channel: "4.2" <2>
  installPlanApproval: "Automatic"
  source: "redhat-operators"
  sourceNamespace: "openshift-marketplace"
  name: "elasticsearch-operator"
----
<1> You must specify the `openshift-operators-redhat` namespace.
<2> Specify the `.status.channels[].name` value from the previous step.

.. Create the Subscription object:
+
----
$ oc create -f <file-name>.yaml
----
+
For example:
+
----
$ oc create -f eo-sub.yaml
----

.. Change to the `openshift-operators-redhat` project:
+
----
$ oc project openshift-operators-redhat

Now using project "openshift-operators-redhat"
----

.. Create a Role-based Access Control (RBAC) object file (for example, `eo-rbac.yaml`) to grant Prometheus permission to access the `openshift-operators-redhat` namespace:
+
[source,yaml]
----
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: prometheus-k8s
  namespace: openshift-operators-redhat
rules:
- apiGroups:
  - ""
  resources:
  - services
  - endpoints
  - pods
  verbs:
  - get
  - list
  - watch
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: prometheus-k8s
  namespace: openshift-operators-redhat
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: prometheus-k8s
subjects:
- kind: ServiceAccount
  name: prometheus-k8s
namespace: openshift-operators-redhat
----

.. Create the RBAC object:
+
----
$ oc create -f eo-rbac.yaml
----
+
The Elasticsearch operator is installed to the `openshift-operators-redhat` namespace and copied to each project in the cluster.

. Install the Cluster Logging Operator using the {product-title} web console for best results:

.. In the {product-title} web console, click *Operators* -> *OperatorHub*.

.. Choose  *Cluster Logging* from the list of available Operators, and click *Install*.

.. On the *Create Operator Subscription* page, under *A specific namespace on the cluster* select *openshift-logging*.
Then, click *Subscribe*.

. Verify the operator installations:

.. Switch to the *Operators* → *Installed Operators* page.

.. Ensure that *Cluster Logging* and *Elasticsearch Operator* are listed on
the *InstallSucceeded* tab with a *Status* of *InstallSucceeded*. Change the project to *all projects* if necessary.
+
[NOTE]
====
During installation an operator might display a *Failed* status. If the operator then installs with an *InstallSucceeded* message,
you can safely ignore the *Failed* message.
====
+
If either operator does not appear as installed, to troubleshoot further:
+
* Switch to the *Operators* → *Installed Operators* page and inspect
the *Status* column for any errors or failures.
* Switch to the *Workloads* → *Pods* page and check the logs in any Pods in the
`openshift-logging` and `openshift-operators-redhat` projects that are reporting issues.

. Create a cluster logging instance:

.. Switch to the the *Administration* -> *Custom Resource Definitions* page.

.. On the *Custom Resource Definitions* page, click *ClusterLogging*.

.. On the *Custom Resource Definition Overview* page, select *View Instances* from the *Actions* menu.

.. On the *Cluster Loggings* page, click *Create Cluster Logging*.
+
You might have to refresh the page to load the data.

.. In the YAML, replace the code with the following:
+
[NOTE]
====
This default cluster logging configuration should support a wide array of environments. Review the topics on tuning and
configuring the cluster logging components for information on modifications you can make to your cluster logging cluster.
====
+
[source,yaml]
----
apiVersion: "logging.openshift.io/v1"
kind: "ClusterLogging"
metadata:
  name: "instance" <1>
  namespace: "openshift-logging"
spec:
  managementState: "Managed"  <2>
  logStore:
    type: "elasticsearch"  <3>
    elasticsearch:
      nodeCount: 3 <4>
      storage:
        storageClassName: gp2
        size: 200G
      redundancyPolicy: "SingleRedundancy"
  visualization:
    type: "kibana"  <5>
    kibana:
      replicas: 1
  curation:
    type: "curator"  <6>
    curator:
      schedule: "30 3 * * *"
  collection:
    logs:
      type: "fluentd"  <7>
      fluentd: {}
----
<1> The name of the CR. This must be `instance`.
<2> The cluster logging management state. In most cases, if you change the default cluster logging defaults, you must set this to `Unmanaged`.
However, an unmanaged deployment does not receive updates until the cluster logging is placed back into a managed state. For more information, see *Changing cluster logging management state*.
<3> Settings for configuring Elasticsearch. Using the CR, you can configure shard replication policy and persistent storage. For more information, see *Configuring Elasticsearch*.
<4> Specify the number of Elasticsearch nodes. See the note that follows this list.
<5> 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 Kibana*.
<6> Settings for configuring Curator. Using the CR, you can set the Curator schedule. For more information, see *Configuring Curator*.
<7> 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 master nodes is three. If you specify a `nodeCount` greater than `3`, {product-title} 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. Master 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

cluster-logging-operator       1/1     1            1           18h
elasticsearch-cd-x6kdekli-1    0/1     1            0           6m54s
elasticsearch-cdm-x6kdekli-1   1/1     1            1           18h
elasticsearch-cdm-x6kdekli-2   0/1     1            0           6m49s
elasticsearch-cdm-x6kdekli-3   0/1     1            0           6m44s
----
====

.. Click *Create*. This creates the Cluster Logging Custom Resource and Elasticsearch Custom Resource, which you
can edit to make changes to your cluster logging cluster.

. Verify the install:

.. Switch to the *Workloads* -> *Pods* page.

.. Select the *openshift-logging* project.
+
You should see several pods for cluster logging, Elasticsearch, Fluentd, and Kibana similar to the following list:
+
* cluster-logging-operator-cb795f8dc-xkckc
* elasticsearch-cdm-b3nqzchd-1-5c6797-67kfz
* elasticsearch-cdm-b3nqzchd-2-6657f4-wtprv
* elasticsearch-cdm-b3nqzchd-3-588c65-clg7g
* fluentd-2c7dg
* fluentd-9z7kk
* fluentd-br7r2
* fluentd-fn2sb
* fluentd-pb2f8
* fluentd-zqgqx
* kibana-7fb4fd4cc9-bvt4p
+
.. Switch to the *Workloads* -> *Pods* page.