From 14026b57a81b52f6ab71f6a3ebf6c46a3e7d2032 Mon Sep 17 00:00:00 2001 From: rh-tokeefe Date: Wed, 10 Nov 2021 09:18:51 -0500 Subject: [PATCH] OSSMDOC-385: Jaeger 1.26 release notes and product name change --- _topic_map.yml | 27 +- .../distributed-tracing-architecture.adoc | 44 ++ .../distributed_tracing_arch/images | 1 + .../distributed_tracing_arch/modules | 1 + .../distributed_tracing_config/modules | 1 + .../distributed-tracing-deploying.adoc | 79 +++ .../distributed-tracing-installation.adoc | 42 ++ .../distributed-tracing-removing.adoc | 27 + .../distributed-tracing-updating.adoc | 14 + .../distributed_tracing_install/modules | 1 + distributed_tracing/images | 1 + distributed_tracing/modules | 1 + ...ibuted-tracing-platform-release-notes.adoc | 22 + modules/distributed-tracing-architecture.adoc | 25 + .../distributed-tracing-config-collector.adoc | 66 ++ .../distributed-tracing-config-default.adoc | 126 ++++ .../distributed-tracing-config-ingester.adoc | 76 +++ modules/distributed-tracing-config-query.adoc | 68 ++ .../distributed-tracing-config-sampling.adoc | 99 +++ .../distributed-tracing-config-storage.adoc | 617 ++++++++++++++++++ .../distributed-tracing-deploy-default.adoc | 115 ++++ ...tributed-tracing-deploy-production-es.adoc | 129 ++++ .../distributed-tracing-deploy-streaming.adoc | 145 ++++ ...ted-tracing-deployment-best-practices.adoc | 17 + ...stributed-tracing-document-attributes.adoc | 39 ++ modules/distributed-tracing-features.adoc | 18 + ...ributed-tracing-install-elasticsearch.adoc | 57 ++ .../distributed-tracing-install-overview.adoc | 19 + modules/distributed-tracing-install.adoc | 49 ++ .../distributed-tracing-product-overview.adoc | 21 + ...ributed-tracing-removing-instance-cli.adoc | 84 +++ ...distributed-tracing-removing-instance.adoc | 28 + .../distributed-tracing-rn-fixed-issues.adoc | 29 + .../distributed-tracing-rn-known-issues.adoc | 34 + .../distributed-tracing-rn-new-features.adoc | 37 ++ ...ributed-tracing-rn-technology-preview.adoc | 27 + ...distributed-tracing-sidecar-automatic.adoc | 38 ++ .../distributed-tracing-sidecar-manual.adoc | 58 ++ modules/distributed-tracing-upgrading-es.adoc | 88 +++ ...distributed-tracing-upgrading-esearch.adoc | 88 +++ .../ossm-accessing-distributed-tracing.adoc | 34 + ...m-config-external-distributed-tracing.adoc | 39 ++ ...ring-distributed-tracing-existing-v1x.adoc | 94 +++ ...m-configuring-distributed-tracing-v1x.adoc | 183 ++++++ .../ossm-configuring-distributed-tracing.adoc | 11 + ...figuring-external-distributed-tracing.adoc | 16 + .../ossm-deploying-distributed-tracing.adoc | 135 ++++ ...uted-tracing-config-elasticsearch-v1x.adoc | 130 ++++ ...ributed-tracing-config-es-cleaner-v1x.adoc | 41 ++ ...ossm-distributed-tracing-service-mesh.adoc | 18 + .../ossm-enabling-distributed-tracing.adoc | 34 + ...distributed-tracing-generating-traces.adoc | 51 ++ ...serverless-distributed-tracing-config.adoc | 66 ++ service_mesh/v2x/ossm-observability.adoc | 2 +- .../ossm-reference-distributed-tracing.adoc | 37 ++ 55 files changed, 3346 insertions(+), 3 deletions(-) create mode 100644 distributed_tracing/distributed_tracing_arch/distributed-tracing-architecture.adoc create mode 120000 distributed_tracing/distributed_tracing_arch/images create mode 120000 distributed_tracing/distributed_tracing_arch/modules create mode 120000 distributed_tracing/distributed_tracing_config/modules create mode 100644 distributed_tracing/distributed_tracing_install/distributed-tracing-deploying.adoc create mode 100644 distributed_tracing/distributed_tracing_install/distributed-tracing-installation.adoc create mode 100644 distributed_tracing/distributed_tracing_install/distributed-tracing-removing.adoc create mode 100644 distributed_tracing/distributed_tracing_install/distributed-tracing-updating.adoc create mode 120000 distributed_tracing/distributed_tracing_install/modules create mode 120000 distributed_tracing/images create mode 120000 distributed_tracing/modules create mode 100644 distributed_tracing/rhos-distributed-tracing-platform-release-notes.adoc create mode 100644 modules/distributed-tracing-architecture.adoc create mode 100644 modules/distributed-tracing-config-collector.adoc create mode 100644 modules/distributed-tracing-config-default.adoc create mode 100644 modules/distributed-tracing-config-ingester.adoc create mode 100644 modules/distributed-tracing-config-query.adoc create mode 100644 modules/distributed-tracing-config-sampling.adoc create mode 100644 modules/distributed-tracing-config-storage.adoc create mode 100644 modules/distributed-tracing-deploy-default.adoc create mode 100644 modules/distributed-tracing-deploy-production-es.adoc create mode 100644 modules/distributed-tracing-deploy-streaming.adoc create mode 100644 modules/distributed-tracing-deployment-best-practices.adoc create mode 100644 modules/distributed-tracing-document-attributes.adoc create mode 100644 modules/distributed-tracing-features.adoc create mode 100644 modules/distributed-tracing-install-elasticsearch.adoc create mode 100644 modules/distributed-tracing-install-overview.adoc create mode 100644 modules/distributed-tracing-install.adoc create mode 100644 modules/distributed-tracing-product-overview.adoc create mode 100644 modules/distributed-tracing-removing-instance-cli.adoc create mode 100644 modules/distributed-tracing-removing-instance.adoc create mode 100644 modules/distributed-tracing-rn-fixed-issues.adoc create mode 100644 modules/distributed-tracing-rn-known-issues.adoc create mode 100644 modules/distributed-tracing-rn-new-features.adoc create mode 100644 modules/distributed-tracing-rn-technology-preview.adoc create mode 100644 modules/distributed-tracing-sidecar-automatic.adoc create mode 100644 modules/distributed-tracing-sidecar-manual.adoc create mode 100644 modules/distributed-tracing-upgrading-es.adoc create mode 100644 modules/distributed-tracing-upgrading-esearch.adoc create mode 100644 modules/ossm-accessing-distributed-tracing.adoc create mode 100644 modules/ossm-config-external-distributed-tracing.adoc create mode 100644 modules/ossm-configuring-distributed-tracing-existing-v1x.adoc create mode 100644 modules/ossm-configuring-distributed-tracing-v1x.adoc create mode 100644 modules/ossm-configuring-distributed-tracing.adoc create mode 100644 modules/ossm-configuring-external-distributed-tracing.adoc create mode 100644 modules/ossm-deploying-distributed-tracing.adoc create mode 100644 modules/ossm-distributed-tracing-config-elasticsearch-v1x.adoc create mode 100644 modules/ossm-distributed-tracing-config-es-cleaner-v1x.adoc create mode 100644 modules/ossm-distributed-tracing-service-mesh.adoc create mode 100644 modules/ossm-enabling-distributed-tracing.adoc create mode 100644 modules/ossm-tutorial-distributed-tracing-generating-traces.adoc create mode 100644 modules/serverless-distributed-tracing-config.adoc create mode 100644 service_mesh/v2x/ossm-reference-distributed-tracing.adoc diff --git a/_topic_map.yml b/_topic_map.yml index ff51136d0e8a..4bc63bd52035 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -2799,8 +2799,8 @@ Topics: File: ossm-troubleshooting-istio - Name: Service Mesh configuration reference File: ossm-reference-smcp - - Name: Jaeger configuration reference - File: ossm-reference-jaeger + - Name: Distributed tracing configuration reference + File: ossm-reference-distributed-tracing - Name: Uninstalling Service Mesh File: removing-ossm - Name: Service Mesh 1.x @@ -2852,6 +2852,29 @@ Topics: - Name: Removing Jaeger File: rhbjaeger-removing --- +Name: Distributed Tracing +Dir: distributed_tracing +Distros: openshift-enterprise +Topics: +- Name: Distributed tracing release notes + File: rhos-distributed-tracing-platform-release-notes +- Name: Platform architecture + Dir: distributed_tracing_arch + Topics: + - Name: Platform architecture + File: distributed-tracing-architecture +- Name: Platform installation + Dir: distributed_tracing_install + Topics: + - Name: Installing platform + File: distributed-tracing-installation + - Name: Configuring platform + File: distributed-tracing-deploying + - Name: Upgrading platform + File: distributed-tracing-updating + - Name: Removing platform + File: distributed-tracing-removing +--- Name: Virtualization Dir: virt Distros: openshift-enterprise,openshift-origin diff --git a/distributed_tracing/distributed_tracing_arch/distributed-tracing-architecture.adoc b/distributed_tracing/distributed_tracing_arch/distributed-tracing-architecture.adoc new file mode 100644 index 000000000000..d5c3ab4de87e --- /dev/null +++ b/distributed_tracing/distributed_tracing_arch/distributed-tracing-architecture.adoc @@ -0,0 +1,44 @@ +[id="distributed-tracing-architecture"] += Distributed tracing platform architecture +include::modules/distributed-tracing-document-attributes.adoc[] +:context: distributed-tracing-architecture + +toc::[] + +Every time a user takes an action in an application, a request is executed by the architecture that may require dozens of different services to participate to produce a response. +Red Hat OpenShift distributed tracing platform lets you perform distributed tracing, which records the path of a request through various microservices that make up an application. + +_Distributed tracing_ is a technique that is used to tie the information about different units of work together — usually executed in different processes or hosts — to understand a whole chain of events in a distributed transaction. +Developers can visualize call flows in large microservice architectures with distributed tracing. +It's valuable for understanding serialization, parallelism, and sources of latency. + +Red Hat {ProductName} records the execution of individual requests across the whole stack of microservices, and presents them as traces. A _trace_ is a data/execution path through the system. An end-to-end trace is comprised of one or more spans. + +A _span_ represents a logical unit of work in Red Hat {ProductName} that has an operation name, the start time of the operation, and the duration, as well as potentially tags and logs. Spans may be nested and ordered to model causal relationships. + +// The following include statements pull in the module files that comprise the assembly. + +include::modules/distributed-tracing-product-overview.adoc[leveloffset=+1] + +include::modules/distributed-tracing-features.adoc[leveloffset=+1] + +include::modules/distributed-tracing-architecture.adoc[leveloffset=+1] + +//// +TODO +WRITE more detailed component docs + +include::modules/distributed-tracing-client-java.adoc[leveloffset=+1] + +include::modules/distributed-tracing-agent.adoc[leveloffset=+1] + +include::modules/distributed-tracing-collector.adoc[leveloffset=+1] + +include::modules/distributed-tracing-data-store.adoc[leveloffset=+1] + +include::modules/distributed-tracing-query.adoc[leveloffset=+1] + +include::modules/distributed-tracing-ingester.adoc[leveloffset=+1] + +include::modules/distributed-tracing-console.adoc[leveloffset=+1] +//// diff --git a/distributed_tracing/distributed_tracing_arch/images b/distributed_tracing/distributed_tracing_arch/images new file mode 120000 index 000000000000..e4c5bd02a10a --- /dev/null +++ b/distributed_tracing/distributed_tracing_arch/images @@ -0,0 +1 @@ +../images/ \ No newline at end of file diff --git a/distributed_tracing/distributed_tracing_arch/modules b/distributed_tracing/distributed_tracing_arch/modules new file mode 120000 index 000000000000..43aab75b53c9 --- /dev/null +++ b/distributed_tracing/distributed_tracing_arch/modules @@ -0,0 +1 @@ +../modules/ \ No newline at end of file diff --git a/distributed_tracing/distributed_tracing_config/modules b/distributed_tracing/distributed_tracing_config/modules new file mode 120000 index 000000000000..43aab75b53c9 --- /dev/null +++ b/distributed_tracing/distributed_tracing_config/modules @@ -0,0 +1 @@ +../modules/ \ No newline at end of file diff --git a/distributed_tracing/distributed_tracing_install/distributed-tracing-deploying.adoc b/distributed_tracing/distributed_tracing_install/distributed-tracing-deploying.adoc new file mode 100644 index 000000000000..bc8a9647f905 --- /dev/null +++ b/distributed_tracing/distributed_tracing_install/distributed-tracing-deploying.adoc @@ -0,0 +1,79 @@ +[id="distributed-tracing-deploying"] += Configuring and Deploying {ProductName} +include::modules/distributed-tracing-document-attributes.adoc[] +:context: distributed-tracing-deploying + +toc::[] + +The Red Hat {ProductName} operator uses a custom resource definition (CRD) file that defines the architecture and configuration settings to be used when creating and deploying the {ProductShortName} resources. You can either install the default configuration or modify the file to better suit your business requirements. + +{ProductName} has predefined deployment strategies. You specify a deployment strategy in the custom resource file. When you create a {ProductShortName} instance the operator uses this configuration file to create the objects necessary for the deployment. + +.{ProductName} custom resource file showing deployment strategy +[source,yaml] +---- +apiVersion: jaegertracing.io/v1 +kind: Jaeger +metadata: + name: simple-prod +spec: + strategy: production <1> +---- + +<1> The Red Hat {ProductName} operator currently supports the following deployment strategies: + +* *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 {ProductName} 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. 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]). ++ +[NOTE] +==== +The streaming strategy requires an additional Red Hat subscription for AMQ Streams. +==== + +[NOTE] +==== +There are two ways to install and use {ProductName}, as part of a service mesh or as a stand alone component. If you have installed {ProductName} as part of Red Hat OpenShift Service Mesh, you can configure and deploy {ProductName} as part of the xref:../../service_mesh/v2x/installing-ossm.adoc#installing-ossm[ServiceMeshControlPlane] or configure {ProductName} and then xref:../../service_mesh/v2x/ossm-observability.html#ossm-config-external-jaeger_observability[reference your Jaeger configuration in the ServiceMeshControlPlane]. + +==== + +// The following include statements pull in the module files that comprise the assembly. + +include::modules/distributed-tracing-deploy-default.adoc[leveloffset=+1] + +include::modules/distributed-tracing-deploy-production-es.adoc[leveloffset=+1] + +include::modules/distributed-tracing-deploy-streaming.adoc[leveloffset=+1] + +[id="customizing-jaeger-deployment"] +== Customizing Jaeger deployment + +include::modules/distributed-tracing-deployment-best-practices.adoc[leveloffset=+2] + +include::modules/distributed-tracing-config-default.adoc[leveloffset=+2] + +include::modules/distributed-tracing-config-collector.adoc[leveloffset=+2] + +include::modules/distributed-tracing-config-sampling.adoc[leveloffset=+2] + +include::modules/distributed-tracing-config-storage.adoc[leveloffset=+2] + +include::modules/distributed-tracing-config-query.adoc[leveloffset=+2] + +include::modules/distributed-tracing-config-ingester.adoc[leveloffset=+2] + +[id="injecting-sidecars"] +== Injecting sidecars + +{ProductName} relies on a proxy sidecar within the application's pod to provide the agent. The {ProductName} operator can inject Jaeger Agent sidecars into Deployment workloads. You can enable automatic sidecar injection or manage it manually. + +include::modules/distributed-tracing-sidecar-automatic.adoc[leveloffset=+2] + +include::modules/distributed-tracing-sidecar-manual.adoc[leveloffset=+2] diff --git a/distributed_tracing/distributed_tracing_install/distributed-tracing-installation.adoc b/distributed_tracing/distributed_tracing_install/distributed-tracing-installation.adoc new file mode 100644 index 000000000000..d095185b1bc4 --- /dev/null +++ b/distributed_tracing/distributed_tracing_install/distributed-tracing-installation.adoc @@ -0,0 +1,42 @@ +[id="installing-distributed-tracing"] += Installing {ProductName} +include::modules/distributed-tracing-document-attributes.adoc[] +:context: distributed-tracing-install + +toc::[] + +You can install Red Hat {ProductName} on {product-title} in either of two ways: + +* You can install Red Hat {ProductName} as part of Red Hat OpenShift Service Mesh. Distributed tracing platform is included by default in the Service Mesh installation. To install distributed tracing platform as part of a service mesh, follow the xref:../../service_mesh/v2x/preparing-ossm-installation.adoc#preparing-ossm-installation[Red Hat Service Mesh Installation] instructions. {ProductName} must be installed in the same namespace as your service mesh, that is, the `ServiceMeshControlPlane` and the distributed tracing platform resources must be in the same namespace. + +* If you do not want to install a service mesh, you can use the {ProductName} operator to install {ProductName} by itself. To install distributed tracing platform without a service mesh, use the following instructions. + +== Prerequisites + +Before you can install {ProductName}, review the installation activities, and ensure that you meet the prerequisites: + +* Possess an active {product-title} subscription on your Red Hat account. If you do not have a subscription, contact your sales representative for more information. + +* Review the xref:../../architecture/architecture-installation.adoc#installation-overview_architecture-installation[{product-title} {product-version} overview]. +* Install {product-title} {product-version}. + +** xref:../../installing/installing_aws/installing-aws-account.adoc#installing-aws-account[Install {product-title} {product-version} on AWS] +** xref:../../installing/installing_aws/installing-aws-user-infra.adoc#installing-aws-user-infra[Install {product-title} {product-version} on user-provisioned AWS] +** xref:../../installing/installing_bare_metal/installing-bare-metal.adoc#installing-bare-metal[Install {product-title} {product-version} on bare metal] +** xref:../../installing/installing_vsphere/installing-vsphere.adoc#installing-vsphere[Install {product-title} {product-version} on vSphere] +* Install the version of the OpenShift CLI (`oc`) that matches your {product-title} version and add it to your path. + +* An account with the `cluster-admin` role. + +// The following include statements pull in the module files that comprise the assembly. + +include::modules/distributed-tracing-install-overview.adoc[leveloffset=+1] + +include::modules/distributed-tracing-install-elasticsearch.adoc[leveloffset=+1] + +include::modules/distributed-tracing-install.adoc[leveloffset=+1] + +//// +== Next steps +* xref:../../jaeger/jaeger_install/rhbj-deploying.adoc#jaeger-deploying[Deploy {ProductName}]. +//// diff --git a/distributed_tracing/distributed_tracing_install/distributed-tracing-removing.adoc b/distributed_tracing/distributed_tracing_install/distributed-tracing-removing.adoc new file mode 100644 index 000000000000..98233a4ff0ff --- /dev/null +++ b/distributed_tracing/distributed_tracing_install/distributed-tracing-removing.adoc @@ -0,0 +1,27 @@ +[id="removing-distributed-tracing"] += Removing {ProductName} +include::modules/distributed-tracing-document-attributes.adoc[] +:context: removing-distributed-tracing + +toc::[] + +The steps for removing {ProductName} from an {product-title} cluster are as follows: + +. Shut down any {ProductName} pods. +. Remove any {ProductName} instances. +. Remove the {ProductName} Operator. + +include::modules/distributed-tracing-removing-instance.adoc[leveloffset=+1] + +include::modules/distributed-tracing-removing-instance-cli.adoc[leveloffset=+1] + + +== Removing the {ProductName} operator + +.Procedure + +. Follow the instructions for xref:../../operators/admin/olm-deleting-operators-from-cluster.adoc#olm-deleting-operators-from-a-cluster[Deleting Operators from a cluster]. + +* Remove the {ProductName} operator. + +* After the {ProductName} operator has been removed, if appropriate, remove the OpenShift Elasticsearch Operator. diff --git a/distributed_tracing/distributed_tracing_install/distributed-tracing-updating.adoc b/distributed_tracing/distributed_tracing_install/distributed-tracing-updating.adoc new file mode 100644 index 000000000000..959a175c92fb --- /dev/null +++ b/distributed_tracing/distributed_tracing_install/distributed-tracing-updating.adoc @@ -0,0 +1,14 @@ +[id="upgrading-distributed-tracing"] += Upgrading {ProductName} +include::modules/distributed-tracing-document-attributes.adoc[] +:context: upgrading-distributed-tracing + +toc::[] + +The Operator Lifecycle Manager (OLM) controls the installation, upgrade, and role-based access control (RBAC) of Operators in a cluster. The OLM runs by default in {product-title}. +The OLM queries for available Operators as well as upgrades for installed Operators. +For more information about how {product-title} handled upgrades, refer to the xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-understanding-olm[Operator Lifecycle Manager] documentation. + +The update approach used by the {ProductName} operator upgrades the managed {ProductShortName} instances to the version associated with the operator. Whenever a new version of the {ProductName} operator is installed, all the {ProductShortName} application instances managed by the operator will be upgraded to the operator's version. For example, if version 1.10 is installed (both operator and backend components) and the operator is upgraded to version 1.11, then as soon as the operator upgrade has completed, the Operator will scan for running {ProductName} instances and upgrade them to 1.11 as well. + +For specific instructions for how to update the OpenShift Elasticsearch Operator, refer to xref:../../logging/cluster-logging-upgrading.adoc#cluster-logging-upgrading_cluster-logging-upgrading[Updating OpenShift Logging]. diff --git a/distributed_tracing/distributed_tracing_install/modules b/distributed_tracing/distributed_tracing_install/modules new file mode 120000 index 000000000000..43aab75b53c9 --- /dev/null +++ b/distributed_tracing/distributed_tracing_install/modules @@ -0,0 +1 @@ +../modules/ \ No newline at end of file diff --git a/distributed_tracing/images b/distributed_tracing/images new file mode 120000 index 000000000000..5e67573196d8 --- /dev/null +++ b/distributed_tracing/images @@ -0,0 +1 @@ +../images \ No newline at end of file diff --git a/distributed_tracing/modules b/distributed_tracing/modules new file mode 120000 index 000000000000..43aab75b53c9 --- /dev/null +++ b/distributed_tracing/modules @@ -0,0 +1 @@ +../modules/ \ No newline at end of file diff --git a/distributed_tracing/rhos-distributed-tracing-platform-release-notes.adoc b/distributed_tracing/rhos-distributed-tracing-platform-release-notes.adoc new file mode 100644 index 000000000000..369661a23121 --- /dev/null +++ b/distributed_tracing/rhos-distributed-tracing-platform-release-notes.adoc @@ -0,0 +1,22 @@ +[id="distributed-tracing-release-notes"] += Distributed tracing release notes +include::modules/distributed-tracing-document-attributes.adoc[] +:context: distributed-tracing-release-notes + +toc::[] + +// The following include statements pull in the module files that comprise the assembly. + +include::modules/distributed-tracing-product-overview.adoc[leveloffset=+1] + +include::modules/making-open-source-more-inclusive.adoc[leveloffset=+1] + +include::modules/support.adoc[leveloffset=+1] + +include::modules/distributed-tracing-rn-new-features.adoc[leveloffset=+1] + +include::modules/distributed-tracing-rn-technology-preview.adoc[leveloffset=+1] + +include::modules/distributed-tracing-rn-known-issues.adoc[leveloffset=+1] + +include::modules/distributed-tracing-rn-fixed-issues.adoc[leveloffset=+1] diff --git a/modules/distributed-tracing-architecture.adoc b/modules/distributed-tracing-architecture.adoc new file mode 100644 index 000000000000..bf6cdf0d5234 --- /dev/null +++ b/modules/distributed-tracing-architecture.adoc @@ -0,0 +1,25 @@ +//// +This CONCEPT module included in the following assemblies: +-service_mesh/v1x/ossm-architecture.adoc +-service_mesh/v2x/ossm-architecture.adoc +-rhbjaeger-architecture.adoc +//// + +[id="distributed-tracing-architecture_{context}"] += {ProductName} architecture + +{ProductName} is made up of several components that work together to collect, store, and display tracing data. + +* *Jaeger Client* (Tracer, Reporter, instrumented application, client libraries)- Jaeger clients are language specific implementations of the OpenTracing API. They can be used to instrument applications for distributed tracing either manually or with a variety of existing open source frameworks, such as Camel (Fuse), Spring Boot (RHOAR), MicroProfile (RHOAR/Thorntail), Wildfly (EAP), and many more, that are already integrated with OpenTracing. + +* *Jaeger Agent* (Server Queue, Processor Workers) - The Jaeger agent is a network daemon that listens for spans sent over User Datagram Protocol (UDP), which it batches and sends to the collector. The agent is meant to be placed on the same host as the instrumented application. This is typically accomplished by having a sidecar in container environments like Kubernetes. + +* *Jaeger Collector* (Queue, Workers) - Similar to the Agent, the Collector is able to receive spans and place them in an internal queue for processing. This allows the collector to return immediately to the client/agent instead of waiting for the span to make its way to the storage. + +* *Storage* (Data Store) - Collectors require a persistent storage backend. Jaeger has a pluggable mechanism for span storage. Note that for this release, the only supported storage is Elasticsearch. + +* *Query* (Query Service) - Query is a service that retrieves traces from storage. + +* *Ingester* (Ingester Service) - Jaeger can use Apache Kafka as a buffer between the collector and the actual backing storage (Elasticsearch). Ingester is a service that reads data from Kafka and writes to another storage backend (Elasticsearch). + +* *Jaeger Console* – Jaeger provides a user interface that lets you visualize your distributed tracing data. On the Search page, you can find traces and explore details of the spans that make up an individual trace. diff --git a/modules/distributed-tracing-config-collector.adoc b/modules/distributed-tracing-config-collector.adoc new file mode 100644 index 000000000000..ac878579f076 --- /dev/null +++ b/modules/distributed-tracing-config-collector.adoc @@ -0,0 +1,66 @@ +//// +This REFERENCE module included in the following assemblies: +-distributed-tracing-deploy.adoc +//// + +[id="distributed-tracing-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. + +.Parameters used by the Operator to define the Jaeger Collector +[options="header"] +[cols="l, a, a"] +|=== +|Parameter |Description |Values +|collector: + replicas: +|Specifies the number of Collector replicas to create. +|Integer, for example, `5` +|=== + + +.Jaeger parameters passed to the Collector +[options="header"] +[cols="l, a, a"] +|=== +|Parameter |Description |Values +|spec: + collector: + options: {} +|Configuration options that define the Jaeger Collector. +| + +|options: + collector: + num-workers: +|The number of workers pulling from the queue. +|Integer, for example, `50` + +|options: + collector: + queue-size: +|The size of the Collector queue. +|Integer, for example, `2000` + +|options: + 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 + +|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, Jaeger will self-provision Kafka. +| + +|options: + log-level: +|Logging level for the collector. +|`trace`, `debug`, `info`, `warning`, `error`, `fatal`, `panic` +|=== diff --git a/modules/distributed-tracing-config-default.adoc b/modules/distributed-tracing-config-default.adoc new file mode 100644 index 000000000000..7a94ab7408a2 --- /dev/null +++ b/modules/distributed-tracing-config-default.adoc @@ -0,0 +1,126 @@ +//// +This REFERENCE module included in the following assemblies: +- distributed-tracing-deploying.adoc +//// + +[id="distributed-tracing-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`. +| +|{product-title} 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 Jaeger 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/distributed-tracing-config-ingester.adoc b/modules/distributed-tracing-config-ingester.adoc new file mode 100644 index 000000000000..c804e753d5cc --- /dev/null +++ b/modules/distributed-tracing-config-ingester.adoc @@ -0,0 +1,76 @@ +//// +This REFERENCE module included in the following assemblies: +-distributed-tracing-deploy.adoc +//// + +[id="distributed-tracing-config-ingester_{context}"] += Jaeger Ingester configuration options + +Ingester is a service that reads from a 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 parameters passed to the Ingester +[options="header"] +[cols="l, a, a"] +|=== +|Parameter |Description |Values +|spec: + ingester: + options: {} +|Configuration options that define the Ingester service. +| + +|options: + deadlockInterval: +|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`. Default value is `0`. + +|options: + 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. +|Label for the consumer. For example, `jaeger-spans`. + +|options: + kafka: + consumer: + brokers: +|Identifies the Kafka configuration used by the Ingester to consume the messages. +|Label for the broker, for example, `my-cluster-kafka-brokers.kafka:9092`. + +|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/distributed-tracing-config-query.adoc b/modules/distributed-tracing-config-query.adoc new file mode 100644 index 000000000000..1556a4a006e4 --- /dev/null +++ b/modules/distributed-tracing-config-query.adoc @@ -0,0 +1,68 @@ +//// +This REFERENCE module included in the following assemblies: +distributed-tracing-deploy.adoc +//// + +[id="distributed-tracing-config-query_{context}"] += Jaeger Query configuration options + +Query is a service that retrieves traces from storage and hosts the user interface to display them. + +.Parameters used by the Operator to define Jaeger Query +[options="header"] +[cols="l, a, a, a"] +|=== +|Parameter |Description |Values |Default value + +|spec: + query: + replicas: +|Specifies the number of Query replicas to create. +|Integer, for example, `2` +| + +|=== + + +.Jaeger parameters passed to Query +[options="header"] +[cols="l, a, a, a"] +|=== +|Parameter |Description |Values |Default value + +|spec: + query: + options: {} +|Configuration options that define the Query service. +| +| + +|options: + log-level: +|Logging level for Query. +|Possible values: `trace`, `debug`, `info`, `warning`, `error`, `fatal`, `panic`. +| + +|options: + 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} +| +|=== + +.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/distributed-tracing-config-sampling.adoc b/modules/distributed-tracing-config-sampling.adoc new file mode 100644 index 000000000000..9706d0cd999d --- /dev/null +++ b/modules/distributed-tracing-config-sampling.adoc @@ -0,0 +1,99 @@ +//// +This REFERENCE module included in the following assemblies: +-rhbjaeger-deploy.adoc +//// + +[id="distributed-tracing-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: + +* *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. + +.Jaeger sampling options +[options="header"] +[cols="l, a, a, a"] +|=== +|Parameter |Description |Values |Default value +|spec: + sampling: + options: {} + default_strategy: + service_strategy: +|Configuration options that define the sampling strategies for tracing. +| +|If you do not provide configuration, the collectors will return the default probabilistic sampling policy with probability 0.001 (0.1%) for all services. + +|default_strategy: + type: +service_strategy: + type: +|Sampling strategy to use. (See descriptions above.) +|Valid values are `probabilistic`, and `ratelimiting`. +|`probabilistic` + +|default_strategy: + param: +service_strategy: + param: +|Parameters for the selected sampling strategy. +|Decimal and integer values (0, .1, 1, 10) +|1 +|=== + +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: + sampling: + options: + default_strategy: + type: probabilistic + param: 0.5 + service_strategies: + - service: alpha + type: probabilistic + param: 0.8 + operation_strategies: + - operation: op1 + type: probabilistic + param: 0.2 + - operation: op2 + type: probabilistic + param: 0.4 + - service: beta + type: ratelimiting + param: 5 +---- + +If there are no user-supplied configurations, Jaeger uses the following settings. + +.default sampling +[source,yaml] +---- +spec: + sampling: + options: + default_strategy: + type: probabilistic + param: 1 +---- diff --git a/modules/distributed-tracing-config-storage.adoc b/modules/distributed-tracing-config-storage.adoc new file mode 100644 index 000000000000..999a9858f7e3 --- /dev/null +++ b/modules/distributed-tracing-config-storage.adoc @@ -0,0 +1,617 @@ +//// +This REFERENCE module included in the following assemblies: +distributed-tracing-deploy.adoc +//// + +[id="distributed-tracing-config-storage_{context}"] += Jaeger storage configuration options + +You configure storage for the Collector, Ingester, and Query services under `spec.storage`. Multiple instances of each of these components can be provisioned as required for performance and resilience purposes. + +.General storage parameters used by the Operator to define Jaeger storage + +[options="header"] +[cols="l, a, a, a"] +|=== +|Parameter |Description |Values |Default value +|spec: + storage: + type: +|Type of storage to use for the deployment. +|`memory` or `elasticsearch`. +Memory storage is only appropriate for development, testing, demonstrations, and proof of concept environments as the data does not persist if the pod is shut down. For production environments Jaeger supports Elasticsearch for persistent storage. +|`memory` + +|storage: + secretname: +|Name of the secret, for example `jaeger-secret`. +| +|N/A + +|storage: + options: {} +|Configuration options that define the storage. +| +| +|=== + +.Elasticsearch index cleaner parameters +[options="header"] +[cols="l, a, a, a"] +|=== +|Parameter |Description |Values |Default value +|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 * * *" +|=== + +[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 Jaeger 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. + +.Restrictions + +* You can have only one Jaeger with self-provisioned Elasticsearch instance per namespace. The Elasticsearch cluster is meant to be dedicated for a single Jaeger instance. +* There can be only one Elasticsearch per namespace. + +[NOTE] +==== +If you already have installed Elasticsearch as part of OpenShift Logging, the Jaeger Operator can use the installed OpenShift Elasticsearch Operator to provision storage. +==== + +The following configuration parameters are for a _self-provisioned_ Elasticsearch instance, that is an instance created by the Jaeger Operator using the OpenShift Elasticsearch Operator. You specify configuration options for self-provisioned Elasticsearch under `spec:storage:elasticsearch` in your configuration file. + +.Elasticsearch resource configuration parameters +[options="header"] +[cols="l, a, a, a"] +|=== +|Parameter |Description |Values |Default value +|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 +|3 + +|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 +|1 + +|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* +|16Gi + +|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 +| + +|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* +| + +|elasticsearch: + redundancyPolicy: +|Data replication policy defines how Elasticsearch shards are replicated across data nodes in the cluster. If not specified, the Jaeger Operator automatically determines the most appropriate replication based on number of nodes. +|`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). +| + +| +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. +|=== + +.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 persistent storage: +[source,yaml] +---- +apiVersion: jaegertracing.io/v1 +kind: Jaeger +metadata: + name: simple-prod +spec: + strategy: production + storage: + type: elasticsearch + elasticsearch: + nodeCount: 1 + storage: # <1> + storageClassName: gp2 + size: 5Gi + resources: + requests: + cpu: 200m + memory: 4Gi + limits: + memory: 4Gi + redundancyPolicy: ZeroRedundancy +---- + +<1> Persistent storage configuration. In this case AWS `gp2` with `5Gi` size. When no value is specified, Jaeger uses `emptyDir`. The OpenShift Elasticsearch Operator provisions `PersistentVolumeClaim` and `PersistentVolume` which are not removed with Jaeger instance. You can mount the same volumes if you create a Jaeger instance with the same name and namespace. + + +[id="distributed-tracing-config-external-es_{context}"] +== Connecting to an existing Elasticsearch instance + +You can use an existing Elasticsearch cluster for storage with Jaeger, that is, an instance that was not auto-provisioned by the Jaeger Operator. You do this by specifying the URL of the existing cluster as the `spec:storage:options:es:server-urls` value in your configuration. + +.Restrictions + +* You cannot share or reuse a {ProductName} logging Elasticsearch instance with Jaeger. The Elasticsearch cluster is meant to be dedicated for a single Jaeger instance. + +[NOTE] +==== +Red Hat does not provide support for your external Elasticsearch instance. You can review the tested integrations matrix on the link:https://access.redhat.com/articles/5381021[Customer Portal]. +==== + +The following configuration parameters are for an already existing Elasticsearch instance, also known as an _external_ Elasticsearch instance. In this case, you specify configuration options for Elasticsearch under `spec:storage:options:es` in your custom resource file. + +.General ES configuration parameters +[options="header"] +[cols="l, a, a, a"] +|=== +|Parameter |Description |Values |Default value +|es: + server-urls: +|URL of the Elasticsearch instance. +|The fully-qualified domain name of the Elasticsearch server. +|`http://elasticsearch..svc:9200` + +|es: + max-doc-count: +|The maximum document count to return from an Elasticsearch query. This will also apply to aggregations. If you set both `es.max-doc-count` and `es.max-num-spans`, Elasticsearch will use the smaller value of the two. +| +|10000 + +|es: + max-num-spans: +|[*Deprecated* - Will be removed in a future release, use `es.max-doc-count` instead.] The maximum number of spans to fetch at a time, per query, in Elasticsearch. If you set both `es.max-num-spans` and `es.max-doc-count`, Elasticsearch will use the smaller value of the two. +| +|10000 + +|es: + max-span-age: +|The maximum lookback for spans in Elasticsearch. +| +|72h0m0s + +|es: + sniffer: +|The sniffer configuration for Elasticsearch. The client uses the sniffing process to find all nodes automatically. Disabled by default. +|`true`/ `false` +|`false` + +|es: + sniffer-tls-enabled: +|Option to enable TLS when sniffing an Elasticsearch Cluster, The client uses the sniffing process to find all nodes automatically. Disabled by default +|`true`/ `false` +|`false` + +|es: + timeout: +|Timeout used for queries. When set to zero there is no timeout. +| +|0s + +|es: + username: +|The username required by Elasticsearch. The basic authentication also loads CA if it is specified. See also `es.password`. +| +| + +|es: + password: +|The password required by Elasticsearch. See also, `es.username`. +| +| + +|es: + version: +|The major Elasticsearch version. If not specified, the value will be auto-detected from Elasticsearch. +| +|0 +|=== + +.ES data replication parameters +[options="header"] +[cols="l, a, a, a"] +|=== +|Parameter |Description |Values |Default value +|es: + num-replicas: +|The number of replicas per index in Elasticsearch. +| +|1 + +|es: + num-shards: +|The number of shards per index in Elasticsearch. +| +|5 +|=== + +.ES index configuration parameters +[options="header"] +[cols="l, a, a, a"] +|=== +|Parameter |Description |Values |Default value +|es: + create-index-templates: +|Automatically create index templates at application startup when set to `true`. When templates are installed manually, set to `false`. +|`true`/ `false` +|`true` + +|es: + index-prefix: +|Optional prefix for Jaeger indices. For example, setting this to "production" creates indices named "production-jaeger-*". +| +| +|=== + +.ES bulk processor configuration parameters +[options="header"] +[cols="l, a, a, a"] +|=== +|Parameter |Description |Values |Default value +|es: + bulk: + actions: +|The number of requests that can be added to the queue before the bulk processor decides to commit updates to disk. +| +|1000 + +//What is the default here? The original text said "Set to zero to disable. By default, this is disabled." +|es: + bulk: + flush-interval: +|A `time.Duration` after which bulk requests are committed, regardless of other thresholds. To disable the bulk processor flush interval, set this to zero. +| +|200ms + +|es: + bulk: + size: +|The number of bytes that the bulk requests can take up before the bulk processor decides to commit updates to disk. +| +|5000000 + +|es: + bulk: + workers: +|The number of workers that are able to receive and commit bulk requests to Elasticsearch. +| +|1 +|=== + +.ES TLS configuration parameters +[options="header"] +[cols="l, a, a, a"] +|=== +|Parameter |Description |Values |Default value +|es: + tls: + ca: +|Path to a TLS Certification Authority (CA) file used to verify the remote server(s). +| +|Will use the system truststore by default. + +|es: + tls: + cert: +|Path to a TLS Certificate file, used to identify this process to the remote server(s). +| +| + +|es: + tls: + enabled: +|Enable transport layer security (TLS) when talking to the remote server(s). Disabled by default. +|`true`/ `false` +|`false` + +|es: + tls: + key: +|Path to a TLS Private Key file, used to identify this process to the remote server(s). +| +| + +|es: + tls: + server-name: +|Override the expected TLS server name in the certificate of the remote server(s). +| +| +//Clarification of "if specified" for `token-file` and `username`, does that mean if this is set? Or that it only loads the CA if one is specified (that is, if es.tls.ca has a value?) +|es: + token-file: +|Path to a file containing the bearer token. This flag also loads the Certification Authority (CA) file if it is specified. +| +| +|=== + +.ES archive configuration parameters +[options="header"] +[cols="l, a, a, a"] +|=== +|Parameter |Description |Values |Default value +|es-archive: + bulk: + actions: +|The number of requests that can be added to the queue before the bulk processor decides to commit updates to disk. +| +|0 + +//What is the default here? The original text said "Set to zero to disable. By default, this is disabled." +|es-archive: + bulk: + flush-interval: +|A `time.Duration` after which bulk requests are committed, regardless of other thresholds. To disable the bulk processor flush interval, set this to zero. +| +|0s + +|es-archive: + bulk: + size: +|The number of bytes that the bulk requests can take up before the bulk processor decides to commit updates to disk. +| +|0 + +|es-archive: + bulk: + workers: +|The number of workers that are able to receive and commit bulk requests to Elasticsearch. +| +|0 + +|es-archive: + create-index-templates: +|Automatically create index templates at application startup when set to `true`. When templates are installed manually, set to `false`. +|`true`/ `false` +|`false` + +|es-archive: + enabled: +|Enable extra storage. +|`true`/ `false` +|`false` + +|es-archive: + index-prefix: +|Optional prefix for Jaeger indices. For example, setting this to "production" creates indices named "production-jaeger-*". +| +| + +|es-archive: + max-doc-count: +|The maximum document count to return from an Elasticsearch query. This will also apply to aggregations. +| +|0 + +|es-archive: + max-num-spans: +|[*Deprecated* - Will be removed in a future release, use `es-archive.max-doc-count` instead.] The maximum number of spans to fetch at a time, per query, in Elasticsearch. +| +|0 + +|es-archive: + max-span-age: +|The maximum lookback for spans in Elasticsearch. +| +|0s + +|es-archive: + num-replicas: +|The number of replicas per index in Elasticsearch. +| +|0 + +|es-archive: + num-shards: +|The number of shards per index in Elasticsearch. +| +|0 + +|es-archive: + password: +|The password required by Elasticsearch. See also, `es.username`. +| +| + +|es-archive: + server-urls: +|The comma-separated list of Elasticsearch servers. Must be specified as fully qualified URLs, for example, `\http://localhost:9200`. +| +| + +|es-archive: + sniffer: +|The sniffer configuration for Elasticsearch. The client uses the sniffing process to find all nodes automatically. Disabled by default. +|`true`/ `false` +|`false` + +|es-archive: + sniffer-tls-enabled: +|Option to enable TLS when sniffing an Elasticsearch Cluster, The client uses the sniffing process to find all nodes automatically. Disabled by default. +|`true`/ `false` +|`false` + +|es-archive: + timeout: +|Timeout used for queries. When set to zero there is no timeout. +| +|0s + +|es-archive: + tls: + ca: +|Path to a TLS Certification Authority (CA) file used to verify the remote server(s). +| +|Will use the system truststore by default. + +|es-archive: + tls: + cert: +|Path to a TLS Certificate file, used to identify this process to the remote server(s). +| +| + +|es-archive: + tls: + enabled: +|Enable transport layer security (TLS) when talking to the remote server(s). Disabled by default. +|`true`/ `false` +|`false` + +|es-archive: + tls: + key: +|Path to a TLS Private Key file, used to identify this process to the remote server(s). +| +| + +|es-archive: + tls: + server-name: +|Override the expected TLS server name in the certificate of the remote server(s). +| +| + +//Clarification of "if specified" for next two rows, does that mean if this is set? Or that it only loads the CA if one is specified (that is, if es-archive.tls.ca has a value?) +|es-archive: + token-file: +|Path to a file containing the bearer token. This flag also loads the Certification Authority (CA) file if it is specified. +| +| + +|es-archive: + username: +|The username required by Elasticsearch. The basic authentication also loads CA if it is specified. See also `es-archive.password`. +| +| + +|es-archive: + version: +|The major Elasticsearch version. If not specified, the value will be auto-detected from Elasticsearch. +| +|0 +|=== + + +.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 +---- + +The following example shows a Jaeger CR using an external Elasticsearch cluster with TLS CA certificate mounted from a volume and user/password stored in a secret. + +.External Elasticsearch example: +[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 # <1> + index-prefix: my-prefix + tls: # <2> + ca: /es/certificates/ca.crt + secretName: jaeger-secret # <3> + volumeMounts: # <4> + - name: certificates + mountPath: /es/certificates/ + readOnly: true + volumes: + - name: certificates + secret: + secretName: quickstart-es-http-certs-public +---- +<1> URL to Elasticsearch service running in default namespace. +<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 jaeger-secret --from-literal=ES_PASSWORD=changeme --from-literal=ES_USERNAME=elastic +<4> Volume mounts and volumes which are mounted into all storage components. diff --git a/modules/distributed-tracing-deploy-default.adoc b/modules/distributed-tracing-deploy-default.adoc new file mode 100644 index 000000000000..8d9b5b309445 --- /dev/null +++ b/modules/distributed-tracing-deploy-default.adoc @@ -0,0 +1,115 @@ +//// +This PROCEDURE module included in the following assemblies: +- distributed-tracing-deploying.adoc +//// + +[id="distributed-tracing-deploy-default_{context}"] += Deploying the default {ProductName} strategy from the web console + +The custom resource definition (CRD) defines the configuration used when you deploy an instance of {ProductName}. 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 {ProductName} operator must be installed. +* Review the instructions for how to customize the Jaeger installation. +* An account with the `cluster-admin` role. + +[NOTE] +==== +Jaeger streaming is currently unsupported on IBM Z. +==== + +.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="distributed-tracing-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 OpenShift CLI (`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. ++ +[source,terminal] +---- +$ oc login https://{HOSTNAME}:8443 +---- + +. Create a new project named `jaeger-system`. ++ +[source,terminal] +---- +$ 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: ++ +[source,terminal] +---- +$ oc create -n jaeger-system -f jaeger.yaml +---- + +. Run the following command to watch the progress of the pods during the installation process: ++ +[source,terminal] +---- +$ oc get pods -n jaeger-system -w +---- ++ +Once the installation process has completed, you should see output similar to the following: ++ +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +jaeger-all-in-one-inmemory-cdff7897b-qhfdx 2/2 Running 0 24s +---- diff --git a/modules/distributed-tracing-deploy-production-es.adoc b/modules/distributed-tracing-deploy-production-es.adoc new file mode 100644 index 000000000000..885d7c2c4b85 --- /dev/null +++ b/modules/distributed-tracing-deploy-production-es.adoc @@ -0,0 +1,129 @@ +//// +This PROCEDURE module included in the following assemblies: +- distributed-tracing-deploying.adoc +//// + +[id="distributed-tracing-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 OpenShift 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="distributed-tracing-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 OpenShift CLI (`oc`). +* An account with the `cluster-admin` role. + +.Procedure + +. Log in to the {product-title} CLI as a user with the `cluster-admin` role. ++ +[source,terminal] +---- +$ oc login https://{HOSTNAME}:8443 +---- + +. Create a new project named `jaeger-system`. ++ +[source,terminal] +---- +$ 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: ++ +[source,terminal] +---- +$ oc create -n jaeger-system -f jaeger-production.yaml +---- ++ +. Run the following command to watch the progress of the pods during the installation process: ++ +[source,terminal] +---- +$ oc get pods -n jaeger-system -w +---- ++ +Once the installation process has completed, you should see output similar to the following: ++ +[source,terminal] +---- +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/distributed-tracing-deploy-streaming.adoc b/modules/distributed-tracing-deploy-streaming.adoc new file mode 100644 index 000000000000..70469d31111c --- /dev/null +++ b/modules/distributed-tracing-deploy-streaming.adoc @@ -0,0 +1,145 @@ +//// +This PROCEDURE module included in the following assemblies: +- distributed-tracing-deploying.adoc +//// + +[id="distributed-tracing-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). + +[NOTE] +==== +The streaming strategy requires an additional Red Hat subscription for AMQ Streams. If you do not have an AMQ Streams subscription, contact your sales representative for more information. +==== + +.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. + +[NOTE] +==== +Jaeger streaming is currently unsupported on IBM Z. +==== + +.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="distributed-tracing-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 OpenShift CLI (`oc`). +* An account with the `cluster-admin` role. + +Procedure + +. Log in to the {product-title} CLI as a user with the `cluster-admin` role. ++ +[source,terminal] +---- +$ oc login https://{HOSTNAME}:8443 +---- + +. Create a new project named `jaeger-system`. ++ +[source,terminal] +---- +$ 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: ++ +[source,terminal] +---- +$ oc create -n jaeger-system -f jaeger-streaming.yaml +---- ++ +. Run the following command to watch the progress of the pods during the installation process: ++ +[source,terminal] +---- +$ oc get pods -n jaeger-system -w +---- ++ +Once the installation process has completed, you should see output similar to the following: ++ +[source,terminal] +---- +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/distributed-tracing-deployment-best-practices.adoc b/modules/distributed-tracing-deployment-best-practices.adoc new file mode 100644 index 000000000000..bd72d7272065 --- /dev/null +++ b/modules/distributed-tracing-deployment-best-practices.adoc @@ -0,0 +1,17 @@ +//// +This module included in the following assemblies: +* /jaeger/jaeger_install/rhbjaeger-deploying.adoc +//// + +[id="distributed-tracing-deployment-best-practices_{context}"] += Deployment best practices +:pantheon-module-type: CONCEPT + + +* Jaeger instance names must be unique. If you want to have multiple Jaeger instances and are using sidecar injected Jaeger agents, then the Jaeger instances should have unique names, and the injection annotation should explicitly specify the Jaeger instance name the tracing data should be reported to. + +* If you have a multitenant implementation and tenants are separated by namespaces, deploy a Jaeger instance to each tenant namespace. + +** Jaeger agent as a daemonset is not supported for multitenant installations or OpenShift Dedicated. Jaeger agent as a sidecar is the only supported configuration for these use cases. + +* If you are installing Jaeger as part of Red Hat OpenShift Service Mesh, Jaeger resources must be installed in the same namespace as the `ServiceMeshControlPlane` resource. diff --git a/modules/distributed-tracing-document-attributes.adoc b/modules/distributed-tracing-document-attributes.adoc new file mode 100644 index 000000000000..bdb73d9d95f8 --- /dev/null +++ b/modules/distributed-tracing-document-attributes.adoc @@ -0,0 +1,39 @@ +// Standard document attributes to be used in the distributed tracing documentation +// +// The following are shared by all RH Build of distributed tracing documents: +:toc: +:toclevels: 4 +:toc-title: +:experimental: +// +// Product content attributes, that is, substitution variables in the files. +// +:product-title: OpenShift Container Platform +:ProductName: OpenShift distributed tracing platform +:ProductShortName: distributed tracing platform +:ProductRelease: +:ProductVersion: 2.0 +:product-build: +:DownloadURL: registry.redhat.io +:cloud-redhat-com: Red Hat OpenShift Cluster Manager +:kebab: image:kebab.png[title="Options menu"] +// +// Documentation publishing attributes used in the master-docinfo.xml file +// Note that the DocInfoProductName generates the URL for the product page. +// Changing the value changes the generated URL. +// + +:DocInfoProductName: Red Hat OpenShift distributed tracing platform +:DocInfoProductName: OpenShift distributed tracing platform +:DocInfoProductNumber: 2.0 +// +// 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 +// +:RN_BookName: Red Hat OpenShift Distributed Tracing Release Notes +:Install_BookName: Installing Red Hat OpenShift distributed tracing platform +:Using_BookName: Using Red Hat Red Hat OpenShift distributed tracing platform diff --git a/modules/distributed-tracing-features.adoc b/modules/distributed-tracing-features.adoc new file mode 100644 index 000000000000..bdf6317c9b01 --- /dev/null +++ b/modules/distributed-tracing-features.adoc @@ -0,0 +1,18 @@ +//// +This CONCEPT module included in the following assemblies: +-service_mesh/v2x/ossm-architecture.adoc ??? +-distributed-tracing-architecture.adoc +//// + +[id="distributed-tracing-features_{context}"] += {ProductName} features + +{ProductName} provides the following capabilities: + +* Integration with Kiali – When properly configured, you can view {ProductName} data from the Kiali console. + +* High scalability – The {ProductName} backend is designed to have no single points of failure and to scale with the business needs. + +* Distributed Context Propagation – Lets you connect data from different components together to create a complete end-to-end trace. + +* Backwards compatibility with Zipkin – {ProductName} 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/distributed-tracing-install-elasticsearch.adoc b/modules/distributed-tracing-install-elasticsearch.adoc new file mode 100644 index 000000000000..daed8f4e090f --- /dev/null +++ b/modules/distributed-tracing-install-elasticsearch.adoc @@ -0,0 +1,57 @@ +// Module included in the following assemblies: +// +// - distributed-tracing-installation.adoc + + +[id="distributed-tracing-operator-install-elasticsearch_{context}"] += Installing the OpenShift 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 and configure a persistent storage option, in this case, Elasticsearch. + +.Prerequisites +* Access to the {product-title} web console. +* An account with the `cluster-admin` role. If you use {product-dedicated}, you must have an account with the `dedicated-admin` role. + +[WARNING] +==== +Do not install Community versions of the Operators. Community Operators are not supported. +==== + +[NOTE] +==== +If you have already installed the OpenShift Elasticsearch Operator as part of OpenShift Logging, you do not need to install the OpenShift Elasticsearch Operator again. The Jaeger Operator will create the Elasticsearch instance using the installed OpenShift Elasticsearch Operator. +==== + +.Procedure + +. Log in to the {product-title} web console as a user with the `cluster-admin` role. If you use {product-dedicated}, you must have an account with the `dedicated-admin` role. + +. Navigate to *Operators* -> *OperatorHub*. + +. Type *Elasticsearch* into the filter box to locate the OpenShift Elasticsearch Operator. + +. Click the *OpenShift Elasticsearch Operator* provided by Red Hat to display information about the Operator. + +. Click *Install*. + +. On the *Install Operator* page, under *Installation Mode* select *All namespaces on the cluster (default)*. This makes the Operator available to all projects in the cluster. + +. Under *Installed Namespaces* select *openshift-operators-redhat* from the menu. ++ +[NOTE] +==== +The Elasticsearch installation requires the *openshift-operators-redhat* namespace for the OpenShift Elasticsearch Operator. The other {ProductName} operators are installed in the `openshift-operators` namespace. +==== ++ +. Select *stable-5.x* as the *Update Channel*. + +. Select the *Automatic* Approval Strategy. ++ +[NOTE] +==== +The Manual approval strategy requires a user with appropriate credentials to approve the Operator install and subscription process. +==== + +. Click *Install*. + +. On the *Installed Operators* page, select the `openshift-operators-redhat` project. Wait until you see that the OpenShift Elasticsearch Operator shows a status of "InstallSucceeded" before continuing. diff --git a/modules/distributed-tracing-install-overview.adoc b/modules/distributed-tracing-install-overview.adoc new file mode 100644 index 000000000000..e3c68657b414 --- /dev/null +++ b/modules/distributed-tracing-install-overview.adoc @@ -0,0 +1,19 @@ +//// +This CONCEPT module included in the following assemblies: +- distributed-tracing-installation.adoc +//// + +[id="distributed-tracing-install-overview_{context}"] += Red Hat OpenShift distributed tracing platform installation overview + +The steps for installing {ProductName} are as follows: + +* Review the documentation and determine your deployment strategy. + +* If your deployment strategy requires persistent storage, install the OpenShift Elasticsearch Operator via the OperatorHub. + +* Install the distributed tracing platform Operator via the OperatorHub. + +* Modify the distributed tracing platform YAML file to support your deployment strategy. + +* Deploy one or more instances of distributed tracing platform to your {product-title} environment. diff --git a/modules/distributed-tracing-install.adoc b/modules/distributed-tracing-install.adoc new file mode 100644 index 000000000000..cc9a96b3e38b --- /dev/null +++ b/modules/distributed-tracing-install.adoc @@ -0,0 +1,49 @@ +//// +This PROCEDURE module included in the following assemblies: +- distributed-tracing-installation.adoc +//// + +[id="distributed-tracing-operator-install_{context}"] += Installing the Red Hat {ProductName} operator + +To install distributing tracing platform you use the link:https://operatorhub.io/[OperatorHub] to install the distributing tracing platform Operator. + +By default the Operator is installed in the `openshift-operators` project. + +.Prerequisites +* Access to the {product-title} web console. +* An account with the `cluster-admin` role. If you use {product-dedicated}, you must have an account with the `dedicated-admin` role. +* If you require persistent storage, you must also install the OpenShift Elasticsearch Operator before installing the distributing tracing platform Operator. + +[WARNING] +==== +Do not install Community versions of the Operators. Community Operators are not supported. +==== + +.Procedure + +. Log in to the {product-title} web console as a user with the `cluster-admin` role. If you use {product-dedicated}, you must have an account with the `dedicated-admin` role. + +. Navigate to *Operators* -> *OperatorHub*. + +. Type *distributing tracing platform * into the filter to locate the distributing tracing platform Operator. + +. Click the *distributing tracing platform Operator* provided by Red Hat to display information about the Operator. + +. Click *Install*. + +. On the *Install Operator* page, select the *stable* Update Channel. This will automatically update {ProductName} as new versions are released. If you select a maintenance channel, for example, *Stable*, you will receive bug fixes and security patches for the length of the support cycle for that version. + +. Select *All namespaces on the cluster (default)*. This installs the Operator in the default `openshift-operators` project and makes the Operator available to all projects in the cluster. + +* Select an Approval Strategy. You can select *Automatic* or *Manual* updates. If you choose Automatic updates for an installed Operator, when a new version of that Operator is available, the Operator Lifecycle Manager (OLM) automatically upgrades the running instance of your Operator without human intervention. If you select Manual updates, when a newer version of an Operator is available, the OLM creates an update request. As a cluster administrator, you must then manually approve that update request to have the Operator updated to the new version. ++ +[NOTE] +==== +The Manual approval strategy requires a user with appropriate credentials to approve the Operator install and subscription process. +==== ++ + +. Click *Install*. + +. On the *Subscription Overview* page, select the `openshift-operators` project. Wait until you see that the {ProductName} operator shows a status of "InstallSucceeded" before continuing. diff --git a/modules/distributed-tracing-product-overview.adoc b/modules/distributed-tracing-product-overview.adoc new file mode 100644 index 000000000000..3bd2ee5e22da --- /dev/null +++ b/modules/distributed-tracing-product-overview.adoc @@ -0,0 +1,21 @@ +//// +This CONCEPT module included in the following assemblies: +-service_mesh/v2x/ossm-architecture.adoc ?? +-distributed-tracing-architecture.adoc +//// + +[id="distributed-tracing-product-overview_{context}"] += OpenShift distributed tracing platform overview + +As a service owner, you can use distributed tracing to instrument your services to gather insights into your service architecture. +You can use the distributed tracing platform for monitoring, network profiling, and troubleshooting the interaction between components in modern, cloud-native, microservices-based applications. + +Using distributed tracing lets you perform the following functions: + +* Monitor distributed transactions + +* Optimize performance and latency + +* Perform root cause analysis + +Distributed tracing is based on the vendor-neutral link:https://opentracing.io/[OpenTracing] APIs and instrumentation. diff --git a/modules/distributed-tracing-removing-instance-cli.adoc b/modules/distributed-tracing-removing-instance-cli.adoc new file mode 100644 index 000000000000..4f86f73e8db8 --- /dev/null +++ b/modules/distributed-tracing-removing-instance-cli.adoc @@ -0,0 +1,84 @@ +//// +This PROCEDURE module included in the following assemblies: +- distributed-tracing-installation.adoc +//// + +[id="distributed-tracing-removing-cli_{context}"] += Removing a Jaeger instance from the CLI + + +. Log in to the {product-title} CLI. ++ +[source,terminal] +---- +$ oc login +---- ++ +. To display the Jaeger instances run the command: ++ +[source,terminal] +---- +$ oc get deployments -n +---- ++ +The names of operators have the suffix `-operator`. The following example shows two Jaeger Operators and four Jaeger instances: ++ +[source,terminal] +---- +$ oc get deployments -n jaeger-system +---- ++ +You should see output similar to the following: ++ +[source,terminal] +---- +NAME READY UP-TO-DATE AVAILABLE AGE +elasticsearch-operator 1/1 1 1 93m +jaeger-operator 1/1 1 1 49m +jaeger-test 1/1 1 1 7m23s +jaeger-test2 1/1 1 1 6m48s +tracing1 1/1 1 1 7m8s +tracing2 1/1 1 1 35m +---- ++ +. To remove an instance of Jaeger, run the command: ++ +[source,terminal] +---- +$ oc delete jaeger -n +---- ++ +For example, ++ +[source,terminal] +---- +$ oc delete jaeger tracing2 -n jaeger-system +---- ++ + +. To verify the deletion, run `oc get deployment` again: ++ +[source,terminal] +---- +$ oc get deployments -n +---- + ++ +For example, ++ +[source,terminal] +---- +$ oc get deployments -n jaeger-system +---- ++ +Should generate output similar to the following: ++ +[source,terminal] +---- +NAME READY UP-TO-DATE AVAILABLE AGE +elasticsearch-operator 1/1 1 1 94m +jaeger-operator 1/1 1 1 50m +jaeger-test 1/1 1 1 8m14s +jaeger-test2 1/1 1 1 7m39s +tracing1 1/1 1 1 7m59s +---- diff --git a/modules/distributed-tracing-removing-instance.adoc b/modules/distributed-tracing-removing-instance.adoc new file mode 100644 index 000000000000..eb1430606864 --- /dev/null +++ b/modules/distributed-tracing-removing-instance.adoc @@ -0,0 +1,28 @@ +//// +This PROCEDURE module included in the following assemblies: +- distributed-tracing-removing.adoc +//// + +[id="distributed-tracing-removing_{context}"] += Removing a Jaeger instance using the web console + +[NOTE] +==== +When deleting an instance that uses the in-memory storage, all data will be permanently lost. Data stored in a persistent storage (such as Elasticsearch) will not be deleted when a Jaeger instance is removed. +==== + +.Procedure + +. Log in to the {product-title} web console. + +. Navigate to *Operators* -> *Installed Operators*. + +. Select the name of the project where the Operators are installed from the Project menu, for example, `jaeger-system`. + +. Click the Jaeger Operator. + +. Click the *Jaeger* tab. + +. Click the Options menu {kebab} next to the instance you want to delete and select *Delete Jaeger*. + +. In the confirmation message, click *Delete*. diff --git a/modules/distributed-tracing-rn-fixed-issues.adoc b/modules/distributed-tracing-rn-fixed-issues.adoc new file mode 100644 index 000000000000..9e320325c7a7 --- /dev/null +++ b/modules/distributed-tracing-rn-fixed-issues.adoc @@ -0,0 +1,29 @@ +//// +Module included in the following assemblies: +* distributed-tracing-release-notes.adoc +* service_mesh/v2x/servicemesh-release-notes.adoc +//// + +[id="distributed-tracing-rn-fixed-issues_{context}"] += Distributed tracing platform fixed issues +//// +Provide the following info for each issue if possible: +Consequence - What user action or situation would make this problem appear (If you have the foo option enabled and did x)? What did the customer experience as a result of the issue? What was the symptom? +Cause - Why did this happen? +Fix - What did we change to fix the problem? +Result - How has the behavior changed as a result? Try to avoid “It is fixed” or “The issue is resolved” or “The error no longer presents”. +//// + +* link:https://issues.redhat.com/browse/TRACING-2009[TRACING-2009] The Jaeger Operator has been updated to include support for the Strimzi Kafka Operator 0.23.0. + +* link:https://issues.redhat.com/browse/TRACING-1907[TRACING-1907] The Jaeger agent sidecar injection was failing due to missing config maps in the application namespace. The config maps were getting automatically deleted due to an incorrect `OwnerReference` field setting and as a result, the application pods were not moving past the "ContainerCreating" stage. The incorrect settings have been removed. + +* link:https://issues.redhat.com/browse/TRACING-1725[TRACING-1725] Follow-up to TRACING-1631. Additional fix to ensure that Elasticsearch certificates are properly reconciled when there are multiple Jaeger production instances, using same name but within different namespaces. See also link:https://bugzilla.redhat.com/show_bug.cgi?id=1918920[BZ-1918920]. + +* link:https://issues.jboss.org/browse/TRACING-1631[TRACING-1631] Multiple Jaeger production instances, using same name but within different namespaces, causing Elasticsearch certificate issue. When multiple service meshes were installed, all of the Jaeger Elasticsearch instances had the same Elasticsearch secret instead of individual secrets, which prevented the OpenShift Elasticsearch Operator from communicating with all of the Elasticsearch clusters. + +* link:https://issues.redhat.com/browse/TRACING-1300[TRACING-1300] Failed connection between Agent and Collector when using Istio sidecar. An update of the Jaeger Operator enabled TLS communication by default between a Jaeger sidecar agent and the Jaeger Collector. + +* link:https://issues.redhat.com/browse/TRACING-1208[TRACING-1208] Authentication "500 Internal Error" when accessing Jaeger UI. When trying to authenticate to the UI using OAuth, I get a 500 error because oauth-proxy sidecar doesn't trust the custom CA bundle defined at installation time with the `additionalTrustBundle`. + +* link:https://issues.redhat.com/browse/TRACING-1166[TRACING-1166] It is not currently possible to use the Jaeger streaming strategy within a disconnected environment. When a Kafka cluster is being provisioned, it results in a error: `Failed to pull image registry.redhat.io/amq7/amq-streams-kafka-24-rhel7@sha256:f9ceca004f1b7dccb3b82d9a8027961f9fe4104e0ed69752c0bdd8078b4a1076`. diff --git a/modules/distributed-tracing-rn-known-issues.adoc b/modules/distributed-tracing-rn-known-issues.adoc new file mode 100644 index 000000000000..181a98533cf2 --- /dev/null +++ b/modules/distributed-tracing-rn-known-issues.adoc @@ -0,0 +1,34 @@ +//// +Module included in the following assemblies: +* service_mesh/v2x/servicemesh-release-notes.adoc +* distributed-tracing--release-notes.adoc +//// + +[id="distributed-tracing-rn-known-issues_{context}"] += Distributed tracing platform known issues + +//// +Consequence - What user action or situation would make this problem appear (Selecting the Foo option with the Bar version 1.3 plugin enabled results in an error message)? What did the customer experience as a result of the issue? What was the symptom? +Cause (if it has been identified) - Why did this happen? +Workaround (If there is one)- What can you do to avoid or negate the effects of this issue in the meantime? Sometimes if there is no workaround it is worthwhile telling readers to contact support for advice. Never promise future fixes. +Result - If the workaround does not completely address the problem. +//// + +These limitations exist in Jaeger: + +* Apache Spark is not supported. + +* Jaeger streaming via AMQ/Kafka is unsupported on IBM Z and IBM Power Systems. + +These are the known issues in Jaeger: + +* link:https://issues.redhat.com/browse/TRACING-2057[TRACING-2057] The Kafka API has been updated to `v1beta2` to support the Strimzi Kafka Operator 0.23.0. However, this API version is not supported by AMQ Streams 1.6.3. If you have the following environment, your Jaeger services will not be upgraded, and you cannot create new Jaeger services or modify existing Jaeger services: + +** Jaeger Operator channel: *1.17.x stable* or *1.20.x stable* +** AMQ Streams Operator channel: *amq-streams-1.6.x* ++ +To resolve this issue, switch the subscription channel for your AMQ Streams Operator to either *amq-streams-1.7.x* or *stable*. + +* link:https://bugzilla.redhat.com/show_bug.cgi?id=1918920[BZ-1918920] The Elasticsearch pods does not get restarted automatically after an update. As a workaround, restart the pods manually. + +* link:https://issues.redhat.com/browse/TRACING-809[TRACING-809] Jaeger Ingester is incompatible with Kafka 2.3. When there are two or more instances of the Jaeger Ingester and enough traffic it will continuously generate rebalancing messages in the logs. This is due to a regression in Kafka 2.3 that was fixed in Kafka 2.3.1. For more information, see https://github.com/jaegertracing/jaeger/issues/1819[Jaegertracing-1819]. diff --git a/modules/distributed-tracing-rn-new-features.adoc b/modules/distributed-tracing-rn-new-features.adoc new file mode 100644 index 000000000000..fc2799f43221 --- /dev/null +++ b/modules/distributed-tracing-rn-new-features.adoc @@ -0,0 +1,37 @@ +//// +Module included in the following assemblies: +- distributed-tracing-release-notes.adoc +//// +//// +Feature – Describe the new functionality available to the customer. For enhancements, try to describe as specifically as possible where the customer will see changes. +Reason – If known, include why has the enhancement been implemented (use case, performance, technology, etc.). For example, showcases integration of X with Y, demonstrates Z API feature, includes latest framework bug fixes. +Result – If changed, describe the current user experience. +//// + +[id="distributed-tracing-rn-new-features_{context}"] +== New features and enhancements {ProductName} + +This release of {ProductName} includes the following new features: + +* This release introduces Red Hat {ProductName} based on Jaeger 1.28. + +* Going forward, Red Hat OpenShift distributed tracing will only support the `stable` operator channel. Channels for individual releases are no longer be supported. + +* There is a new distributed tracing icon that appears in the OpenShift OperatorHub. + +* This release also addresses Common Vulnerabilities and Exposures (CVEs) and bug fixes. + +== Component versions supported in {ProductName} version {ProductVersion} + +|=== +|Component |Version + +|Jaeger +|1.26 + +|OpenTelemetry +|0.33 + +|Kafka +|x.x +|=== diff --git a/modules/distributed-tracing-rn-technology-preview.adoc b/modules/distributed-tracing-rn-technology-preview.adoc new file mode 100644 index 000000000000..7a2a71d503a1 --- /dev/null +++ b/modules/distributed-tracing-rn-technology-preview.adoc @@ -0,0 +1,27 @@ +//// +Module included in the following assemblies: +- rhbjaeger-release-notes.adoc +//// + +[id="distributed-tracing-rn-tech-preview_{context}"] += Technology Preview +//// +Provide the following info for each issue if possible: +Description - Describe the new functionality available to the customer. For enhancements, try to describe as specifically as possible where the customer will see changes. Avoid the word “supports” as in [product] now supports [feature] to avoid customer confusion with full support. Say, for example, “available as a Technology Preview.” +Package - A brief description of what the customer has to install or enable to use the Technology Preview feature. (e.g., available in quickstart.zip on customer portal, JDF website, container on registry, enable option, etc.) +//// + +[IMPORTANT] +==== +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/. +==== + +== {ProductName} 2.0.0 Technology Preview 1 -- Retain only for 4.6-4.8 +When you install the Jaeger Operator you can select a Technology Preview version of Jaeger. This gives you access to clients and infrastructure for exporting tracing data to Jaeger based on the link:https://opentelemetry.io/[OpenTelemetry framework]. Note that this version is not supported for production environments. + +The OpenTelemetry collector allows developers to instrument their code with vendor agnostic APIs, avoiding vendor lock-in and opening the door to a growing ecosystem of observability tooling. + +== Red Hat OpenShift distributed tracing data collection + +Red Hat OpenShift distributed tracing data collection, based on OpenTelemetry 0.33, is technology preview. This includes operator and collector capabilities. diff --git a/modules/distributed-tracing-sidecar-automatic.adoc b/modules/distributed-tracing-sidecar-automatic.adoc new file mode 100644 index 000000000000..1e6fb5d2db0b --- /dev/null +++ b/modules/distributed-tracing-sidecar-automatic.adoc @@ -0,0 +1,38 @@ +//// +This PROCEDURE module included in the following assemblies: +- distributed-tracing-deploying.adoc +//// + +[id="distributed-tracing-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/distributed-tracing-sidecar-manual.adoc b/modules/distributed-tracing-sidecar-manual.adoc new file mode 100644 index 000000000000..07171002ddd6 --- /dev/null +++ b/modules/distributed-tracing-sidecar-manual.adoc @@ -0,0 +1,58 @@ +//// +This PROCEDURE module included in the following assemblies: +- distributed-tracing-deploying.adoc +//// + +[id="distributed-tracing-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/modules/distributed-tracing-upgrading-es.adoc b/modules/distributed-tracing-upgrading-es.adoc new file mode 100644 index 000000000000..f615ecfe62ca --- /dev/null +++ b/modules/distributed-tracing-upgrading-es.adoc @@ -0,0 +1,88 @@ +//// +This PROCEDURE module included in the following assemblies: +- distributed_tracing_install/distributed-tracing-updating +//// + +[id="upgrading_esearch5_esearch6_{context}"] += Upgrading from Elasticsearch 5 to Elasticsearch 6 + +When updating from Elasticsearch 5 to Elasticsearch 6, you must delete your Jaeger instance, then recreate the Jaeger instance because of an issue with certificates. Re-creating the Jaeger instance triggers creating a new set of certificates. If you are using persistent storage the same volumes can be mounted for the new Jaeger instance as long as the Jaeger name and namespace for the new Jaeger instance are the same as the deleted Jaeger instance. + +.Procedure if Jaeger is installed as part of Red Hat Service Mesh + +. Determine the name of your Jaeger custom resource file. In this example, `istio-system` is the control plane namespace. ++ +[source,terminal] +---- +$ oc get jaeger -n +---- ++ +You should see something like the following: ++ +[source,terminal] +---- +NAME AGE +jaeger 3d21h +---- ++ +. Copy the generated custom resource file into a temporary directory: ++ +[source,terminal] +---- +$ oc get jaeger jaeger -oyaml -n > /tmp/jaeger-cr.yaml +---- ++ +. Delete the Jaeger instance: ++ +[source,terminal] +---- +$ oc delete jaeger jaeger -n +---- ++ +. Recreate the Jaeger instance from your copy of the custom resource file: ++ +[source,terminal] +---- +$ oc create -f /tmp/jaeger-cr.yaml -n +---- ++ +. Delete the copy of the generated custom resource file: ++ +[source,terminal] +---- +$ rm /tmp/jaeger-cr.yaml +---- + + +.Procedure if Jaeger not installed as part of Red Hat Service Mesh + +Before you begin, create a copy of your Jaeger custom resource file. + +. Delete the Jaeger instance by deleting the custom resource file: ++ +[source,terminal] +---- +$ oc delete -f +---- ++ +For example: ++ +[source,terminal] +---- +$ oc delete -f jaeger-prod-elasticsearch.yaml +---- ++ +. Recreate your Jaeger instance from the backup copy of your custom resource file: ++ +[source,terminal] +---- +$ oc create -f +---- ++ +. Validate that your pods have restarted: ++ +[source,terminal] +---- +$ oc get pods -n -w +---- ++ diff --git a/modules/distributed-tracing-upgrading-esearch.adoc b/modules/distributed-tracing-upgrading-esearch.adoc new file mode 100644 index 000000000000..a085bf21bbff --- /dev/null +++ b/modules/distributed-tracing-upgrading-esearch.adoc @@ -0,0 +1,88 @@ +//// +This PROCEDURE module included in the following assemblies: +- distributed_tracing_install/distributed-tracing-updating +//// + +[id="upgrading_es5_es6_{context}"] += Upgrading from Elasticsearch 5 to Elasticsearch 6 + +When updating from Elasticsearch 5 to Elasticsearch 6, you must delete your Jaeger instance, then recreate the Jaeger instance because of an issue with certificates. Re-creating the Jaeger instance triggers creating a new set of certificates. If you are using persistent storage the same volumes can be mounted for the new Jaeger instance as long as the Jaeger name and namespace for the new Jaeger instance are the same as the deleted Jaeger instance. + +.Procedure if Jaeger is installed as part of Red Hat Service Mesh + +. Determine the name of your Jaeger custom resource file. In this example, `istio-system` is the control plane namespace. ++ +[source,terminal] +---- +$ oc get jaeger -n +---- ++ +You should see something like the following: ++ +[source,terminal] +---- +NAME AGE +jaeger 3d21h +---- ++ +. Copy the generated custom resource file into a temporary directory: ++ +[source,terminal] +---- +$ oc get jaeger jaeger -oyaml -n > /tmp/jaeger-cr.yaml +---- ++ +. Delete the Jaeger instance: ++ +[source,terminal] +---- +$ oc delete jaeger jaeger -n +---- ++ +. Recreate the Jaeger instance from your copy of the custom resource file: ++ +[source,terminal] +---- +$ oc create -f /tmp/jaeger-cr.yaml -n +---- ++ +. Delete the copy of the generated custom resource file: ++ +[source,terminal] +---- +$ rm /tmp/jaeger-cr.yaml +---- + + +.Procedure if Jaeger not installed as part of Red Hat Service Mesh + +Before you begin, create a copy of your Jaeger custom resource file. + +. Delete the Jaeger instance by deleting the custom resource file: ++ +[source,terminal] +---- +$ oc delete -f +---- ++ +For example: ++ +[source,terminal] +---- +$ oc delete -f jaeger-prod-elasticsearch.yaml +---- ++ +. Recreate your Jaeger instance from the backup copy of your custom resource file: ++ +[source,terminal] +---- +$ oc create -f +---- ++ +. Validate that your pods have restarted: ++ +[source,terminal] +---- +$ oc get pods -n -w +---- ++ diff --git a/modules/ossm-accessing-distributed-tracing.adoc b/modules/ossm-accessing-distributed-tracing.adoc new file mode 100644 index 000000000000..3b8bde3a5604 --- /dev/null +++ b/modules/ossm-accessing-distributed-tracing.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// * service_mesh/v2x/-ossm-troubleshooting-istio.adoc + +[id="ossm-accessing-distributed-tracing_{context}"] += Accessing the {ProductName} console +//// +(how to find the URL) +Installed Operators > Jaeger Operator > Jaeger > Jaeger Details > Resources > Route > Location = Link +Networking > Routes> search Jaeger route (Location = Link) +Kiali Console > Distributed Tracing tab +//// + +The installation process creates a route to access the Jaeger console. + +.Procedure +. Log in to the {Product-title} console. + +. Navigate to *Networking* -> *Routes* and +search for the Jaeger route, which is the URL listed under *Location*. + +. To query for details of the route using the command line, enter the following command. In this example, `istio-system` is the control plane namespace. ++ +[source,terminal] +---- +$ export JAEGER_URL=$(oc get route -n istio-system jaeger -o jsonpath='{.spec.host}') +---- ++ +. Launch a browser and navigate to ``\https://``, where `` is the route that you discovered in the previous step. + +. Log in using the same user name and password that you use to access the {Product-title} console. + +. If you have added services to the service mesh and have generated traces, you can use the filters and *Find Traces* button to search your trace data. ++ +If you are validating the console installation, there is no trace data to display. diff --git a/modules/ossm-config-external-distributed-tracing.adoc b/modules/ossm-config-external-distributed-tracing.adoc new file mode 100644 index 000000000000..82390bf9609c --- /dev/null +++ b/modules/ossm-config-external-distributed-tracing.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// * service_mesh/v2x/ossm-config.adoc + +[id="ossm-config-external-distributed-tracing_{context}"] += Connecting standalone Jaeger + +If you already use standalone Jaeger for distributed tracing in {product-title}, configure your `ServiceMeshControlPlane` resource to use that standalone Jaeger instance rather than the one installed with {ProductName}. + +.Prerequisites + +* Configure and deploy a standalone Jaeger instance. For more information, see the Jaeger documentation. + +.Procedure + +. In the {product-title} web console, click *Operators* -> *Installed Operators*. + +. Click the *Project* menu and select the project where you installed the control plane, for example *istio-system*. + +. Click the {ProductName} Operator. In the *Istio Service Mesh Control Plane* column, click the name of your `ServiceMeshControlPlane` resource, for example `basic`. + +. Add the name of your standalone Jaeger instance to the `ServiceMeshControlPlane`. ++ +.. Click the *YAML* tab. ++ +.. Add the name of your standalone Jaeger instance to `spec.addons.jaeger.name` in your `ServiceMeshControlPlane` resource. In the following example, `simple-prod` is the name of your standalone Jaeger instance. ++ +.Standalone Jaeger example +[source,yaml] +---- +spec: + addons: + jaeger: + name: simple-prod +---- ++ +.. Click *Save*. + +. Click *Reload* to verify the `ServiceMeshControlPlane` resource was configured correctly. diff --git a/modules/ossm-configuring-distributed-tracing-existing-v1x.adoc b/modules/ossm-configuring-distributed-tracing-existing-v1x.adoc new file mode 100644 index 000000000000..8a2f9f9035e2 --- /dev/null +++ b/modules/ossm-configuring-distributed-tracing-existing-v1x.adoc @@ -0,0 +1,94 @@ +// Module included in the following assemblies: +// +// * service_mesh/v1x/ossm-custom-resources.adoc + +[id="ossm-configuring-distributed-tracing-existing-v1x_{context}"] += Connecting to an existing Jaeger instance + +In order for the SMCP to connect to an existing Jaeger instance, the following must be true: + +* The Jaeger instance is deployed in the same namespace as the control plane, for example, into the `istio-system` namespace. + +* To enable secure communication between services, you should enable the oauth-proxy, which secures communication to your Jaeger instance, and make sure the secret is mounted into your Jaeger instance so Kiali can communicate with it. + +* To use a custom or already existing Jaeger instance, set `spec.istio.tracing.enabled` to "false" to disable the deployment of a Jaeger instance. + +* Supply the correct jaeger-collector endpoint to Mixer by setting `spec.istio.global.tracer.zipkin.address` to the hostname and port of your jaeger-collector service. The hostname of the service is usually `-collector..svc.cluster.local`. + +* Supply the correct jaeger-query endpoint to Kiali for gathering traces by setting `spec.istio.kiali.jaegerInClusterURL` to the hostname of your jaeger-query service - the port is normally not required, as it uses 443 by default. The hostname of the service is usually `-query..svc.cluster.local`. + +* Supply the dashboard URL of your Jaeger instance to Kiali to enable accessing Jaeger through the Kiali console. You can retrieve the URL from the OpenShift route that is created by the Jaeger Operator. If your Jaeger resource is called `external-jaeger` and resides in the `istio-system` project, you can retrieve the route using the following command: ++ +[source,terminal] +---- +$ oc get route -n istio-system external-jaeger +---- ++ +.Example output +[source,terminal] +---- +NAME HOST/PORT PATH SERVICES [...] +external-jaeger external-jaeger-istio-system.apps.test external-jaeger-query [...] +---- ++ +The value under `HOST/PORT` is the externally accessible URL of the Jaeger dashboard. + + +.Example Jaeger resource +[source,yaml] +---- +apiVersion: jaegertracing.io/v1 +kind: "Jaeger" +metadata: + name: "external-jaeger" + # Deploy to the Control Plane Namespace + namespace: istio-system +spec: + # Set Up Authentication + ingress: + enabled: true + security: oauth-proxy + openshift: + # This limits user access to the Jaeger instance to users who have access + # to the control plane namespace. Make sure to set the correct namespace here + sar: '{"namespace": "istio-system", "resource": "pods", "verb": "get"}' + htpasswdFile: /etc/proxy/htpasswd/auth + + volumeMounts: + - name: secret-htpasswd + mountPath: /etc/proxy/htpasswd + volumes: + - name: secret-htpasswd + secret: + secretName: htpasswd + +---- + +The following `ServiceMeshControlPlane` example assumes that you have deployed Jaeger using the Jaeger Operator and the example Jaeger resource. + +.Example `ServiceMeshControlPlane` with external Jaeger +[source,yaml] +---- +apiVersion: maistra.io/v1 +kind: ServiceMeshControlPlane +metadata: + name: external-jaeger + namespace: istio-system +spec: + version: v1.1 + istio: + tracing: + # Disable Jaeger deployment by service mesh operator + enabled: false + global: + tracer: + zipkin: + # Set Endpoint for Trace Collection + address: external-jaeger-collector.istio-system.svc.cluster.local:9411 + kiali: + # Set Jaeger dashboard URL + dashboard: + jaegerURL: https://external-jaeger-istio-system.apps.test + # Set Endpoint for Trace Querying + jaegerInClusterURL: external-jaeger-query.istio-system.svc.cluster.local +---- diff --git a/modules/ossm-configuring-distributed-tracing-v1x.adoc b/modules/ossm-configuring-distributed-tracing-v1x.adoc new file mode 100644 index 000000000000..18be6cd4120a --- /dev/null +++ b/modules/ossm-configuring-distributed-tracing-v1x.adoc @@ -0,0 +1,183 @@ +// Module included in the following assemblies: +// +// * service_mesh/v1x/ossm-custom-resources.adoc + +[id="ossm-configuring-distributed-tracing_{context}"] += Configuring Jaeger + +When the {ProductShortName} Operator creates the `ServiceMeshControlPlane` resource it can also create the resources for distributed tracing. {ProductShortName} uses Jaeger for distributed tracing. + +You can specify your Jaeger configuration in either of two ways: + +* Configure Jaeger in the `ServiceMeshControlPlane` resource. There are some limitations with this approach. + +* Configure Jaeger in a custom `Jaeger` resource and then reference that Jaeger instance 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. + +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 installing and deploying tracing by the Service Mesh Operator. Installing Jaeger is enabled by default. To use an existing Jaeger deployment, set this value to `false`. +|`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. diff --git a/modules/ossm-configuring-distributed-tracing.adoc b/modules/ossm-configuring-distributed-tracing.adoc new file mode 100644 index 000000000000..fd8a6accfb32 --- /dev/null +++ b/modules/ossm-configuring-distributed-tracing.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// * service_mesh/v2x/customizing-installation-ossm.adoc + + +[id="ossm-specifying-distributed-tracing-configuration_{context}"] += Specifying Jaeger configuration in the SMCP + +You can configure Jaeger under the `addons` section of the `ServiceMeshControlPlane` resource. However, there are some limitations to what you can configure in the SMCP. + +When the SMCP passes configuration information to the Jaeger Operator, it triggers one of three deployment strategies: `allInOne`, `production`, or `streaming`. diff --git a/modules/ossm-configuring-external-distributed-tracing.adoc b/modules/ossm-configuring-external-distributed-tracing.adoc new file mode 100644 index 000000000000..14bee7a393c1 --- /dev/null +++ b/modules/ossm-configuring-external-distributed-tracing.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * service_mesh/v2x/customizing-installation-ossm.adoc + + +[id="ossm-specifying-external-distributed-tracing_{context}"] += Specifying Jaeger configuration in a Jaeger custom resource + +You can fully customize your Jaeger deployment by configuring Jaeger in the Jaeger custom resource (CR) rather than in the `ServiceMeshControlPlane` (SMCP) resource. This configuration is sometimes referred to as an "external Jaeger" since the configuration is specified outside of the SMCP. + +[NOTE] +==== +You must deploy the SMCP and Jaeger CR in the same namespace. For example, `istio-system`. +==== + +You can configure and deploy a standalone Jaeger instance and then specify the `name` of the Jaeger resource as the value for `spec.addons.jaeger.name` in the SMCP resource. If a Jaeger CR matching the value of `name` exists, the control plane will use the existing installation. This approach lets you fully customize your Jaeger configuration. diff --git a/modules/ossm-deploying-distributed-tracing.adoc b/modules/ossm-deploying-distributed-tracing.adoc new file mode 100644 index 000000000000..59cbbe3dd14a --- /dev/null +++ b/modules/ossm-deploying-distributed-tracing.adoc @@ -0,0 +1,135 @@ +// Module included in the following assemblies: +// +// * service_mesh/v2x/ossm-custom-resources.adoc + +[id="ossm-deploying-distributed-tracing_{context}"] += Deploying Jaeger + +Jaeger has predefined deployment strategies. You specify a deployment strategy in the Jaeger custom resource (CR) file. When you create a Jaeger instance, the Operator uses this configuration file to create the objects necessary for the deployment. + +The Jaeger Operator currently supports the following deployment strategies: + +* *allInOne* (default) - This strategy is intended for development, testing, and demo purposes and it is not for production use. The main back-end components, Agent, Collector and Query service, are all packaged into a single executable, which is configured (by default) to use in-memory storage. You can configure this deployment strategy in the SMCP. ++ +[NOTE] +==== +In-memory storage is not persistent, which means that if the Jaeger instance shuts down, restarts, or is replaced, 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, and a more scalable and highly available architecture is required. Each back-end component 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, which is currently Elasticsearch. Multiple instances of each of these components can be provisioned as required for performance and resilience purposes. You can configure this deployment strategy in the SMCP, but in order to be fully customized, you must specify your configuration in the Jaeger CR and link that to the SMCP. + +* *streaming* - The streaming strategy is designed to augment the production strategy by providing a streaming capability that sits between the Collector and the Elasticsearch back-end storage. This provides the benefit of reducing the pressure on the back-end 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]). You cannot configure this deployment strategy in the SMCP; you must configure a Jaeger CR and link that to the SMCP. + +[NOTE] +==== +The streaming strategy requires an additional Red Hat subscription for AMQ Streams. +==== + +[id="ossm-deploying-jaeger-default_{context}"] +== Default Jaeger deployment + +If you do not specify Jaeger configuration options, the `ServiceMeshControlPlane` resource will use the `allInOne` Jaeger deployment strategy by default. When using the default `allInOne` deployment strategy, set `spec.addons.jaeger.install.storage.type` to `Memory`. You can accept the defaults or specify additional configuration options under `install`. + +.Control plane default Jaeger parameters (Memory) +[source,yaml] +---- +apiVersion: maistra.io/v2 +kind: ServiceMeshControlPlane +metadata: + name: basic +spec: + version: v2.0 + tracing: + sampling: 10000 + type: Jaeger + addons: + jaeger: + name: jaeger + install: + storage: + type: Memory +---- + +[id="ossm-deploying-jaeger-production-min_{context}"] +== Production Jaeger deployment (minimal) + +To use the default settings for the `production` deployment strategy, set `spec.addons.jaeger.install.storage.type` to `Elasticsearch` and specify additional configuration options under `install`. Note that the SMCP only supports configuring Elasticsearch resources and image name. + +.Control plane default Jaeger parameters (Elasticsearch) +[source,yaml] +---- +apiVersion: maistra.io/v2 +kind: ServiceMeshControlPlane +metadata: + name: basic +spec: + version: v2.0 + tracing: + sampling: 10000 + type: Jaeger + addons: + jaeger: + name: jaeger-production + install: + storage: + type: Elasticsearch + ingress: + enabled: true + runtime: + components: + tracing.jaeger.elasticsearch: # only supports resources and image name + container: + resources: {} +---- + + +[id="ossm-deploying-jaeger-production_{context}"] +== Production Jaeger deployment (fully customized) + +The SMCP supports only minimal Elasticsearch parameters. To fully customize your production environment and access all of the Elasticsearch configuration parameters, use the Jaeger custom resource (CR) to configure Jaeger. + +Create and configure your Jaeger instance and set `spec.addons.jaeger.name` to the name of the Jaeger instance, in this example: `jaeger-production-cr`. + +.Control plane with linked Jaeger production CR +[source,yaml] +---- +apiVersion: maistra.io/v2 +kind: ServiceMeshControlPlane +metadata: + name: basic +spec: + version: v2.0 + tracing: + sampling: 1000 + type: Jaeger + addons: + jaeger: + name: jaeger-production-cr #name of Jaeger CR + install: + storage: + type: Elasticsearch + ingress: + enabled: true +---- + +[id="ossm-deploying-jaeger-streaming_{context}"] +== Streaming Jaeger deployment + +To use the `streaming` deployment strategy, you create and configure your Jaeger instance first, then set `spec.addons.jaeger.name` to the name of the Jaeger instance, in this example: `jaeger-streaming-cr`. + +.Control plane with linked Jaeger streaming CR +[source,yaml] +---- +apiVersion: maistra.io/v2 +kind: ServiceMeshControlPlane +metadata: + name: basic +spec: + version: v2.0 + tracing: + sampling: 1000 + type: Jaeger + addons: + jaeger: + name: jaeger-streaming-cr #name of Jaeger CR +---- diff --git a/modules/ossm-distributed-tracing-config-elasticsearch-v1x.adoc b/modules/ossm-distributed-tracing-config-elasticsearch-v1x.adoc new file mode 100644 index 000000000000..8b91ee42e8b9 --- /dev/null +++ b/modules/ossm-distributed-tracing-config-elasticsearch-v1x.adoc @@ -0,0 +1,130 @@ +// Module included in the following assemblies: +// +// * service_mesh/v1x/ossm-custom-resources.adoc + +[id="ossm-distributed-tracing-config-elasticsearch-v1x_{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. diff --git a/modules/ossm-distributed-tracing-config-es-cleaner-v1x.adoc b/modules/ossm-distributed-tracing-config-es-cleaner-v1x.adoc new file mode 100644 index 000000000000..45a34cb1f5c7 --- /dev/null +++ b/modules/ossm-distributed-tracing-config-es-cleaner-v1x.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies: +// +// * service_mesh/v1x/ossm-custom-resources.adoc + +[id="ossm-distributed-tracing-config-es-cleaner-v1x_{context}"] += Configuring the Elasticsearch index cleaner job + +When the {ProductShortName} Operator creates the `ServiceMeshControlPlane` it also creates the custom resource (CR) for Jaeger. The Jaeger operator then uses this CR when creating Jaeger instances. + +When using Elasticsearch storage, by default a job is created to clean old traces from it. To configure the options for this job, you edit the Jaeger custom resource (CR), to customize it for your use case. The relevant options are listed below. + +[source,yaml] +---- + apiVersion: jaegertracing.io/v1 + kind: Jaeger + spec: + strategy: production + storage: + type: elasticsearch + esIndexCleaner: + enabled: false + numberOfDays: 7 + schedule: "55 23 * * *" +---- + +.Elasticsearch index cleaner parameters +|=== +|Parameter |Values |Description + +|enabled: +|true/ false +|Enable or disable the index cleaner job. + +|numberOfDays: +|integer value +|Number of days to wait before deleting an index. + +|schedule: +|"55 23 * * *" +|Cron expression for the job to run +|=== diff --git a/modules/ossm-distributed-tracing-service-mesh.adoc b/modules/ossm-distributed-tracing-service-mesh.adoc new file mode 100644 index 000000000000..521a1865426b --- /dev/null +++ b/modules/ossm-distributed-tracing-service-mesh.adoc @@ -0,0 +1,18 @@ +//// +This CONCEPT module included in the following assemblies: +-service_mesh/v1x/ossm-vs-community.adoc +-service_mesh/v2x/ossm-vs-community.adoc +//// + +[id="ossm-distributed-tracing-service-mesh_{context}"] += Jaeger and service mesh + +Installing Jaeger with the Service Mesh on {product-title} differs from community Jaeger installations in multiple ways. These modifications are sometimes necessary to resolve issues, provide additional features, or to handle differences when deploying on {product-title}. + +* Jaeger has been enabled by default for {ProductShortName}. +* Ingress has been enabled by default for {ProductShortName}. +* The name for the Zipkin port name has changed to `jaeger-collector-zipkin` (from `http`) +* Jaeger uses Elasticsearch for storage by default when you select either the `production` or `streaming` deployment option. +* The community version of Istio provides a generic "tracing" route. {ProductName} uses a "jaeger" route that is installed by the Jaeger Operator and is already protected by OAuth. +* {ProductName} uses a sidecar for the Envoy proxy, and Jaeger also uses a sidecar, for the Jaeger agent. +These two sidecars are configured separately and should not be confused with each other. The proxy sidecar creates spans related to the pod's ingress and egress traffic. The agent sidecar receives the spans emitted by the application and sends them to the Jaeger Collector. diff --git a/modules/ossm-enabling-distributed-tracing.adoc b/modules/ossm-enabling-distributed-tracing.adoc new file mode 100644 index 000000000000..d89aa457a2ce --- /dev/null +++ b/modules/ossm-enabling-distributed-tracing.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * service_mesh/v2x/customizing-installation-ossm.adoc + + +[id="ossm-enabling-tracing_{context}"] += Enabling and disabling tracing + +You enable distributed tracing by specifying a tracing type and a sampling rate in the `ServiceMeshControlPlane` resource. + +.Default `all-in-one` Jaeger parameters +[source,yaml] +---- +apiVersion: maistra.io/v2 +kind: ServiceMeshControlPlane +metadata: + name: basic +spec: + version: v2.0 + tracing: + sampling: 100 + type: Jaeger +---- + +Currently, the only tracing type that is supported is `Jaeger`. + +Jaeger is enabled by default. To disable tracing, set `type` to `None`. + +The sampling rate determines how often the Envoy proxy generates a trace. You can use the sampling rate option to control what percentage of requests get reported to your tracing system. You can configure this setting based upon your traffic in the mesh and the amount of tracing data you want to collect. You configure `sampling` as a scaled integer representing 0.01% increments. For example, setting the value to `10` samples 0.1% of traces, setting the value to `500` samples 5% of traces, and a setting of `10000` samples 100% of traces. + +[NOTE] +==== +The SMCP sampling configuration option controls the Envoy sampling rate. You configure the Jaeger trace sampling rate in the Jaeger custom resource. +==== diff --git a/modules/ossm-tutorial-distributed-tracing-generating-traces.adoc b/modules/ossm-tutorial-distributed-tracing-generating-traces.adoc new file mode 100644 index 000000000000..9e16ea281bc0 --- /dev/null +++ b/modules/ossm-tutorial-distributed-tracing-generating-traces.adoc @@ -0,0 +1,51 @@ +//// +This PROCEDURE module included in the following assemblies: +* service_mesh/v1x/prepare-to-deploy-applications-ossm.adoc +* service_mesh/v2x/prepare-to-deploy-applications-ossm.adoc +//// + +[id="generating-sample-traces-analyzing-trace-data_{context}"] += Generating example traces and analyzing trace data + +Jaeger is an open source distributed tracing system. With Jaeger, you can perform a trace that follows the path of a request through various microservices which make up an application. Jaeger is installed by default as part of the {ProductShortName}. + +This tutorial uses {ProductShortName} and the Bookinfo sample application to demonstrate how you can use Jaeger to perform distributed tracing. + +.Prerequisites: + +* {product-title} 4.1 or higher installed. +* {ProductName} {ProductVersion} installed. +* Jaeger enabled during the installation. +* Bookinfo example application installed. + +.Procedure + +. After installing the Bookinfo sample application, send traffic to the mesh. Enter the following command several times. ++ +[source,terminal] +---- +$ curl "http://$GATEWAY_URL/productpage" +---- ++ +This command simulates a user visiting the `productpage` microservice of the application. + +. In the {product-title} console, navigate to *Networking* -> *Routes* and search for the Jaeger route, which is the URL listed under *Location*. +* Alternatively, use the CLI to query for details of the route. In this example, `istio-system` is the control plane namespace: ++ +[source,terminal] +---- +$ export JAEGER_URL=$(oc get route -n istio-system jaeger -o jsonpath='{.spec.host}') +---- ++ +.. Enter the following command to reveal the URL for the Jaeger console. Paste the result in a browser and navigate to that URL. ++ +[source,terminal] +---- +echo $JAEGER_URL +---- + +. Log in using the same user name and password as you use to access the {product-title} console. + +. In the left pane of the Jaeger dashboard, from the *Service* menu, select *productpage.bookinfo* and click the *Find Traces* button at the bottom of the pane. A list of traces is displayed. + +. Click one of the traces in the list to open a detailed view of that trace. If you click the first one in the list, which is the most recent trace, you see the details that correspond to the latest refresh of the `/productpage`. diff --git a/modules/serverless-distributed-tracing-config.adoc b/modules/serverless-distributed-tracing-config.adoc new file mode 100644 index 000000000000..3410aa7e5077 --- /dev/null +++ b/modules/serverless-distributed-tracing-config.adoc @@ -0,0 +1,66 @@ +[id="serverless-distributed-tracing-config_{context}"] += Configuring Jaeger for use with {ServerlessProductName} + +.Prerequisites + +To configure Jaeger for use with {ServerlessProductName}, you will need: + +* Cluster administrator permissions on an {product-title} cluster. +* A current installation of {ServerlessOperatorName} and Knative Serving. +* A current installation of the Jaeger Operator. + +.Procedure + +. Create and apply a `Jaeger` custom resource (CR) that contains the following: ++ +.Jaeger CR +[source,yaml] +---- +apiVersion: jaegertracing.io/v1 +kind: Jaeger +metadata: + name: jaeger + namespace: default +---- +. Enable tracing for Knative Serving, by editing the `KnativeServing` CR and adding a YAML configuration for tracing: ++ +.Tracing YAML example +[source,yaml] +---- +apiVersion: operator.knative.dev/v1alpha1 +kind: KnativeServing +metadata: + name: knative-serving + namespace: knative-serving +spec: + config: + tracing: + sample-rate: "0.1" <1> + backend: zipkin <2> + zipkin-endpoint: http://jaeger-collector.default.svc.cluster.local:9411/api/v2/spans <3> + debug: "false" <4> +---- ++ +<1> The `sample-rate` defines sampling probability. Using `sample-rate: "0.1"` means that 1 in 10 traces will be sampled. +<2> `backend` must be set to `zipkin`. +<3> The `zipkin-endpoint` must point to your `jaeger-collector` service endpoint. To get this endpoint, substitute the namespace where the Jaeger CR is applied. +<4> Debugging should be set to `false`. Enabling debug mode by setting `debug: "true"` allows all spans to be sent to the server, bypassing sampling. + +.Verification + +You can access the Jaeger web console to see tracing data, by using the `jaeger` route. + +. Get the `jaeger` route's hostname by entering the following command: ++ +[source,terminal] +---- +$ oc get route jaeger +---- ++ +.Example output +[source,terminal] +---- +NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD +jaeger jaeger-default.apps.example.com jaeger-query reencrypt None +---- +. Open the endpoint address in your browser to view the console. diff --git a/service_mesh/v2x/ossm-observability.adoc b/service_mesh/v2x/ossm-observability.adoc index 98dfabe0b7be..5b8c790269be 100644 --- a/service_mesh/v2x/ossm-observability.adoc +++ b/service_mesh/v2x/ossm-observability.adoc @@ -23,7 +23,7 @@ include::modules/ossm-config-sampling.adoc[leveloffset=+2] include::modules/ossm-config-external-jaeger.adoc[leveloffset=+2] -For more information about configuring Jaeger, see the xref:../../jaeger/jaeger_install/rhbjaeger-deploying.adoc#jaeger-deploy-default_jaeger-deploying[Jaeger documentation]. +For more information about configuring OpenShift distributed tracing platform, see the xref:../../distributed_tracing/distributed_tracing_install/distributed-tracing-deploying.adoc#distributed-tracing-deploy-default_distributed-tracing-deploying[OpenShift distributed tracing platform documentation]. include::modules/ossm-access-grafana.adoc[leveloffset=+1] diff --git a/service_mesh/v2x/ossm-reference-distributed-tracing.adoc b/service_mesh/v2x/ossm-reference-distributed-tracing.adoc new file mode 100644 index 000000000000..365dbdc30190 --- /dev/null +++ b/service_mesh/v2x/ossm-reference-distributed-tracing.adoc @@ -0,0 +1,37 @@ +[id="jaeger-config-ref"] += Jaeger configuration reference +include::modules/ossm-document-attributes.adoc[] +:context: distributed-tracing-config-reference + +toc::[] + +When the {ProductShortName} Operator deploys the `ServiceMeshControlPlane` resource, it can also create the resources for distributed tracing. {ProductShortName} uses distributed-tracing for distributed tracing. + +include::modules/ossm-enabling-distributed-tracing.adoc[leveloffset=+1] + +include::modules/ossm-configuring-distributed-tracing.adoc[leveloffset=+1] + +include::modules/ossm-deploying-distributed-tracing.adoc[leveloffset=+1] + +include::modules/ossm-configuring-external-distributed-tracing.adoc[leveloffset=+1] + +include::modules/distributed-tracing-deployment-best-practices.adoc[leveloffset=+2] + +include::modules/distributed-tracing-config-default.adoc[leveloffset=+2] + +include::modules/distributed-tracing-config-collector.adoc[leveloffset=+2] + +include::modules/distributed-tracing-config-sampling.adoc[leveloffset=+2] + +include::modules/distributed-tracing-config-storage.adoc[leveloffset=+2] + +For more information about configuring Elasticsearch with {product-title}, see xref:../../logging/config/cluster-logging-log-store.adoc[Configuring the log store] or xref:../../distributed_tracing/distributed_tracing_install/distributed-tracing-deploying.adoc[Configuring and deploying distributed tracing platform]. +//// +For information about connecting to an external Elasticsearch instance, see xref:../../jaeger/jaeger_install/rhbjaeger-deploying.adoc#jaeger-config-external-es_jaeger-deploying[Connecting to an existing Elasticsearch instance]. + +For information about connecting to an external Elasticsearch instance, see xref:../../distributed_tracing/distributed_tracing_install/distributed-tracing-deploying.adoc#jaeger-config-external-es_jaeger-deploying[Connecting to an existing Elasticsearch instance]. +//// + +include::modules/distributed-tracing-config-query.adoc[leveloffset=+2] + +include::modules/distributed-tracing-config-ingester.adoc[leveloffset=+2]