Corrects Service Mesh for DITA migration

modules/ossm-config-default.adoc

@@ -6,7 +6,8 @@
 [id="ossm-config-default_{context}"]
 = Distributed tracing default configuration options
 
-The Jaeger custom resource (CR) defines the architecture and settings to be used when creating the {JaegerShortName} resources. You can modify these parameters to customize your {JaegerShortName} implementation to your business needs.
+[role="_abstract"]
+See the Jaeger custom resource (CR) for a description for building your {JaegerShortName}. Change the fields to match what you need.
 
 .Generic YAML example of the Jaeger CR
 [source,yaml]
@@ -67,7 +68,7 @@ spec:
 
 |`spec:`
 |Specification for the object to be created.
-|Contains all of the configuration parameters for your {JaegerShortName} instance. When a common definition for all Jaeger components is required, it is defined under the `spec` node. When the definition relates to an individual component, it is placed under the `spec/<component>` node.
+|Lists all settings for your {JaegerShortName} instance. Put shared settings under `spec`. Put settings for one part under `spec/<component>`.
 |N/A
 
 |`strategy:`

modules/ossm-config-ingester.adoc

@@ -6,7 +6,8 @@
 [id="ossm-config-ingester_{context}"]
 = Ingester configuration options
 
-Ingester is a service that reads from a Kafka topic and writes to the Elasticsearch storage backend. If you are using the `allInOne` or `production` deployment strategies, you do not need to configure the Ingester service.
+[role="_abstract"]
+Use the Ingester to read data from a Kafka topic and to write data to Elasticsearch. You do not need the Ingester for `allInOne` or `production` strategies.
 
 .Jaeger parameters passed to the Ingester
 [options="header"]
@@ -29,7 +30,7 @@ The deadlock interval is disabled by default (set to `0`), to avoid terminating
   kafka:
     consumer:
       topic:
-|The `topic` parameter identifies the Kafka configuration used by the collector to produce the messages, and the Ingester to consume the messages.
+|The `topic` value names the Kafka setup. The collector writes to it. The Ingester reads from it.
 |Label for the consumer. For example, `jaeger-spans`.
 
 |options:

modules/ossm-config-jaeger-collector.adoc

@@ -6,9 +6,10 @@
 [id="ossm-config-jaeger-collector_{context}"]
 = Jaeger Collector configuration options
 
-The Jaeger Collector is the component responsible for receiving the spans that were captured by the tracer and writing them to persistent Elasticsearch storage when using the `production` strategy, or to AMQ Streams when using the `streaming` strategy.
+[role="_abstract"]
+The Jaeger Collector receives spans from the tracer. When you apply the `production` strategy, the Jaeger Collector sends them to Elasticsearch. When you apply the`streaming` strategy, it sends them to AMQ Streams.
 
-The Collectors are stateless and thus many instances of Jaeger Collector can be run in parallel. Collectors require almost no configuration, except for the location of the Elasticsearch cluster.
+Collectors do not store state. You can run many Collectors at the same time. You only need to set where Elasticsearch runs.
 
 .Parameters used by the Operator to define the Jaeger Collector
 [options="header"]
@@ -49,14 +50,14 @@ The Collectors are stateless and thus many instances of Jaeger Collector can be
   kafka:
     producer:
       topic: jaeger-spans
-|The `topic` parameter identifies the Kafka configuration used by the Collector to produce the messages, and the Ingester to consume the messages.
+|The `topic` value names the Kafka setup. The Collector writes to it. The Ingester reads from it.
 |Label for the producer.
 
 |options:
   kafka:
     producer:
       brokers: my-cluster-kafka-brokers.kafka:9092
-|Identifies the Kafka configuration used by the Collector to produce the messages. If brokers are not specified, and you have AMQ Streams 1.4.0+ installed, the {JaegerName} Operator will self-provision Kafka.
+|Names the Kafka setup for the Collector. If you omit brokers and AMQ Streams 1.4.0+ is installed, the {JaegerName} Operator creates Kafka for you.
 |
 
 |options:

modules/ossm-config-manage-es-certificates.adoc

