OSSMDOC-153 connect to existing Jaeger OSSM 2.0

jaeger/jaeger_install/rhbjaeger-deploying.adoc

@@ -5,7 +5,7 @@ include::modules/jaeger-document-attributes.adoc[]
 
 toc::[]
 
-The Jaeger Operator includes a custom resource definition (CRD) file that defines the architecture and configuration settings for the Jaeger resources. You can either install the default configuration or modify the file to better suit your business requirements.
+The Jaeger Operator uses a custom resource definition (CRD) file that defines the architecture and configuration settings to be used when creating and deploying the Jaeger resources. You can either install the default configuration or modify the file to better suit your business requirements.
 
 Jaeger has predefined deployment strategies. You specify a deployment strategy in the custom resource file. When you create a Jaeger instance the Operator uses this configuration file to create the objects necessary for the deployment.
 
@@ -22,14 +22,14 @@ spec:
 
 <1> The Jaeger Operator currently supports the following deployment strategies:
 
-* *allInOne* (Default) - This strategy is intended for development, testing, and demo purposes. The main backend components, Agent, Collector and Query service, are all packaged into a single executable which is configured (by default) to use in-memory storage.
+* *allInOne* (Default) - This strategy is intended for development, testing, and demo purposes; it is not intended for production use. The main backend components, Agent, Collector and Query service, are all packaged into a single executable which is configured (by default) to use in-memory storage.
 +
 [NOTE]
 ====
 In-memory storage is not persistent, which means that if the Jaeger instance shuts down, restarts, or is replaced, that your trace data will be lost.  And in-memory storage cannot be scaled, since each pod has its own memory. For persistent storage, you must use the `production` or `streaming` strategies, which use Elasticsearch as the default storage.
 ====
 
