Skip to content

[enterprise-4.6] OSSMDOC-153 connect to existing Jaeger OSSM 2.0 #28825

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Jan 25, 2021
Merged

[enterprise-4.6] OSSMDOC-153 connect to existing Jaeger OSSM 2.0 #28825

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
75537f3
OSSMDOC-153 connect to existing Jaeger OSSM 2.0
JStickler Nov 16, 2020
b6006b5
First round of review comments from Gary and Rob.
JStickler Nov 18, 2020
89ace00
Second round of review comments.
JStickler Dec 2, 2020
4fc9e12
review comments from Fillip.
JStickler Dec 18, 2020
0db8c79
Capitalized Jaeger in SMCP
JStickler Jan 4, 2021
2e03235
Cleaning up parameter punctuation.
JStickler Jan 11, 2021
a1b3514
review from Neal
JStickler Jan 22, 2021
8faf81f
removed second that
JStickler Jan 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions jaeger/jaeger_install/rhbjaeger-deploying.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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]).
+
Expand All @@ -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.
Expand Down
178 changes: 178 additions & 0 deletions modules/ossm-configuring-jaeger-v1x.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
175 changes: 6 additions & 169 deletions modules/ossm-configuring-jaeger.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Loading