Manual CP of RHDEVDOCS-2603 #29378

modules/cluster-logging-collector-legacy-fluentd.adoc

@@ -0,0 +1,119 @@
+// Module included in the following assemblies:
+//
+// * logging/cluster-logging-external.adoc
+
+[id="cluster-logging-collector-legacy-fluentd_{context}"]
+= Forwarding logs using the legacy Fluentd method
+
+You can use the Fluentd *forward* protocol to send logs to destinations outside of your {product-title} cluster instead of the default Elasticsearch log store by creating a configuration file and config map. You are responsible for configuring the external log aggregator to receive the logs from {product-title}.
+
+[IMPORTANT]
+====
+This method for forwarding logs is deprecated in {product-title} and will be removed in a future release.
+====
+
+ifdef::openshift-origin[]
+The *forward* protocols are provided with the Fluentd image as of v1.4.0.
+endif::openshift-origin[]
+
+To send logs using the Fluentd *forward* protocol, create a configuration file called `secure-forward.conf`, that points to an external log aggregator. Then, use that file to create a config map called called `secure-forward` in the `openshift-logging` project, which {product-title} uses when forwarding the logs.
+
+.Sample Fluentd configuration file
+
+[source,yaml]
+----
+<store>
+  @type forward
+  <security>
+    self_hostname ${hostname}
+    shared_key "fluent-receiver"
+  </security>
+  transport tls
+  tls_verify_hostname false
+  tls_cert_path '/etc/ocp-forward/ca-bundle.crt'
+  <buffer>
+    @type file
+    path '/var/lib/fluentd/secureforwardlegacy'
+    queued_chunks_limit_size "1024"
+    chunk_limit_size "1m"
+    flush_interval "5s"
+    flush_at_shutdown "false"
+    flush_thread_count "2"
+    retry_max_interval "300"
+    retry_forever true
+    overflow_action "exception"
+  </buffer>
+  <server>
+    host fluent-receiver.example.com
+    port 24224
+  </server>
+</store>
+----
+
+.Procedure
+
+To configure {product-title} to forward logs using the legacy Fluentd method:
+
+. Create a configuration file named `secure-forward` and specify parameters similar to the following within the `<store>` stanza:
++
+[source,yaml]
+----
+<store>
+  @type forward
+  <security>
+    self_hostname ${hostname}
+    shared_key <key> <1>
+  </security>
+  transport tls <2>
+  tls_verify_hostname <value> <3>
+  tls_cert_path <path_to_file> <4>
+  <buffer> <5>
+    @type file
+    path '/var/lib/fluentd/secureforwardlegacy'
+    queued_chunks_limit_size "#{ENV['BUFFER_QUEUE_LIMIT'] || '1024' }"
+    chunk_limit_size "#{ENV['BUFFER_SIZE_LIMIT'] || '1m' }"
+    flush_interval "#{ENV['FORWARD_FLUSH_INTERVAL'] || '5s'}"
+    flush_at_shutdown "#{ENV['FLUSH_AT_SHUTDOWN'] || 'false'}"
+    flush_thread_count "#{ENV['FLUSH_THREAD_COUNT'] || 2}"
+    retry_max_interval "#{ENV['FORWARD_RETRY_WAIT'] || '300'}"
+    retry_forever true
+    overflow_action "#{ENV['BUFFER_QUEUE_FULL_ACTION'] || 'exception'}"
+  </buffer>
+  <server>
+    name <6>
+    host <7>
+    hostlabel <8>
+    port <9>
+  </server>
+  <server> <10>
+    name
+    host
+  </server>
+----
+<1> Enter the shared key between nodes.
+<2> Specify `tls` to enable TLS validation.
+<3> Set to `true` to verify the server cert host name. Set to `false` to ignore server cert host name.
+<4> Specify the path to the private CA certificate file as `/etc/ocp-forward/ca_cert.pem`.
+<5> Specify the link:https://docs.fluentd.org/configuration/buffer-section[Fluentd buffer parameters] as needed.
+<6> Optionally, enter a name for this server.
+<7> Specify the host name or IP of the server.
+<8> Specify the host label of the server.
+<9> Specify the port of the server.
+<10> Optionally, add additional servers.
+If you specify two or more servers, *forward* uses these server nodes in a round-robin order.
++
+To use Mutual TLS (mTLS) authentication, see the link:https://docs.fluentd.org/output/forward#tips-and-tricks[Fluentd documentation] for information about client certificate, key parameters, and other settings.
+
+. Create a config map named `secure-forward` in the `openshift-logging` project from the configuration file:
++
+[source,terminal]
+----
+$ oc create configmap secure-forward --from-file=secure-forward.conf -n openshift-logging
+----
+
+The Cluster Logging Operator redeploys the Fluentd pods. If the pods do not redeploy, you can delete the Fluentd pods to force them to redeploy.
+
+[source,terminal]
+----
+$ oc delete pod --selector logging-infra=fluentd
+----