-* *production* - The production strategy is intended for production environments, where long term storage of trace data is important, as well as a more scalable and highly available architecture is required. Each of the backend components is therefore deployed separately.  The Agent can be injected as a sidecar on the instrumented application or as a daemonset. The Query and Collector services are configured with a supported storage type - currently Elasticsearch. Multiple instances of each of these components can be provisioned as required for performance and resilience purposes.
+* *production* - The production strategy is intended for production environments, where long term storage of trace data is important, as well as a more scalable and highly available architecture is required. Each of the backend components is therefore deployed separately.  The Agent can be injected as a sidecar on the instrumented application. The Query and Collector services are configured with a supported storage type - currently Elasticsearch. Multiple instances of each of these components can be provisioned as required for performance and resilience purposes.
 
 * *streaming* - The streaming strategy is designed to augment the production strategy by providing a streaming capability that effectively sits between the Collector and the backend storage (Elasticsearch). This provides the benefit of reducing the pressure on the backend storage, under high load situations, and enables other trace post-processing capabilities to tap into the real time span data directly from the streaming platform (https://access.redhat.com/documentation/en-us/red_hat_amq/7.6/html/using_amq_streams_on_openshift/index[AMQ Streams]/ https://kafka.apache.org/documentation/[Kafka]).
 +
@@ -40,7 +40,8 @@ The streaming strategy requires an additional Red Hat subscription for AMQ Strea
 
 [NOTE]
 ====
-There are two ways to install Jaeger, as part of a service mesh or as a stand alone component. If you have installed Jaeger as part of Red Hat OpenShift Service Mesh, you must configure and deploy Jaeger as part of the xref:../../service_mesh/v2x/ossm-custom-resources.adoc#ossm-custom-resources-v2x[ServiceMeshControlPlane].
+There are two ways to install and use Jaeger, as part of a service mesh or as a stand alone component. If you have installed Jaeger as part of Red Hat OpenShift Service Mesh, you can configure and deploy Jaeger as part of the xref:../../service_mesh/v2x/ossm-custom-resources.adoc#ossm-custom-resources-v2x[ServiceMeshControlPlane] or configure Jaeger and then xref:../../service_mesh/v2x/ossm-custom-resources.adoc#ossm-deploying-jaeger-streaming[reference your Jaeger configuration in the SMCP].
+
 ====
 
 // The following include statements pull in the module files that comprise the assembly.

modules/ossm-configuring-jaeger-v1x.adoc

@@ -0,0 +1,178 @@
+// Module included in the following assemblies:
+//
+// * service_mesh/v1x/customizing-installation-ossm.adoc
+
+[id="ossm-configuring-jaeger-v1x_{context}"]
+= Configuring Jaeger
+
+When the {ProductShortName} Operator creates the `ServiceMeshControlPlane` resource it also creates the Jaeger resource. The Jaeger Operator then uses this object when creating Jaeger instances.
+
+The default Jaeger parameters specified in the `ServiceMeshControlPlane` are as follows:
+
+.Default `all-in-one` Jaeger parameters
+[source,yaml]
+----
+  apiVersion: maistra.io/v1
+  kind: ServiceMeshControlPlane
+  spec:
+    version: v1.1
+    istio:
+      tracing:
+        enabled: true
+        jaeger:
+          template: all-in-one
+----
+
+.Jaeger parameters
+[options="header"]
+[cols="l, a, a, a"]
+|===
+|Parameter |Description |Values |Default value
+
+|tracing
+   enabled
+|This parameter enables/disables tracing in {ProductShortName}. Jaeger is installed by default.
+|`true`/`false`
+|`true`
+
+|jaeger
+   template
+|This parameter specifies which Jaeger deployment strategy to use.
+|* `all-in-one`- For development, testing, demonstrations, and proof of concept.
+* `production-elasticsearch` - For production use.
+|`all-in-one`
+|===
+
+[NOTE]
+====
+The default template in the `ServiceMeshControlPlane` resource is the `all-in-one` deployment strategy which uses in-memory storage. For production, the only supported storage option is Elasticsearch, therefore you must configure the `ServiceMeshControlPlane` to request the `production-elasticsearch` template when you deploy {ProductShortName} within a production environment.
+====
+
+
+[id="ossm-configuring-jaeger-elasticsearch_{context}"]
+== Configuring Elasticsearch
+
+The default Jaeger deployment strategy uses the `all-in-one` template so that the installation can be completed using minimal resources.  However, because the `all-in-one` template uses in-memory storage, it is only recommended for development, demo, or testing purposes and should NOT be used for production environments.
+
+If you are deploying {ProductShortName} and Jaeger in a production environment you must change the template to the `production-elasticsearch` template, which uses Elasticsearch for Jaeger's storage needs.
+
+Elasticsearch is a memory intensive application. The initial set of nodes specified in the default {product-title} installation may not be large enough to support the Elasticsearch cluster.  You should modify the default Elasticsearch configuration to match your use case and the resources you have requested for your {product-title} installation. You can adjust both the CPU and memory limits for each component by modifying the resources block with valid CPU and memory values. Additional nodes must be added to the  cluster if you want to run with the recommended amount (or more) of memory. Ensure that you do not exceed the resources requested for your {product-title} installation.
+
+.Default "production" Jaeger parameters with Elasticsearch
+[source,yaml]
+----
+  apiVersion: maistra.io/v1
+  kind: ServiceMeshControlPlane
+  spec:
+    istio:
+      tracing:
+      enabled: true
+      ingress:
+        enabled: true
+      jaeger:
+        template: production-elasticsearch
+        elasticsearch:
+          nodeCount: 3
+          redundancyPolicy:
+          resources:
+            requests:
+              cpu: "1"
+              memory: "16Gi"
+            limits:
+              cpu: "1"
+              memory: "16Gi"
+
+----
+
+.Elasticsearch parameters
+[options="header"]
+[cols="l, a, a, a, a"]
+|===
+|Parameter |Description |Values |Default Value |Examples
+
+|tracing:
+  enabled:
+|This parameter enables/disables tracing in {ProductShortName}. Jaeger is installed by default.
+|`true`/`false`
+|`true`
+|
+
+|ingress:
+  enabled:
+|This parameter enables/disables ingress for Jaeger.
+|`true`/`false`
+|`true`
+|
+
+|jaeger:
+   template:
+|This parameter specifies which Jaeger deployment strategy to use.
+|`all-in-one`/`production-elasticsearch`
+|`all-in-one`
+|
+
+|elasticsearch:
+  nodeCount:
+|Number of Elasticsearch nodes to create.
+|Integer value.
+|1
+|Proof of concept = 1,
+Minimum deployment =3
+
+|requests:
+  cpu:
+|Number of central processing units for requests, based on your environment’s configuration.
+|Specified in cores or millicores (for example, 200m, 0.5, 1).
+|1Gi
+|Proof of concept = 500m,
+Minimum deployment =1
+
+|requests:
+  memory:
+|Available memory for requests, based on your environment’s configuration.
+|Specified in bytes (for example, 200Ki, 50Mi, 5Gi).
+|500m
+|Proof of concept = 1Gi,
+Minimum deployment = 16Gi*
+
+|limits:
+  cpu:
+|Limit on number of central processing units, based on your environment’s configuration.
+|Specified in cores or millicores (for example, 200m, 0.5, 1).
+|
+|Proof of concept = 500m,
+Minimum deployment =1
+
+|limits:
+  memory:
+|Available memory limit based on your environment’s configuration.
+|Specified in bytes (for example, 200Ki, 50Mi, 5Gi).
+|
+|Proof of concept = 1Gi,
+Minimum deployment = 16Gi*
+
+|
+4+|{asterisk} 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.
+|===
+
+
+.Procedure
+
+. Log in to the {product-title} web console as a user with the `cluster-admin` role.
+
+. Navigate to *Operators* -> *Installed Operators*.
+
+. Click the {ProductName} Operator.
+
+. Click the *Istio Service Mesh Control Plane* tab.
+
+. Click the name of your control plane file, for example, `basic-install`.
+
+. Click the *YAML* tab.
+
+. Edit the Jaeger parameters, replacing the default `all-in-one` template with parameters for the `production-elasticsearch` template, modified for your use case.  Ensure that the indentation is correct.
+
+. Click *Save*.
+
+. Click *Reload*.
+{product-title} redeploys Jaeger and creates the Elasticsearch resources based on the specified parameters.

modules/ossm-configuring-jaeger.adoc

@@ -1,178 +1,15 @@
 // Module included in the following assemblies:
 //
-// * service_mesh/v1x/customizing-installation-ossm.adoc
 // * service_mesh/v2x/customizing-installation-ossm.adoc
 
-[id="ossm-configuring-jaeger_{context}"]
-= Configuring Jaeger
 
-When the {ProductShortName} Operator creates the `ServiceMeshControlPlane` resource it also creates the Jaeger resource. The Jaeger Operator then uses this object when creating Jaeger instances.
+[id="ossm-specifying-jaeger-configuration_{context}"]
+= Specifying Jaeger Configuration
 
-The default Jaeger parameters specified in the `ServiceMeshControlPlane` are as follows:
+You configure Jaeger under the `addons` section of `ServiceMeshControlPlane` resource.
 
-.Default `all-in-one` Jaeger parameters
-[source,yaml]
-----
-  apiVersion: maistra.io/v1
-  kind: ServiceMeshControlPlane
-  spec:
-    istio:
-      tracing:
-        enabled: true
-        jaeger:
-          template: all-in-one
-----
+You can specify your Jaeger configuration in either of two ways:
 
-.Jaeger parameters
-[options="header"]
-[cols="l, a, a, a"]
-|===
-|Parameter |Description |Values |Default value
+* Specify the Jaeger configuration in the `ServiceMeshControlPlane` resource under `spec.addons.jaeger.install`.  There are some limitations with this approach.  For example, you cannot configure a `streaming` deployment strategy via the control plane.
 
-|tracing
-   enabled
-|This parameter enables/disables tracing in {ProductShortName}. Jaeger is installed by default.
-|`true`/`false`
-|`true`
-
-|jaeger
-   template
-|This parameter specifies which Jaeger deployment strategy to use.
-|* `all-in-one`- For development, testing, demonstrations, and proof of concept.
-* `production-elasticsearch` - For production use.
-|`all-in-one`
-|===
-
-[NOTE]
-====
-The default template in the `ServiceMeshControlPlane` resource is the `all-in-one` deployment strategy which uses in-memory storage. For production, the only supported storage option is Elasticsearch, therefore you must configure the `ServiceMeshControlPlane` to request the `production-elasticsearch` template when you deploy {ProductShortName} within a production environment.
-====
-
-
-[id="ossm-configuring-jaeger-elasticsearch_{context}"]
-== Configuring Elasticsearch
-
-The default Jaeger deployment strategy uses the `all-in-one` template so that the installation can be completed using minimal resources.  However, because the `all-in-one` template uses in-memory storage, it is only recommended for development, demo, or testing purposes and should NOT be used for production environments.
-
-If you are deploying {ProductShortName} and Jaeger in a production environment you must change the template to the `production-elasticsearch` template, which uses Elasticsearch for Jaeger's storage needs.
-
-Elasticsearch is a memory intensive application. The initial set of nodes specified in the default {product-title} installation may not be large enough to support the Elasticsearch cluster.  You should modify the default Elasticsearch configuration to match your use case and the resources you have requested for your {product-title} installation. You can adjust both the CPU and memory limits for each component by modifying the resources block with valid CPU and memory values. Additional nodes must be added to the  cluster if you want to run with the recommended amount (or more) of memory. Ensure that you do not exceed the resources requested for your {product-title} installation.
-
-.Default "production" Jaeger parameters with Elasticsearch
-[source,yaml]
-----
-  apiVersion: maistra.io/v1
-  kind: ServiceMeshControlPlane
-  spec:
-    istio:
-      tracing:
-      enabled: true
-      ingress:
-        enabled: true
-      jaeger:
-        template: production-elasticsearch
-        elasticsearch:
-          nodeCount: 3
-          redundancyPolicy:
-          resources:
-            requests:
-              cpu: "1"
-              memory: "16Gi"
-            limits:
-              cpu: "1"
-              memory: "16Gi"
-
-----
-
-.Elasticsearch parameters
-[options="header"]
-[cols="l, a, a, a, a"]
-|===
-|Parameter |Description |Values |Default Value |Examples
-
-|tracing:
-  enabled
-|This parameter enables/disables tracing in {ProductShortName}. Jaeger is installed by default.
-|`true`/`false`
-|`true`
-|
-
-|ingress:
-  enabled
-|This parameter enables/disables ingress for Jaeger.
-|`true`/`false`
-|`true`
-|
-
-|jaeger
-   template
-|This parameter specifies which Jaeger deployment strategy to use.
-|`all-in-one`/`production-elasticsearch`
-|`all-in-one`
-|
-
-|elasticsearch:
-  nodeCount
-|Number of Elasticsearch nodes to create.
-|Integer value.
-|1
-|Proof of concept = 1,
-Minimum deployment =3
-
-|requests:
-  cpu
-|Number of central processing units for requests, based on your environment’s configuration.
-|Specified in cores or millicores (for example, 200m, 0.5, 1).
-|1Gi
-|Proof of concept = 500m,
-Minimum deployment =1
-
-|requests:
-  memory
-|Available memory for requests, based on your environment’s configuration.
-|Specified in bytes (for example, 200Ki, 50Mi, 5Gi).
-|500m
-|Proof of concept = 1Gi,
-Minimum deployment = 16Gi*
-
-|limits:
-  cpu
-|Limit on number of central processing units, based on your environment’s configuration.
-|Specified in cores or millicores (for example, 200m, 0.5, 1).
-|
-|Proof of concept = 500m,
-Minimum deployment =1
-
-|limits:
-  memory
-|Available memory limit based on your environment’s configuration.
-|Specified in bytes (for example, 200Ki, 50Mi, 5Gi).
-|
-|Proof of concept = 1Gi,
-Minimum deployment = 16Gi*
-
-|
-4+|{asterisk} 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.
-|===
-
-
-.Procedure
-
-. Log in to the {product-title} web console as a user with the `cluster-admin` role.
-
-. Navigate to *Operators* -> *Installed Operators*.
-
-. Click the {ProductName} Operator.
-
-. Click the *Istio Service Mesh Control Plane* tab.
-
-. Click the name of your control plane file, for example, `basic-install`.
-
-. Click the *YAML* tab.
-
-. Edit the Jaeger parameters, replacing the default `all-in-one` template with parameters for the `production-elasticsearch` template, modified for your use case.  Ensure that the indentation is correct.
-
-. Click *Save*.
-
-. Click *Reload*.
-{product-title} redeploys Jaeger and creates the Elasticsearch resources based on the specified parameters.
+* Configure and deploy a Jaeger instance and then specify the `name` of the Jaeger resource as the value for `spec.addons.jaeger.name` in the `ServiceMeshControlPlane` resource.  If a Jaeger resource matching the value of `name` exists, the control plane will use the existing installation.  This approach lets you fully customize your Jaeger configuration.