Merge pull request #46088 from JStickler/OSSMDOC-554

OSSMDOC-554: Document new cert management settings for Elasticsearch.

Author: JStickler

modules/distr-tracing-config-storage.adoc

@@ -65,7 +65,13 @@ Memory storage is only appropriate for development, testing, demonstrations, and
 [id="distributed-tracing-config-auto-provisioning-es_{context}"]
 == Auto-provisioning an Elasticsearch instance
 
-When the `storage:type` is set to `elasticsearch` but there is no value set for `spec:storage:options:es:server-urls`, the {JaegerName} Operator uses the OpenShift Elasticsearch Operator to create an Elasticsearch cluster based on the configuration provided in the `storage` section of the custom resource file.
+When you deploy a Jaeger custom resource, the {JaegerName} Operator uses the OpenShift Elasticsearch Operator to create an Elasticsearch cluster based on the configuration provided in the `storage` section of the custom resource file. The {JaegerName} Operator will provision Elasticsearch if the following configurations are set:
+
+* `spec.storage:type` is set to `elasticsearch`
+* `spec.storage.elasticsearch.doNotProvision` set to `false`
+* `spec.storage.options.es.server-urls` is not defined, that is, there is no connection to an Elasticsearch instance that was not provisioned by the Red Hat Elasticsearch Operator.
+
+When provisioning Elasticsearch, the {JaegerName} Operator sets the Elasticsearch custom resource `name` to the value of `spec.storage.elasticsearch.name` from the Jaeger custom resource.  If you do not specify a value for `spec.storage.elasticsearch.name`, the Operator uses `elasticsearch`.
 
 .Restrictions
 
@@ -84,6 +90,20 @@ The following configuration parameters are for a _self-provisioned_ Elasticsearc
 [cols="l, a, a, a"]
 |===
 |Parameter |Description |Values |Default value
+|elasticsearch:
+  properties:
+    doNotProvision:
+|Use to specify whether or not an Elasticsearch instance should be provisioned by the {JaegerName} Operator.
+|`true`/`false`
+|`true`
+
+|elasticsearch:
+  properties:
+    name:
+|Name of the Elasticsearch instance. The {JaegerName} Operator uses the Elasticsearch instance specified in this parameter to connect to Elasticsearch.
+|string
+|`elasticsearch`
+
 |elasticsearch:
   nodeCount:
 |Number of Elasticsearch nodes. For high availability use at least 3 nodes. Do not use 2 nodes as “split brain” problem can happen.
@@ -133,6 +153,12 @@ Minimum deployment = 16Gi*
 |`ZeroRedundancy`(no replica shards), `SingleRedundancy`(one replica shard), `MultipleRedundancy`(each index is spread over half of the Data nodes), `FullRedundancy` (each index is fully replicated on every Data node in the cluster).
 |
 
+|elasticsearch:
+  useCertManagement:
+|Use to specify whether or not {JaegerShortName} should use the certificate management feature of the Red Hat Elasticsearch Operator.  This feature was added to {logging-title} 5.2 in {product-title} 4.7 and is the preferred setting for new Jaeger deployments.
+|`true`/`false`
+|`true`
+
 |
 3+|*Each Elasticsearch node can operate with a lower memory setting though this is NOT recommended for production deployments. For production use, you should have no less than 16Gi allocated to each pod by default, but preferably allocate as much as you can, up to 64Gi per pod.
 |===
@@ -189,7 +215,15 @@ spec:
 [id="distributed-tracing-config-external-es_{context}"]
 == Connecting to an existing Elasticsearch instance
 
-You can use an existing Elasticsearch cluster for storage with {DTShortName}, that is, an instance that was not auto-provisioned by the {JaegerName} Operator. You do this by specifying the URL of the existing cluster as the `spec:storage:options:es:server-urls` value in your configuration.
+You can use an existing Elasticsearch cluster for storage with {DTShortName}. An existing Elasticsearch cluster, also known as an _external_ Elasticsearch instance, is an instance that was not installed by the {JaegerName} Operator or by the Red Hat Elasticsearch Operator.
+
+When you deploy a Jaeger custom resource, the {JaegerName} Operator will not provision Elasticsearch if the following configurations are set:
+
+* `spec.storage.elasticsearch.doNotProvision` set to `true`
+* `spec.storage.options.es.server-urls` has a value
+* `spec.storage.elasticsearch.name` has a value, or if the Elasticsearch instance name is `elasticsearch`.
+
+The {JaegerName} Operator uses the Elasticsearch instance specified in `spec.storage.elasticsearch.name` to connect to Elasticsearch.
 
 .Restrictions
 
@@ -615,3 +649,84 @@ spec:
 <2> TLS configuration. In this case only CA certificate, but it can also contain es.tls.key and es.tls.cert when using mutual TLS.
 <3> Secret which defines environment variables ES_PASSWORD and ES_USERNAME. Created by kubectl create secret generic tracing-secret --from-literal=ES_PASSWORD=changeme --from-literal=ES_USERNAME=elastic
 <4> Volume mounts and volumes which are mounted into all storage components.
+
+[id="distr-tracing-manage-es-certificates_{context}"]
+= Managing certificates with Elasticsearch
+
+You can create and manage certificates using the Red Hat Elasticsearch Operator. Managing certificates using the Red Hat Elasticsearch Operator also lets you use a single Elasticsearch cluster with multiple Jaeger Collectors.
+
+[IMPORTANT]
+====
+Managing certificates with Elasticsearch is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production.
+
+These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/.
+====
+
+Starting with version 2.4, the {JaegerName} Operator delegates certificate creation to the Red Hat Elasticsearch Operator by using the following annotations in 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
+
+* {product-title} 4.7
+* {logging-title} 5.2
+* The Elasticsearch node and the Jaeger instances must be deployed in the same namespace.  For example, `tracing-system`.
+
+You 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
+----
+
+The {JaegerName} Operator sets the Elasticsearch custom resource `name` to the value of `spec.storage.elasticsearch.name` from the Jaeger custom resource when provisioning Elasticsearch.
+
+The certificates are provisioned by the Red Hat Elasticsearch Operator and the {JaegerName} Operator injects the certificates.