@@ -0,0 +1,82 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v2x/ossm-reference-jaeger.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="distr-tracing-manage-es-certificates_{context}"]
+= Managing certificates with Elasticsearch
+
+[role="_abstract"]
+You can create and manage certificates with the {es-op}. You can also use one Elasticsearch cluster with more than one Jaeger Collector.
+
+:FeatureName: Managing certificates with Elasticsearch
+include::snippets/technology-preview.adoc[leveloffset=+1]
+
+Starting with version 2.4, the {JaegerName} Operator asks the {es-op} to create certificates. Add these annotations to the Elasticsearch custom resource:
+
+* `logging.openshift.io/elasticsearch-cert-management: "true"`
+* `logging.openshift.io/elasticsearch-cert.jaeger-<shared-es-node-name>: "user.jaeger"`
+* `logging.openshift.io/elasticsearch-cert.curator-<shared-es-node-name>: "system.logging.curator"`
+
+Where the `<shared-es-node-name>` is the name of the Elasticsearch node. For example, if you create an Elasticsearch node named `custom-es`, your custom resource might look like the following example.
+
+.Example Elasticsearch CR showing annotations
+[source,yaml]
+----
+apiVersion: logging.openshift.io/v1
+kind: Elasticsearch
+metadata:
+  annotations:
+    logging.openshift.io/elasticsearch-cert-management: "true"
+    logging.openshift.io/elasticsearch-cert.jaeger-custom-es: "user.jaeger"
+    logging.openshift.io/elasticsearch-cert.curator-custom-es: "system.logging.curator"
+  name: custom-es
+spec:
+  managementState: Managed
+  nodeSpec:
+    resources:
+      limits:
+        memory: 16Gi
+      requests:
+        cpu: 1
+        memory: 16Gi
+  nodes:
+    - nodeCount: 3
+      proxyResources: {}
+      resources: {}
+      roles:
+        - master
+        - client
+        - data
+      storage: {}
+  redundancyPolicy: ZeroRedundancy
+----
+
+*Prerequisites*
+
+* Install the {SMProductName} Operator.
+* Install the {logging-title} with the default configuration in your cluster.
+* Deploy the Elasticsearch node and the Jaeger instances must be deployed in the same namespace. For example, `tracing-system`.
+
+Now, you can enable certificate management by setting `spec.storage.elasticsearch.useCertManagement` to `true` in the Jaeger custom resource.
+
+.Example showing `useCertManagement`
+[source,yaml]
+----
+apiVersion: jaegertracing.io/v1
+kind: Jaeger
+metadata:
+  name: jaeger-prod
+spec:
+  strategy: production
+  storage:
+    type: elasticsearch
+    elasticsearch:
+      name: custom-es
+      doNotProvision: true
+      useCertManagement: true
+----
+
+When it provisions Elasticsearch, the {JaegerName} Operator sets the Elasticsearch CR `name` from `spec.storage.elasticsearch.name` in the Jaeger CR.
+
+The {es-op} creates the certificates. The {JaegerName} Operator adds them to the deployment.

modules/ossm-config-query.adoc

@@ -6,6 +6,7 @@
 [id="ossm-config-query_{context}"]
 = Query configuration options
 
+[role="_abstract"]
 Query is a service that retrieves traces from storage and hosts the user interface to display them.
 
 .Parameters used by the {JaegerName} Operator to define Query

modules/ossm-config-security-ossm-cli.adoc

@@ -6,6 +6,7 @@
 [id="ossm-config-security-ossm-cli_{context}"]
 = Configuring distributed tracing security for service mesh from the command line
 
+[role="_abstract"]
 You can modify the Jaeger resource to configure {JaegerShortName} security for use with {SMproductShortName} from the command line by running the {oc-first}.
 
 .Prerequisites

modules/ossm-config-security-ossm-web.adoc

@@ -6,6 +6,7 @@
 [id="ossm-config-security-ossm-web_{context}"]
 = Configuring distributed tracing security for service mesh from the web console
 
+[role="_abstract"]
 You can modify the Jaeger resource to configure {JaegerShortName} security for use with {SMproductShortName} in the web console.
 
 .Prerequisites

modules/ossm-config-security-ossm.adoc

@@ -6,6 +6,11 @@
 [id="ossm-config-security-ossm_{context}"]
 = Configuring distributed tracing security for service mesh
 
-The {JaegerShortName} uses OAuth for default authentication. However {SMProductName} uses a secret called `htpasswd` to facilitate communication between dependent services such as Grafana, Kiali, and the {JaegerShortName}. When you configure your {JaegerShortName} in the `ServiceMeshControlPlane` the {SMProductShortName} automatically configures security settings to use `htpasswd`.
+[role="_abstract"]
+By default, the {JaegerShortName} uses OAuth to sign users in.
 
-If you are specifying your {JaegerShortName} configuration in a Jaeger custom resource, you must manually configure the `htpasswd` settings and ensure the `htpasswd` secret is mounted into your Jaeger instance so that Kiali can communicate with it.
+{SMProductName} also uses a secret named `htpasswd`. Grafana, Kiali, and the {JaegerShortName} use this secret to talk to each other.
+
+When you set Jaeger in the `ServiceMeshControlPlane`, service mesh turns on `htpasswd` security for you.
+
+If you set Jaeger in a Jaeger custom resource instead, you must add the `htpasswd` settings yourself. Mount the `htpasswd` secret in your Jaeger instance so Kiali can reach it.

modules/ossm-config-smcp-jaeger.adoc

@@ -6,6 +6,7 @@
 [id="ossm-specifying-jaeger-configuration_{context}"]
 = Specifying Jaeger configuration in the SMCP
 
-You configure Jaeger under the `addons` section of the `ServiceMeshControlPlane` resource. However, there are some limitations to what you can configure in the SMCP.
+[role="_abstract"]
+Set Jaeger options in the `addons` section of the `ServiceMeshControlPlane` resource. The SMCP only supports some settings.
 
-When the SMCP passes configuration information to the {JaegerName} Operator, it triggers one of three deployment strategies: `allInOne`, `production`, or `streaming`.
+When the SMCP sends settings to the {JaegerName} Operator, the Operator picks one of three deployment strategies: `allInOne`, `production`, or `streaming`.