diff --git a/_topic_map.yml b/_topic_map.yml index 5839c82bd9c8..a9a98a9d9797 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -1457,18 +1457,12 @@ Topics: Topics: - Name: Installing Jaeger File: rhbjaeger-installation -# - Name: Deploying Jaeger -# File: rhbjaeger-deploying + - Name: Deploying Jaeger + File: rhbjaeger-deploying - Name: Upgrading Jaeger File: rhbjaeger-updating - Name: Removing Jaeger File: rhbjaeger-removing -# Integrations / cross-product stories -- Name: Integrating Jaeger - Dir: jaeger_config - Topics: - - Name: Integrating Jaeger with serverless applications using OpenShift Serverless - File: serverless-jaeger-integration --- Name: Container-native virtualization diff --git a/jaeger/jaeger_install/rhbjaeger-deploying.adoc b/jaeger/jaeger_install/rhbjaeger-deploying.adoc index 26c7d1f0a7ab..66c599f49b52 100644 --- a/jaeger/jaeger_install/rhbjaeger-deploying.adoc +++ b/jaeger/jaeger_install/rhbjaeger-deploying.adoc @@ -1,42 +1,71 @@ [id="deploying-jaeger"] = Deploying Jaeger -include::modules/ossm-document-attributes.adoc[] +include::modules/jaeger-document-attributes.adoc[] :context: jaeger-deploying toc::[] -The Jaeger Operator includes a custom resource definition (CRD) file that determines the architecture and configuration settings to use when creating the Jaeger custom resources (CR). You can either install the default configuration or modify the custom resource file to better suit your business requirements. +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. -Each Jaeger instance is associated with a deployment strategy. You define the strategy is defined in the custom resource file and when you create a Jaeger instance the Operator uses the deployment strategy and configuration options in the CR file to create the objects necessary for the deployment. -The Jaeger Operator currently supports the following deployment strategies: +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. -* *allInOne* (Default) strategy - 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. +.Jaeger custom resource file showing deployment strategy +[source,yaml] +---- +apiVersion: jaegertracing.io/v1 +kind: Jaeger +metadata: + name: simple-prod +spec: + strategy: production <1> +---- +<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. ++ [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. For persistent storage, use the production Elasticsearch deployment strategy. +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* strategy - 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. For more information about configuring Elasticsearch with {product-title}, see xref:../../logging/config/cluster-logging-elasticsearch.adoc[Configuring Elasticsearch]. +* *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. -* *streaming* strategy - 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 (Kafka). +* *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]). [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/service_mesh_install/customizing-installation-ossm.adoc#customizing-installation-ossm[ServiceMeshControlPlane]. ==== - // The following include statements pull in the module files that comprise the assembly. include::modules/jaeger-deploy-default.adoc[leveloffset=+1] +include::modules/jaeger-deploy-production-es.adoc[leveloffset=1] + +include::modules/jaeger-deploy-streaming.adoc[leveloffset=1] + +[id="customizing-jaeger-deployment"] += Customizing Jaeger deployment + include::modules/jaeger-config-default.adoc[leveloffset=+1] -include::modules/jaeger-deploy-production-es.adoc[leveloffset=+1] +include::modules/jaeger-config-collector.adoc[leveloffset=+1] + +include::modules/jaeger-config-sampling.adoc[leveloffset=+1] + +include::modules/jaeger-config-storage.adoc[leveloffset=+1] + +include::modules/jaeger-config-query.adoc[leveloffset=+1] + +include::modules/jaeger-config-ingester.adoc[leveloffset=+1] + +[id="injecting-sidecars"] += Injecting sidecars -include::modules/jaeger-config-production-es.adoc[leveloffset=+1] +{ProductName} relies on a proxy sidecar within the application’s pod to provide the agent. The Jaeger Operator can inject Jaeger Agent sidecars into Deployment workloads. You can enable automatic sidecar injection or manage it manually. -include::modules/jaeger-deploy-streaming.adoc[leveloffset=+1] +include::modules/jaeger-sidecar-automatic.adoc[leveloffset=1] -include::modules/jaeger-config-streaming.adoc[leveloffset=+1] +include::modules/jaeger-sidecar-manual.adoc[leveloffset=1] diff --git a/jaeger/rhbjaeger-release-notes.adoc b/jaeger/rhbjaeger-release-notes.adoc index f52e2101d586..bc3650154fab 100644 --- a/jaeger/rhbjaeger-release-notes.adoc +++ b/jaeger/rhbjaeger-release-notes.adoc @@ -11,11 +11,6 @@ include::modules/jaeger-product-overview.adoc[leveloffset=+1] include::modules/support.adoc[leveloffset=+1] -//// -TODO -include::modules/jaeger-supported-configurations.adoc[leveloffset=+1] -//// - include::modules/jaeger-rn-new-features.adoc[leveloffset=+1] include::modules/jaeger-rn-known-issues.adoc[leveloffset=+1] diff --git a/modules/jaeger-config-collector.adoc b/modules/jaeger-config-collector.adoc new file mode 100644 index 000000000000..82c0e36da3ca --- /dev/null +++ b/modules/jaeger-config-collector.adoc @@ -0,0 +1,39 @@ +//// +This REFERENCE module included in the following assemblies: +-rhbjaeger-deploy.adoc +//// + +[id="jaeger-config-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 a persistent storage (Elasticsearch) when using the `production` strategy, or to AMQ Streams when using the `streaming` strategy. + +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. + +.Jaeger collector parameters +[options="header"] +[cols="l, a, a"] +|=== +|Parameter |Description |Values +|spec: + collector: + options: {} +|Configuration options that define the Jaeger Collector. +| + +|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. +|Label for the producer + +|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, Jaeger will self-provision Kafka. +| + +|log-level: +|Logging level for the collector. +|Possible values: `trace`, `debug`, `info`, `warning`, `error`, `fatal`, `panic`. +|=== diff --git a/modules/jaeger-config-default.adoc b/modules/jaeger-config-default.adoc new file mode 100644 index 000000000000..cf4919907ec7 --- /dev/null +++ b/modules/jaeger-config-default.adoc @@ -0,0 +1,126 @@ +//// +This REFERENCE module included in the following assemblies: +- rhbjaeger-deploying.adoc +//// + +[id="jaeger-config-default_{context}"] += Jaeger default configuration options +:pantheon-module-type: REFERENCE + +The Jaeger custom resource (CR) defines the architecture and settings to be used when creating the Jaeger resources. You can modify these parameters to customize your Jaeger implementation to your business needs. + +.Jaeger generic YAML example +[source,yaml] +---- +apiVersion: jaegertracing.io/v1 +kind: Jaeger +metadata: + name: name +spec: + strategy: + allInOne: + options: {} + resources: {} + agent: + options: {} + resources: {} + collector: + options: {} + resources: {} + sampling: + options: {} + storage: + type: + options: {} + query: + options: {} + resources: {} + ingester: + options: {} + resources: {} + options: {} +---- + +.Jaeger parameters +[options="header"] +|=== +|Parameter |Description |Values |Default value + +|apiVersion: +|Version of the Application Program Interface to use when creating the object. +|`jaegertracing.io/v1` +|`jaegertracing.io/v1` + +|kind: +|Defines the kind of Kubernetes object to create. +|`jaeger` +| + +|metadata: +|Data that helps uniquely identify the object, including a `name` string, `UID`, and optional `namespace`. +| +|OpenShift automatically generates the `UID` and completes the `namespace` with the name of the project where the object is created. + +|name: +|Name for the object. +|The name of your Jaeger instance. +|`jaeger-all-in-one-inmemory` + +|spec: +|Specification for the object to be created. +|Contains all of the configuration parameters for your Jeager 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/ node. +|N/A + +|strategy: +|Jaeger deployment strategy +|`allInOne`, `production`, or `streaming` +|`allInOne` + +|allInOne: +|Because the allInOne image deploys the agent, collector, query, ingester, Jaeger UI in a single pod, configuration for this deployment should nest component configuration under the allInOne parameter. +| +| + +|agent: +|Configuration options that define the Jaeger agent. +| +| + +|collector: +|Configuration options that define the Jaeger Collector. +| +| + +|sampling: +|Configuration options that define the sampling strategies for tracing. +| +| + +|storage: +|Configuration options that define the storage. All storage related options should be placed under `storage`, rather than under the `allInOne` or other component options. +| +| + +|query: +|Configuration options that define the Query service. +| +| + +|ingester: +|Configuration options that define the Ingester service. +| +| + +|=== + + +The following example YAML is the minimum required to create a Jaeger instance using the default settings. + +.Example minimum required jaeger-all-in-one.yaml +[source,yaml] +---- +apiVersion: jaegertracing.io/v1 +kind: Jaeger +metadata: + name: jaeger-all-in-one-inmemory +---- diff --git a/modules/jaeger-config-ingester.adoc b/modules/jaeger-config-ingester.adoc new file mode 100644 index 000000000000..75080d252865 --- /dev/null +++ b/modules/jaeger-config-ingester.adoc @@ -0,0 +1,90 @@ +//// +This REFERENCE module included in the following assemblies: +-rhbjaeger-deploy.adoc +//// + +[id="jaeger-config-ingester_{context}"] += Jaeger Ingester configuration options + +Ingester is a service that reads from Kafka topic and writes to another storage backend (Elasticsearch). If you are using the `allInOne` or `production` deployment strategies, you do not need to configure the Ingester service. + + +.Jaeger default parameters +[options="header"] +[cols="l, a, a, a"] +|=== +|Parameter |Description |Values |Default value +|spec: + strategy: streaming + ingester: + options: {} +|Configuration options that define the Ingester service. +| +| + +|ingester: + options: + kafka: + consumer: + 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. +|Label for the consumer +| + +|ingester: + options: + kafka: + consumer: + brokers: my-cluster-kafka-brokers.kafka:9092 +|Identifies the Kafka configuration used by the Ingester to consume the messages. +| +| + +|ingester: + options: + ingester: + deadlockInterval: 5 +| Specifies the interval (in seconds or minutes) that the Ingester should wait for a message before terminating. +The deadlock interval is disabled by default (set to 0), to avoid the Ingester being terminated when no messages arrive while the system is being initialized. +|Minutes and seconds, for example, 1m0s. +|0 + + +|options: + log-level: +|Logging level for the Ingester. +|Possible values: `trace`, `debug`, `info`, `warning`, `error`, `fatal`, `panic`. +| +|=== + + + +.Streaming Collector and Ingester example +[source,yaml] +---- +apiVersion: jaegertracing.io/v1 +kind: Jaeger +metadata: + name: simple-streaming +spec: + strategy: streaming + collector: + options: + kafka: + producer: + topic: jaeger-spans + brokers: my-cluster-kafka-brokers.kafka:9092 + ingester: + options: + kafka: + consumer: + topic: jaeger-spans + brokers: my-cluster-kafka-brokers.kafka:9092 + ingester: + deadlockInterval: 5 + storage: + type: elasticsearch + options: + es: + server-urls: http://elasticsearch:9200 +---- diff --git a/modules/jaeger-config-query.adoc b/modules/jaeger-config-query.adoc new file mode 100644 index 000000000000..37974239858e --- /dev/null +++ b/modules/jaeger-config-query.adoc @@ -0,0 +1,66 @@ +//// +This REFERENCE module included in the following assemblies: +-rhbjaeger-deploy.adoc +//// + +[id="jaeger-config-query_{context}"] += Jaeger Query configuration options + +Query is a service that retrieves traces from storage and hosts the user interface to display them. + +.Jaeger Query parameters +[options="header"] +[cols="l, a, a, a"] +|=== +|Parameter |Description |Values |Default value + +|spec: + query: + options: {} + resources: {} +|Configuration options that define the Query service. +| +| + +|query: + additional-headers: +|Additional HTTP response headers. Can be specified multiple times. +|Format: "Key: Value" +| + +|query: + base-path: +|The base path for all jaeger-query HTTP routes can be set to a non-root value, for example, `/jaeger` would cause all UI URLs to start with `/jaeger`. This can be useful when running jaeger-query behind a reverse proxy. +|/{path} +| + +|query: + port: +|The port for the query service. +| +|16686 + + +|options: + log-level: +|Logging level for Query. +|Possible values: `trace`, `debug`, `info`, `warning`, `error`, `fatal`, `panic`. +| +|=== + +.Sample Query configuration +[source,yaml] +---- +apiVersion: jaegertracing.io/v1 +kind: "Jaeger" +metadata: + name: "my-jaeger" +spec: + strategy: allInOne + allInOne: + options: + log-level: debug + query: + base-path: /jaeger + +---- diff --git a/modules/jaeger-config-sampling.adoc b/modules/jaeger-config-sampling.adoc new file mode 100644 index 000000000000..59c42baa05bf --- /dev/null +++ b/modules/jaeger-config-sampling.adoc @@ -0,0 +1,72 @@ +//// +This REFERENCE module included in the following assemblies: +-rhbjaeger-deploy.adoc +//// + +[id="jaeger-config-sampling_{context}"] += Jaeger sampling configuration options + +The operator can be used to define sampling strategies that will be supplied to tracers that have been configured to use a remote sampler. + +While all traces are generated, only a few are sampled. Sampling a trace marks the trace for further processing and storage. + +[NOTE] +==== +This is not relevant if a trace was started by the Istio proxy as the sampling decision is made there. The Jaeger sampling decision is only relevant when the trace is started by an application using the Jaeger tracer. +==== + +When a service receives a request that contains no trace context, the Jaeger tracer will start a new trace, assign it a random trace ID, and make a sampling decision based on the currently installed sampling strategy. The sampling decision is propagated to all subsequent requests in the trace, so that other services are not making the sampling decision again. + +Jaeger libraries support the following samplers: + +* *Constant* - The sampler always makes the same decision for all traces. It either samples all traces (sampling.param=1) or none of them (sampling.param=0). + +* *Probabilistic* - The sampler makes a random sampling decision with the probability of sampling equal to the value of the `sampling.param` property. For example, with sampling.param=0.1 approximately 1 in 10 traces will be sampled. + +* *Rate Limiting* - The sampler uses a leaky bucket rate limiter to ensure that traces are sampled with a certain constant rate. For example, when sampling.param=2.0 it will sample requests with the rate of 2 traces per second. + +* *Remote* - The sampler consults the Jaeger agent for the appropriate sampling strategy to use in the current service. This allows controlling the sampling strategies in the services from a central configuration in the Jaeger backend. + +.Jaeger sampling parameters +[options="header"] +[cols="l, a, a, a"] +|=== +|Parameter |Description |Values |Default value + +|spec: + sampling: + options: {} +|Configuration options that define the sampling strategies for tracing. +| +| + +|sampling:type: +|Sampling strategy to use. (See descriptions above.) +|Valid values are `const`, `probabilistic`, `ratelimiting`, and `remote`. +|`remote` + +|sampling:options:type:param: +|Parameters for the selected sampling strategy (See examples above) +|Decimal and integer values (0, .1. 1, 10) +|N/A +|=== + + +This example defines a default sampling strategy that is probabilistic, with a 50% chance of the trace instances being sampled. + +.Probabilistic sampling example +[source,yaml] +---- +apiVersion: jaegertracing.io/v1 +kind: Jaeger +metadata: + name: with-sampling +spec: + strategy: allInOne + sampling: + options: + default_strategy: + type: probabilistic + param: 50 + +---- diff --git a/modules/jaeger-config-storage.adoc b/modules/jaeger-config-storage.adoc new file mode 100644 index 000000000000..87ff419403c8 --- /dev/null +++ b/modules/jaeger-config-storage.adoc @@ -0,0 +1,190 @@ +//// +This REFERENCE module included in the following assemblies: +-rhbjaeger-deploy.adoc +//// + +[id="jaeger-config-storage_{context}"] += Jaeger storage configuration options + +The query and collector services are configured with a supported storage type; Elasticsearch. Multiple instances of each of these components can be provisioned as required for performance and resilience purposes. + +When there is no `es.server-urls` option as part of a Jaeger production instance and Elasticsearch is set as the storage type, the Jaeger Operator creates an Elasticsearch cluster via the Elasticsearch Operator by creating a Custom Resource based on the configuration provided in storage section. The Elasticsearch cluster is meant to be dedicated for a single Jaeger instance. + +.Restrictions + +* There can be only one Jaeger with self-provisioned Elasticsearch instance per namespace. +* There can be only one Elasticsearch per namespace. +* You cannot share or reuse a {Product-Name} logging Elasticsearch instance with Jaeger. + + +.Jaeger storage parameters +[options="header"] +[cols="l, a, a, a"] +|=== +|Parameter |Description |Values |Default value + + +|spec: + storage: + options: {} +|Configuration options that define the storage. +| +| + +|storage: + type: +|Type of storage to use for the deployment. +|`memory` or `elasticsearch` +|`memory` + +|storage: + options: + es: + server-urls: +|URL of the Elasticsearch instance. +|The fully-qualified domain name of the Elasticsearch server. +|`http://elasticsearch..svc:9200` + +|storage: + 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. +|Integer value. For example, Proof of concept = 1, +Minimum deployment =3 +|1 + +|storage: + elasticsearch: + redundancyPolicy: +|Controls number of Elasticsearch replica shards. +|`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) +| + +|storage: + elasticsearch: + resources: + 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). For example, Proof of concept = 500m, +Minimum deployment =1 +|1Gi + +|storage: + elasticsearch: + resources: + requests: + memory: +|Available memory for requests, based on your environment’s configuration. +|Specified in bytes (for example, 200Ki, 50Mi, 5Gi). For example, Proof of concept = 1Gi, +Minimum deployment = 16Gi* +|500m + +|storage: + elasticsearch: + resources: + 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). For example, Proof of concept = 500m, +Minimum deployment =1 +| + +|storage: + elasticsearch: + resources: + limits: + memory: +|Available memory limit based on your environment’s configuration. +|Specified in bytes (for example, 200Ki, 50Mi, 5Gi). For example, Proof of concept = 1Gi, +Minimum deployment = 16Gi* +| + +|storage: + elasticsearch: + secretname: +|Name of the secret, for example `jaeger-secret`. +| +|N/A + + +|storage: + esIndexCleaner: + enabled: +|When using Elasticsearch storage, by default a job is created to clean old traces from the index. This parameter enables or disables the index cleaner job. +|`true`/ `false` +|`true` + +|storage: + esIndexCleaner: + numberOfDays: +|Number of days to wait before deleting an index. +|Integer value +|`7` + +|storage: + esIndexCleaner: + schedule: +|Defines the schedule for how often to clean the Elasticsearch index. +|Cron expression +|"55 23 * * *" + +|storage: + esRollover: + schedule: +|Defines the schedule for how often to rollover to a new Elasticsearch index. +|Cron expression +|'*/30 * * * *' +| +3+|{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. +|=== + +.Production storage example +[source,yaml] +---- +apiVersion: jaegertracing.io/v1 +kind: Jaeger +metadata: + name: simple-prod +spec: + strategy: production + storage: + type: elasticsearch + elasticsearch: + nodeCount: 3 + resources: + requests: + cpu: 1 + memory: 16Gi + limits: + memory: 16Gi +---- + + +.Storage example with volume mounts +[source,yaml] +---- +apiVersion: jaegertracing.io/v1 +kind: Jaeger +metadata: + name: simple-prod +spec: + strategy: production + storage: + type: elasticsearch + options: + es: + server-urls: https://quickstart-es-http.default.svc:9200 + index-prefix: my-prefix + tls: + ca: /es/certificates/ca.crt + secretName: jaeger-secret + volumeMounts: + - name: certificates + mountPath: /es/certificates/ + readOnly: true + volumes: + - name: certificates + secret: + secretName: quickstart-es-http-certs-public +---- diff --git a/modules/jaeger-deploy-default.adoc b/modules/jaeger-deploy-default.adoc new file mode 100644 index 000000000000..fb0e9c918ff7 --- /dev/null +++ b/modules/jaeger-deploy-default.adoc @@ -0,0 +1,106 @@ +//// +This PROCEDURE module included in the following assemblies: +- rhbjaeger-deploying.adoc +//// + +[id="jaeger-deploy-default_{context}"] += Deploying the default Jaeger strategy from the web console + +The custom resource definition (CRD) defines the configuration used when you deploy an instance of Jaeger. The default CR for Jaeger is named `jaeger-all-in-one-inmemory` and it is configured with minimal resources to ensure that you can successfully install it on a default {product-title} installation. You can use this default configuration to create a Jaeger instance that uses the `AllInOne` deployment strategy, or you can define your own custom resource file. + +[NOTE] +==== +In-memory storage is not persistent, which means that if the Jaeger pod shuts down, restarts, or is replaced, that your trace data will be lost. For persistent storage, you must use the `production` or `streaming` strategies, which use Elasticsearch as the default storage. +==== + + +.Prerequisites + +* The Jaeger Operator must be installed. +* Review the instructions for how to customize the Jaeger installation. +* An account with the `cluster-admin` role. + +.Procedure + +. Log in to the {product-title} web console as a user with the `cluster-admin` role. + +. Create a new project, for example `jaeger-system`. + +.. Navigate to *Home* -> *Projects*. + +.. Click *Create Project*. + +.. Enter `jaeger-system` in the *Name* field. + +.. Click *Create*. + +. Navigate to *Operators* -> *Installed Operators*. + +. If necessary, select `jaeger-system` from the Project menu. You may have to wait a few moments for the Operators to be copied to the new project. + +. Click the {ProductName} Operator. On the *Overview* tab, under *Provided APIs*, the Operator provides a single link. + +. Under *Jaeger* click *Create Instance*. + +. On the *Create Jaeger* page, to install using the defaults, click *Create* to create the Jaeger instance. + +. On the *Jaegers* page, click the name of the Jaeger instance, for example, `jaeger-all-in-one-inmemory`. + +. On the *Jaeger Details* page, click the *Resources* tab. Wait until the Pod has a status of "Running" before continuing. + + +[id="jaeger-create-cli_{context}"] +== Deploying default Jaeger from the CLI + +Follow this procedure to create an instance of Jaeger from the command line. + +.Prerequisites + +* An installed, verified {ProductName} Operator. +* Access to the {product-title} Command-line Interface (CLI) commonly known as `oc` that matches your {product-title} version. +* An account with the `cluster-admin` role. + +Procedure + +. Log in to the {product-title} CLI as a user with the `cluster-admin` role. ++ +---- +$ oc login https://{HOSTNAME}:8443 +---- + +. Create a new project named `jaeger-system`. ++ +---- +$ oc new-project jaeger-system +---- + +. Create a custom resource file named `jaeger.yaml` that contains the following text: ++ +.Example jaeger-all-in-one.yaml +[source,yaml] +---- +apiVersion: jaegertracing.io/v1 +kind: Jaeger +metadata: + name: jaeger-all-in-one-inmemory +---- ++ + +. Run the following command to deploy Jaeger: ++ +---- +$ oc create -n jaeger-system -f jaeger.yaml +---- ++ +. Run the following command to watch the progress of the Pods during the installation process: ++ +---- +$ oc get pods -n jaeger-system -w +---- ++ +Once the installation process has completed, you should see output similar to the following: ++ +---- +NAME READY STATUS RESTARTS AGE +jaeger-all-in-one-inmemory-cdff7897b-qhfdx 2/2 Running 0 24s +---- diff --git a/modules/jaeger-deploy-production-es.adoc b/modules/jaeger-deploy-production-es.adoc new file mode 100644 index 000000000000..4f21db6832ee --- /dev/null +++ b/modules/jaeger-deploy-production-es.adoc @@ -0,0 +1,126 @@ +//// +This PROCEDURE module included in the following assemblies: +- rhbjaeger-deploying.adoc +//// + +[id="jaeger-deploy-production_{context}"] += Deploying the Jaeger production strategy from the web console + +The `production` deployment 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. + +.Prerequisites + +* The Elasticsearch Operator must be installed. +* The Jaeger Operator must be installed. +* Review the instructions for how to customize the Jaeger installation. +* An account with the `cluster-admin` role. + +.Procedure + +. Log in to the {product-title} web console as a user with the `cluster-admin` role. + +. Create a new project, for example `jaeger-system`. + +.. Navigate to *Home* -> *Projects*. + +.. Click *Create Project*. + +.. Enter `jaeger-system` in the *Name* field. + +.. Click *Create*. + +. Navigate to *Operators* -> *Installed Operators*. + +. If necessary, select `jaeger-system` from the Project menu. You may have to wait a few moments for the Operators to be copied to the new project. + +. Click the Jaeger Operator. On the *Overview* tab, under *Provided APIs*, the Operator provides a single link. + +. Under *Jaeger* click *Create Instance*. + +. On the *Create Jaeger* page, replace the default `all-in-one` yaml text with your production YAML configuration, for example: + ++ +.Example jaeger-production.yaml file with Elasticsearch +[source,yaml] +---- +apiVersion: jaegertracing.io/v1 +kind: Jaeger +metadata: + name: jaeger-production + namespace: +spec: + strategy: production + ingress: + security: oauth-proxy + storage: + type: elasticsearch + elasticsearch: + nodeCount: 3 + redundancyPolicy: SingleRedundancy + esIndexCleaner: + enabled: true + numberOfDays: 7 + schedule: 55 23 * * * + esRollover: + schedule: '*/30 * * * *' +---- ++ + +. Click *Create* to create the Jaeger instance. + + +. On the *Jaegers* page, click the name of the Jaeger instance, for example, `jaeger-prod-elasticsearch`. + +. On the *Jaeger Details* page, click the *Resources* tab. Wait until all the pods have a status of "Running" before continuing. + + +[id="jaeger-deploy-production-cli_{context}"] +== Deploying Jaeger production from the CLI + +Follow this procedure to create an instance of Jaeger from the command line. + +.Prerequisites + +* An installed, verified {ProductName} Operator. +* Access to the {product-title} Command-line Interface (CLI) commonly known as `oc`. +* An account with the `cluster-admin` role. + +.Procedure + +. Log in to the {product-title} CLI as a user with the `cluster-admin` role. ++ +---- +$ oc login https://{HOSTNAME}:8443 +---- + +. Create a new project named `jaeger-system`. ++ +---- +$ oc new-project jaeger-system +---- + +. Create a custom resource file named `jaeger-production.yaml` that contains the text of the example file in the previous procedure. + +. Run the following command to deploy Jaeger: ++ +---- +$ oc create -n jaeger-system -f jaeger-production.yaml +---- ++ +. Run the following command to watch the progress of the Pods during the installation process: ++ +---- +$ oc get pods -n jaeger-system -w +---- ++ +Once the installation process has completed, you should see output similar to the following: ++ +---- +NAME READY STATUS RESTARTS AGE +elasticsearch-cdm-jaegersystemjaegerproduction-1-6676cf568gwhlw 2/2 Running 0 10m +elasticsearch-cdm-jaegersystemjaegerproduction-2-bcd4c8bf5l6g6w 2/2 Running 0 10m +elasticsearch-cdm-jaegersystemjaegerproduction-3-844d6d9694hhst 2/2 Running 0 10m +jaeger-production-collector-94cd847d-jwjlj 1/1 Running 3 8m32s +jaeger-production-query-5cbfbd499d-tv8zf 3/3 Running 3 8m32s + +---- diff --git a/modules/jaeger-deploy-streaming.adoc b/modules/jaeger-deploy-streaming.adoc new file mode 100644 index 000000000000..da2f81ba4d12 --- /dev/null +++ b/modules/jaeger-deploy-streaming.adoc @@ -0,0 +1,130 @@ +//// +This PROCEDURE module included in the following assemblies: +- rhbjaeger-deploying.adoc +//// + +[id="jaeger-deploy-streaming_{context}"] += Deploying the Jaeger streaming strategy from the web console + +The `streaming` deployment 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. + +The `streaming` strategy provides a streaming capability that sits between the collector and the storage (Elasticsearch). This reduces the pressure on the 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 (Kafka). + +.Prerequisites +* The AMQ Streams Operator must be installed. If using version 1.4.0 or higher you can use self-provisioning. If otherwise, you need to create the Kafka instance. +* The Jaeger Operator must be installed. +* Review the instructions for how to customize the Jaeger installation. +* An account with the `cluster-admin` role. + +.Procedure + +. Log in to the {product-title} web console as a user with the `cluster-admin` role. + +. Create a new project, for example `jaeger-system`. + +.. Navigate to *Home* -> *Projects*. + +.. Click *Create Project*. + +.. Enter `jaeger-system` in the *Name* field. + +.. Click *Create*. + +. Navigate to *Operators* -> *Installed Operators*. + +. If necessary, select `jaeger-system` from the Project menu. You may have to wait a few moments for the Operators to be copied to the new project. + +. Click the Jaeger Operator. On the *Overview* tab, under *Provided APIs*, the Operator provides a single link. + +. Under *Jaeger* click *Create Instance*. + +. On the *Create Jaeger* page, replace the default `all-in-one` yaml text with your streaming YAML configuration, for example: + +.Example jaeger-streaming.yaml file +[source,yaml] +---- +apiVersion: jaegertracing.io/v1 +kind: Jaeger +metadata: + name: jaeger-streaming +spec: + strategy: streaming + collector: + options: + kafka: + producer: + topic: jaeger-spans + #Note: If brokers are not defined,AMQStreams 1.4.0+ will self-provision Kafka. + brokers: my-cluster-kafka-brokers.kafka:9092 + storage: + type: elasticsearch + ingester: + options: + kafka: + consumer: + topic: jaeger-spans + brokers: my-cluster-kafka-brokers.kafka:9092 + +---- +//TODO - find out if this storage configuration is correct for OpenShift + +. Click *Create* to create the Jaeger instance. + +. On the *Jaegers* page, click the name of the Jaeger instance, for example, `jaeger-streaming`. + +. On the *Jaeger Details* page, click the *Resources* tab. Wait until all the pods have a status of "Running" before continuing. + + +[id="jaeger-deploy-streaming-cli_{context}"] +== Deploying Jaeger streaming from the CLI + +Follow this procedure to create an instance of Jaeger from the command line. + +.Prerequisites + +* An installed, verified {ProductName} Operator. +* Access to the {product-title} Command-line Interface (CLI) commonly known as `oc`. +* An account with the `cluster-admin` role. + +Procedure + +. Log in to the {product-title} CLI as a user with the `cluster-admin` role. ++ +---- +$ oc login https://{HOSTNAME}:8443 +---- + +. Create a new project named `jaeger-system`. ++ +---- +$ oc new-project jaeger-system +---- + +. Create a custom resource file named `jaeger-streaming.yaml` that contains the text of the example file in the previous procedure. + +. Run the following command to deploy Jaeger: ++ +---- +$ oc create -n jaeger-system -f jaeger-streaming.yaml +---- ++ +. Run the following command to watch the progress of the Pods during the installation process: ++ +---- +$ oc get pods -n jaeger-system -w +---- ++ +Once the installation process has completed, you should see output similar to the following: ++ +---- +NAME READY STATUS RESTARTS AGE +elasticsearch-cdm-jaegersystemjaegerstreaming-1-697b66d6fcztcnn 2/2 Running 0 5m40s +elasticsearch-cdm-jaegersystemjaegerstreaming-2-5f4b95c78b9gckz 2/2 Running 0 5m37s +elasticsearch-cdm-jaegersystemjaegerstreaming-3-7b6d964576nnz97 2/2 Running 0 5m5s +jaeger-streaming-collector-6f6db7f99f-rtcfm 1/1 Running 0 80s +jaeger-streaming-entity-operator-6b6d67cc99-4lm9q 3/3 Running 2 2m18s +jaeger-streaming-ingester-7d479847f8-5h8kc 1/1 Running 0 80s +jaeger-streaming-kafka-0 2/2 Running 0 3m1s +jaeger-streaming-query-65bf5bb854-ncnc7 3/3 Running 0 80s +jaeger-streaming-zookeeper-0 2/2 Running 0 3m39s +---- diff --git a/modules/jaeger-document-attributes.adoc b/modules/jaeger-document-attributes.adoc index d4527cb7edd6..354888453a31 100644 --- a/modules/jaeger-document-attributes.adoc +++ b/modules/jaeger-document-attributes.adoc @@ -3,7 +3,7 @@ // The following are shared by all RH Build of Jaeger documents: :toc: :toclevels: 4 -:toc-title: +:toc-title: :experimental: // // Product content attributes, that is, substitution variables in the files. @@ -21,15 +21,17 @@ // Note that the DocInfoProductName generates the URL for the product page. // Changing the value changes the generated URL. // + :DocInfoProductName: Red Hat OpenShift Jaeger +:DocInfoProductName: OpenShift Jaeger :DocInfoProductNumber: 1.17.1 // // Book Names: -// Defining the book names in document attributes instead of hard-coding them in -// the master.adoc files and in link references. This makes it easy to change the -// book name if necessary. -// Using the pattern ending in 'BookName' makes it easy to grep for occurrences -// throughout the topics +// Defining the book names in document attributes instead of hard-coding them in +// the master.adoc files and in link references. +//This makes it easy to change the book name if necessary. +// Using the pattern ending in 'BookName' makes it easy to grep for occurrences +// throughout the topics // :RN_BookName: Red Hat OpenShift Jaeger Release Notes :Install_BookName: Installing Red Hat OpenShift Jaeger diff --git a/modules/jaeger-features.adoc b/modules/jaeger-features.adoc index 6aab9997fbf7..c32a2cd419cd 100644 --- a/modules/jaeger-features.adoc +++ b/modules/jaeger-features.adoc @@ -15,4 +15,4 @@ Jaeger tracing provides the following capabilities: * Distributed Context Propagation – Lets you connect data from different components together to create a complete end-to-end trace. -* Backwards compatibility with Zipkin – Jaeger provides backwards compatibility with Zipkin by accepting spans in Zipkin formats (Thrift or JSON v1/v2) over HTTP. +* Backwards compatibility with Zipkin – Jaeger has APIs that enable it to be used as a drop-in replacement for Zipkin, but Red Hat is not supporting Zipkin compatibility in this release. diff --git a/modules/jaeger-install-elasticsearch.adoc b/modules/jaeger-install-elasticsearch.adoc index 6985a583ec16..05fb3f52ce3f 100644 --- a/modules/jaeger-install-elasticsearch.adoc +++ b/modules/jaeger-install-elasticsearch.adoc @@ -4,7 +4,7 @@ // - rhbjaeger-installation.adoc -[id="ossm-operator-install-elasticsearch_{context}"] +[id="jaeger-operator-install-elasticsearch_{context}"] = Installing the Elasticsearch Operator The default Jaeger deployment uses in-memory storage because it is designed to be installed quickly for those evaluating Jaeger, giving demonstrations, or using Jaeger in a test environment. If you plan to use Jaeger in production, you must install a persistent storage option, in this case, Elasticsearch. diff --git a/modules/jaeger-sidecar-automatic.adoc b/modules/jaeger-sidecar-automatic.adoc new file mode 100644 index 000000000000..c3b3650ffa0f --- /dev/null +++ b/modules/jaeger-sidecar-automatic.adoc @@ -0,0 +1,38 @@ +//// +This PROCEDURE module included in the following assemblies: +- rhbjaeger-deploying.adoc +//// + +[id="jaeger-sidecar-automatic_{context}"] += Automatically injecting sidecars +:pantheon-module-type: PROCEDURE + +To enable this feature, you add the annotation `sidecar.jaegertracing.io/inject` set to either the string `true` or the Jaeger instance name as returned by `oc get jaegers`. +When you specify `true`, there should be only a single Jaeger instance for the same namespace as the deployment, otherwise, the Operator cannot determine which Jaeger instance to use. A specific Jaeger instance name on a deployment has a higher precedence than `true` applied on its namespace. + +The following snippet shows a simple application that will inject a sidecar, with the Jaeger Agent pointing to the single Jaeger instance available in the same namespace: + +.sample automatic sidecar injection +[source,yaml] +---- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: myapp + annotations: + "sidecar.jaegertracing.io/inject": "true" # <1> +spec: + selector: + matchLabels: + app: myapp + template: + metadata: + labels: + app: myapp + spec: + containers: + - name: myapp + image: acme/myapp:myversion +---- + +When the sidecar is injected, the Jaeger Agent can then be accessed at its default location on `localhost`. diff --git a/modules/jaeger-sidecar-manual.adoc b/modules/jaeger-sidecar-manual.adoc new file mode 100644 index 000000000000..b4e5b07edcb1 --- /dev/null +++ b/modules/jaeger-sidecar-manual.adoc @@ -0,0 +1,58 @@ +//// +This PROCEDURE module included in the following assemblies: +- rhbjaeger-deploying.adoc +//// + +[id="jaeger-sidecar-manual_{context}"] += Manually injecting sidecars +:pantheon-module-type: PROCEDURE + +For controller types other than `Deployments` (for example, `StatefulSets`, `DaemonSets`, etc.), you can manually define the Jaeger Agent sidecar in your specification. + +The following snippet shows the manual definition you can include in your containers section for a Jaeger Agent sidecar: + +.example sidecar definition for a StatefulSet +[source,yaml] +---- +apiVersion: apps/v1 +kind: StatefulSet +metadata: + name: example-statefulset + namespace: example-ns + labels: + app: example-app +spec: + + spec: + containers: + - name: example-app + image: acme/myapp:myversion + ports: + - containerPort: 8080 + protocol: TCP + - name: jaeger-agent + image: registry.redhat.io/distributed-tracing/jaeger-agent-rhel7: + # The agent version must match the operator version + imagePullPolicy: IfNotPresent + ports: + - containerPort: 5775 + name: zk-compact-trft + protocol: UDP + - containerPort: 5778 + name: config-rest + protocol: TCP + - containerPort: 6831 + name: jg-compact-trft + protocol: UDP + - containerPort: 6832 + name: jg-binary-trft + protocol: UDP + - containerPort: 14271 + name: admin-http + protocol: TCP + args: + - --reporter.grpc.host-port=dns:///jaeger-collector-headless.example-ns:14250 + - --reporter.type=grpc +---- + +The Jaeger Agent can then be accessed at its default location on localhost. diff --git a/pipelines/op-release-notes.adoc b/pipelines/op-release-notes.adoc index b9b768a5bb65..e28720343411 100644 --- a/pipelines/op-release-notes.adoc +++ b/pipelines/op-release-notes.adoc @@ -28,8 +28,10 @@ For questions and feedback, you can send an email to the product team at pipelin // Modules included, most to least recent include::modules/op-release-notes-1-0.adoc[leveloffset=+1] + //// [id="additional-resources"] .Additional resources * For more information on uninstalling the {pipelines-title} Operator, see the xref:../pipelines/uninstalling-pipelines.adoc#uninstalling-pipelines[uninstalling OpenShift Pipelines] section. +////