Additional improvement for Logstash volumes documentation (elastic#7053…

…) (elastic#7074)

docs/orchestrating-elastic-stack-applications/logstash.asciidoc

@@ -289,10 +289,11 @@ NOTE: Logstash persistent queues (PQs) and dead letter queues (DLQs) are not cur
 === Defining data volumes for Logstash
 added:[2.9.0]
 
-WARNING: Volume support for Logstash is a breaking change to earlier versions of ECK and requires you to recreate your Logstash objects.
+WARNING: Volume support for Logstash is a breaking change to earlier versions of ECK and requires you to recreate your Logstash resources.
 
 
-[float]
+[id="{p}-volume-claim-settings"]
+[discrete]
 == Specifying the volume claim settings
 
 By default, a PersistentVolume called `logstash-data` is created, that maps to `/usr/share/logstash/data` for persistent storage, typically used for storage from plugins. The `logstash-data` volume claim is, by default, a small (1Gi) volume, using the standard StorageClass of your Kubernetes cluster, but can be overridden by adding a `spec.volumeClaimTemplate` section named `logstash-data`.
@@ -323,7 +324,7 @@ spec:
 
 Separate storage, for example for Logstash configurations using persistent queues (PQ) and/or dead letter queues (DLQ), can be added by including an additional `spec.volumeClaimTemplate` along with a corresponding `spec.podTemplate.spec.containers.volumeMount` for each requested volume.
 
-The following example shows how to setup separate storage for a PQ:
+This example shows how to setup separate storage for a PQ:
 
 
 [source,yaml,subs="attributes,+macros,callouts"]
@@ -360,7 +361,7 @@ spec:
 <2> Set the `path.queue` setting in the configuration to match the `mountPath` in the `volumeMount`.
 
 
-The following example shows how to configure Logstash with a Dead Letter Queue setup on the main pipeline, and a separate pipeline to read items from the DLQ.
+This example shows how to configure {ls} with a Dead Letter Queue setup on the main pipeline, and a separate pipeline to read items from the DLQ.
 
 [source,yaml,subs="attributes,+macros,callouts"]
 ----
@@ -434,14 +435,18 @@ spec:
 <2> Set the `path.dead_letter_queue` setting in the pipeline config to match the `mountPath` in the `volumeMount` for pipelines that are writing to the Dead Letter Queue, and set the `path` setting of the `dead_letter_queue` plugin for the pipeline that will read from the Dead Letter Queue.
 
 
-[float]
+[id="{p}-volume-claim-settings-updates"]
+[discrete]
 == Updating the volume claim settings
 
-Changes are currently forbidden in `spec.volumeClaimTemplates`, such as changing the storage class or volume size. To make these changes, you have to fully delete the Logstash object, delete and recreate or resize the volume and create a new Logstash resource.
+Changes, such as storage class or volume size, are currently forbidden in `spec.volumeClaimTemplates`.
+To make these changes, you have to fully delete the {ls} resource, delete and recreate or resize the volume, and create a new {ls} resource.
 
-Before deleting or resizing a persistent queue volume, ensure that the queue is empty. When using the persistent queue, we recommend setting `queue.drain: true` on the Logstash Pods to ensure that the persistent queue is drained when Pods are shutdown. In conjunction with this, note that you should also increase the `terminationGracePeriodSeconds` to a large enough value to drain your queue.
+Before deleting or resizing a persistent queue (PQ) volume, ensure that the queue is empty. 
+When using the PQ, we recommend setting `queue.drain: true` on the {ls} Pods to ensure that the queue is drained when Pods are shutdown. 
+Note that you should also increase the `terminationGracePeriodSeconds` to a large enough value to allow the queue to drain.
 
-The following example shows how to configure a Logstash resource to drain the queue and increase the termination grace period:
+This example shows how to configure a {ls} resource to drain the queue and increase the termination grace period.
 
 [source,yaml,subs="attributes,+macros,callouts"]
 ----
@@ -458,17 +463,29 @@ spec:
       terminationGracePeriodSeconds: 604800
 ----
 
-NOTE: A https://github.com/kubernetes/kubernetes/issues/94435[known issue] in Kubernetes, means that Kubernetes may not honor `terminationGracePeriodSeconds` settings greater than 600. This may mean that a queue of a terminated Pod may not be fully drained, even when `queue.drain: true` is set and a high `terminationGracePeriodSeconds` is configured.
+NOTE: A https://github.com/kubernetes/kubernetes/issues/94435[{k8s} known issue]: {k8s} may not honor `terminationGracePeriodSeconds` settings greater than 600. 
+A queue of a terminated Pod may not be fully drained, even when `queue.drain: true` is set and a high `terminationGracePeriodSeconds` is configured.
 
-NOTE: In the technical preview, there is currently no way to drain a dead letter queue automatically before Logstash shuts down. To manually drain a Dead Letter Queue, first stop sending data to it, by either disabling the DLQ feature, or disabling any pipelines that send to a DLQ, and wait for events to stop flowing through any pipelines reading from the input.
+NOTE: In this technical preview, there is currently no way to drain a dead letter queue (DLQ) automatically before {ls} shuts down. 
+To manually drain the queue, first stop sending data to it, by either disabling the DLQ feature, or disabling any pipelines that send to a DLQ. 
+Then wait for events to stop flowing through any pipelines reading from the input.
 
 
-[float]
+[id="{p}-emptydir"]
+[discrete]
 == EmptyDir
 
 If you are not concerned about data loss, you can use an `emptyDir` volume for Logstash data.
 
-CAUTION: The use of `emptyDir` in a production environment may generate permanent data loss. Do not use with persistent queues, or dead letter queues, or when using any plugin that requires persistent storage to keep track of state between restarts of Logstash.
+[CAUTION]
+--
+The use of `emptyDir` in a production environment may cause permanent data loss. 
+Do not use with persistent queues (PQs), dead letter queues (DLQs), or with any plugin that requires persistent storage to keep track of state between restarts of {ls}.
+
+Plugins that require persistent storage include any plugin that stores state locally. 
+These plugins typically have a configuration parameter that includes the name `path` or `directory`, not including paths to static content, such as certificates or keystores.
+Examples include the `sincedb_path` setting for the `file`, `dead_letter_queue` and `s3` inputs, the `last_run_metadata_path` for the `JDBC` input, `aggregate_maps_path` for the `aggregate` filter, and `temporary_directory` for the `s3` output, used to aggregate content before uploading to s3.
+--
 
 
 [source,yaml]
@@ -736,14 +753,19 @@ kubectl apply -f {logstash_recipes}/logstash-es-role.yaml
 Deploys Logstash and Elasticsearch, and creates an updated version of the `eck_logstash_user_role` to write to a user specified index.
 
 [id="{p}-logstash-configuration-pq-dlq"]
-=== Creating persitent volumes for PQ and DLQ
+=== Creating persistent volumes for PQ and DLQ
 
 [source,sh,subs="attributes"]
 ----
 kubectl apply -f {logstash_recipes}/logstash-volumes.yaml
 ----
 
-Deploys Logstash, Beats and Elasticsearch. Logstash is configured with two pipelines - a main pipeline for reading from the Beats instance, which will send to the DLQ if it is unable to write to Elasticsearch, and a second pipeline, that will read from the DLQ. In addition, persistent queues are set up. This example shows how to configure persistent volumes outside of the default `logstash-data` persistent volume.
+Deploys Logstash, Beats and Elasticsearch. Logstash is configured with two pipelines:
+
+* a main pipeline for reading from the {beats} instance, which will send to the DLQ if it is unable to write to Elasticsearch
+* a second pipeline, that will read from the DLQ. 
+In addition, persistent queues are set up. 
+This example shows how to configure persistent volumes outside of the default `logstash-data` persistent volume.
 
 
 [id="{p}-logstash-configuration-stack-monitoring"]
@@ -834,11 +856,17 @@ Note that this release is a technical preview. It is still under active developm
 
 [id="{p}-logstash-technical-preview-persistence"]
 === Experimental support for persistence
-NOTE: This is a breaking change from version 2.8.0 of the ECK operator and requires re-creation of existing Logstash objects.
+NOTE: Persistence (experimental) is a breaking change from version 2.8.0 of the ECK operator and requires re-creation of existing {ls} resources.
 
-The operator now includes support for persistence, with a small (`1Gi`) default `PersistentVolume` called `logstash-data` created, that maps to `/usr/share/logstash/data`, which should be typically used for storage from plugins. The default volume can be overridden by adding a `spec.volumeClaimTemplate` section named `logstash-data` to add more storage, or to use a different `storageClass` from the default, for example. Additional `persistentVolumeClaims` can also be defined in `spec.volumeClaimTemplate` for use with PQ, or DLQ, for example.
+The operator now includes support for persistence.
+It creates a small (`1Gi`) default `PersistentVolume` called `logstash-data` that maps to `/usr/share/logstash/data`, typically used for storage from plugins. 
+The default volume can be overridden by adding a `spec.volumeClaimTemplate` section named `logstash-data` to add more storage, or to use a different `storageClass` from the default, for example. 
+You can define additional `persistentVolumeClaims` in `spec.volumeClaimTemplate` for use with PQ, or DLQ, for example.
 
-The current implementation does not allow resizing of volumes even if your chosen storage class would support it. To resize a volume you have to fully delete the Logstash object, delete and recreate or resize the volume and create a new Logstash object. Also note that volume claims will not be deleted when you delete the Logstash resource and have to be deleted manually. This behaviour might change in future versions of the ECK operator.
+The current implementation does not allow resizing of volumes, even if your chosen storage class would support it. 
+To resize a volume, delete the {ls} resource, delete and recreate (or resize) the volume, and create a new {ls} resource. 
+Note that volume claims will not be deleted when you delete the {ls} resource, and must be deleted manually. 
+This behavior might change in future versions of the ECK operator.
 
 [id="{p}-logstash-technical-preview-elasticsearchref"]
 === `ElasticsearchRef` implementation in plugins is in preview mode