From de6f735c668bd4341b6d527e729a3ef95c6ba12c Mon Sep 17 00:00:00 2001 From: Julie Stickler Date: Wed, 12 Jan 2022 11:20:47 -0500 Subject: [PATCH] OSSMDOC-139: Document installing the OTEL Operator. --- _topic_maps/_topic_map.yml | 4 +- .../distr-tracing-deploying-otel.adoc | 19 +++ .../distr-tracing-installing.adoc | 2 + modules/distr-tracing-deploy-default.adoc | 2 +- .../distr-tracing-deploy-otel-collector.adoc | 127 ++++++++++++++++++ .../distr-tracing-deploy-production-es.adoc | 2 +- modules/distr-tracing-deploy-streaming.adoc | 2 +- ...distr-tracing-install-jaeger-operator.adoc | 4 +- .../distr-tracing-install-otel-operator.adoc | 20 ++- 9 files changed, 170 insertions(+), 12 deletions(-) create mode 100644 distr_tracing/distr_tracing_install/distr-tracing-deploying-otel.adoc create mode 100644 modules/distr-tracing-deploy-otel-collector.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 07451200672f..22ab2d15e5d8 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -2747,8 +2747,10 @@ Topics: Topics: - Name: Installing distributed tracing File: distr-tracing-installing - - Name: Configuring distributed tracing + - Name: Configuring the distributed tracing platform File: distr-tracing-deploying + - Name: Configuring distributed tracing data collection + File: distr-tracing-deploying-otel - Name: Upgrading distributed tracing File: distr-tracing-updating - Name: Removing distributed tracing diff --git a/distr_tracing/distr_tracing_install/distr-tracing-deploying-otel.adoc b/distr_tracing/distr_tracing_install/distr-tracing-deploying-otel.adoc new file mode 100644 index 000000000000..8c33f7491ab4 --- /dev/null +++ b/distr_tracing/distr_tracing_install/distr-tracing-deploying-otel.adoc @@ -0,0 +1,19 @@ +[id="distr-tracing-deploying-otel"] += Configuring and deploying distributed tracing data collection +include::modules/distr-tracing-document-attributes.adoc[] +:context: deploying-data-collection + +toc::[] + +The {OTELName} Operator uses a custom resource definition (CRD) file that defines the architecture and configuration settings to use when creating and deploying the {OTELShortName} resources. You can either install the default configuration or modify the file to better suit your business requirements. + +[IMPORTANT] +==== +The {OTELName} Operator is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. +These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. +For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/. +==== + +// The following include statements pull in the module files that comprise the assembly. + +include::modules/distr-tracing-deploy-otel-collector.adoc[leveloffset=+1] diff --git a/distr_tracing/distr_tracing_install/distr-tracing-installing.adoc b/distr_tracing/distr_tracing_install/distr-tracing-installing.adoc index d1ab1f4a5071..26902571752f 100644 --- a/distr_tracing/distr_tracing_install/distr-tracing-installing.adoc +++ b/distr_tracing/distr_tracing_install/distr-tracing-installing.adoc @@ -36,6 +36,8 @@ include::modules/distr-tracing-install-elasticsearch.adoc[leveloffset=+1] include::modules/distr-tracing-install-jaeger-operator.adoc[leveloffset=+1] +include::modules/distr-tracing-install-otel-operator.adoc[leveloffset=+1] + //// == Next steps * xref:../../distr_tracing/distr_tracing_install/distr-tracing-deploying.adoc#deploying-distributed-tracing[Deploy {DTProductName}]. diff --git a/modules/distr-tracing-deploy-default.adoc b/modules/distr-tracing-deploy-default.adoc index d14c8616b779..06416b360832 100644 --- a/modules/distr-tracing-deploy-default.adoc +++ b/modules/distr-tracing-deploy-default.adoc @@ -71,7 +71,7 @@ Follow this procedure to create an instance of {JaegerShortName} from the comman + [source,terminal] ---- -$ oc login https://{HOSTNAME}:8443 +$ oc login https://:8443 ---- . Create a new project named `tracing-system`. diff --git a/modules/distr-tracing-deploy-otel-collector.adoc b/modules/distr-tracing-deploy-otel-collector.adoc new file mode 100644 index 000000000000..d3889bce8842 --- /dev/null +++ b/modules/distr-tracing-deploy-otel-collector.adoc @@ -0,0 +1,127 @@ +//// +This module included in the following assemblies: +- distr_tracing_install/distr-tracing-deploying.adoc +//// + +[id="distr-tracing-deploy-otel-collector_{context}"] += Deploying distributed tracing data collection + +The custom resource definition (CRD) defines the configuration used when you deploy an instance of {OTELName}. + +.Prerequisites + +* The {OTELName} Operator has been installed. +//* You have reviewed the instructions for how to customize the deployment. +* You have access to the cluster as a user with the `cluster-admin` role. + +.Procedure + +. Log in to the OpenShift web console as a user with the `cluster-admin` role. + +. Create a new project, for example `tracing-system`. ++ +[NOTE] +==== +If you are installing distributed tracing as part of Service Mesh, the {DTShortName} resources must be installed in the same namespace as the `ServiceMeshControlPlane` resource, for example `istio-system`. +==== ++ +.. Navigate to *Home* -> *Projects*. + +.. Click *Create Project*. + +.. Enter `tracing-system` in the *Name* field. + +.. Click *Create*. + +. Navigate to *Operators* -> *Installed Operators*. + +. If necessary, select `tracing-system` from the *Project* menu. You might have to wait a few moments for the Operators to be copied to the new project. + +. Click the *{OTELName} Operator*. On the *Details* tab, under *Provided APIs*, the Operator provides a single link. + +. Under *OpenTelemetryCollector*, click *Create Instance*. + +. On the *Create OpenTelemetry Collector* page, to install using the defaults, click *Create* to create the {OTELShortName} instance. + +. On the *OpenTelemetryCollectors* page, click the name of the {OTELShortName} instance, for example, `opentelemetrycollector-sample`. + +. On the *Details* page, click the *Resources* tab. Wait until the pod has a status of "Running" before continuing. + +[id="distr-tracing-deploy-otel-collector-cli_{context}"] += Deploying {OTELShortName} from the CLI + +Follow this procedure to create an instance of {OTELShortName} from the command line. + +.Prerequisites + +* The {OTELName} Operator has been installed and verified. ++ +//* You have reviewed the instructions for how to customize the deployment. ++ +* You have access to the OpenShift CLI (`oc`) that matches your {product-title} version. +* You have access to the cluster as a user 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://:8443 +---- + +. Create a new project named `tracing-system`. ++ +[source,terminal] +---- +$ oc new-project tracing-system +---- + +. Create a custom resource file named `jopentelemetrycollector-sample.yaml` that contains the following text: ++ +.Example opentelemetrycollector.yaml +[source,yaml] +---- + apiVersion: opentelemetry.io/v1alpha1 + kind: OpenTelemetryCollector + metadata: + name: opentelemetrycollector-sample + namespace: openshift-operators + spec: + image: >- + registry.redhat.io/rhosdt/opentelemetry-collector-rhel8@sha256:61934ea5793c55900d09893e8f8b1f2dbd2e712faba8e97684e744691b29f25e + config: | + receivers: + jaeger: + protocols: + grpc: + exporters: + logging: + service: + pipelines: + traces: + receivers: [jaeger] + exporters: [logging] +---- + +. Run the following command to deploy {JaegerShortName}: ++ +[source,terminal] +---- +$ oc create -n tracing-system -f opentelemetrycollector.yaml +---- + +. Run the following command to watch the progress of the pods during the installation process: ++ +[source,terminal] +---- +$ oc get pods -n tracing-system -w +---- ++ +After the installation process has completed, you should see output similar to the following example: ++ +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +opentelemetrycollector-cdff7897b-qhfdx 2/2 Running 0 24s +---- diff --git a/modules/distr-tracing-deploy-production-es.adoc b/modules/distr-tracing-deploy-production-es.adoc index ed66b22737da..70ed0b1269be 100644 --- a/modules/distr-tracing-deploy-production-es.adoc +++ b/modules/distr-tracing-deploy-production-es.adoc @@ -97,7 +97,7 @@ Follow this procedure to create an instance of {JaegerShortName} from the comman + [source,terminal] ---- -$ oc login https://{HOSTNAME}:8443 +$ oc login https://:8443 ---- . Create a new project named `tracing-system`. diff --git a/modules/distr-tracing-deploy-streaming.adoc b/modules/distr-tracing-deploy-streaming.adoc index d07d6d7dfe26..ee9d841a64a1 100644 --- a/modules/distr-tracing-deploy-streaming.adoc +++ b/modules/distr-tracing-deploy-streaming.adoc @@ -112,7 +112,7 @@ Procedure + [source,terminal] ---- -$ oc login https://{HOSTNAME}:8443 +$ oc login https://:8443 ---- . Create a new project named `tracing-system`. diff --git a/modules/distr-tracing-install-jaeger-operator.adoc b/modules/distr-tracing-install-jaeger-operator.adoc index c8b33d7262f5..0e8acd01eca3 100644 --- a/modules/distr-tracing-install-jaeger-operator.adoc +++ b/modules/distr-tracing-install-jaeger-operator.adoc @@ -47,4 +47,6 @@ The *Manual* approval strategy requires a user with appropriate credentials to a . Click *Install*. -. On the *Subscription Overview* page, select the `openshift-operators` project. Wait until you see that the {JaegerName} Operator shows a status of "InstallSucceeded" before continuing. +. Navigate to *Operators* -> *Installed Operators*. + +. On the *Installed Operators* page, select the `openshift-operators` project. Wait until you see that the {JaegerName} Operator shows a status of "Succeeded" before continuing. diff --git a/modules/distr-tracing-install-otel-operator.adoc b/modules/distr-tracing-install-otel-operator.adoc index a6d7ec5ec3dd..6e1259d72027 100644 --- a/modules/distr-tracing-install-otel-operator.adoc +++ b/modules/distr-tracing-install-otel-operator.adoc @@ -6,7 +6,12 @@ This module included in the following assemblies: [id="distr-tracing-otel-operator-install_{context}"] = Installing the {OTELName} Operator -#TECH PREVIEW BOILERPLATE HERE# +[IMPORTANT] +==== +The {OTELName} Operator is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. +These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. +For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/. +==== To install {OTELName}, you use the link:https://operatorhub.io/[OperatorHub] to install the {OTELName} Operator. @@ -15,7 +20,6 @@ By default, the Operator is installed in the `openshift-operators` project. .Prerequisites * You have access to the {product-title} web console. * You have access to the cluster as a user 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 {OTELName} Operator. [WARNING] ==== @@ -28,17 +32,17 @@ Do not install Community versions of the Operators. Community Operators are not . Navigate to *Operators* -> *OperatorHub*. -. Type *distributing tracing datacollection* into the filter to locate the {OTELName} Operator. +. Type *distributing tracing data collection* into the filter to locate the {OTELName} Operator. . Click the *{OTELName} Operator* provided by Red Hat to display information about the Operator. . Click *Install*. -. On the *Install Operator* page, select the *stable* Update Channel. This automatically updates your Operator as new versions are released. +. On the *Install Operator* page, accept the default *stable* Update channel. This automatically updates your Operator as new versions are released. -. 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. +. Accept the default *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 srategy. 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, 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, 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. +. Accept the default *Automatic* approval strategy. By accepting the default, when a new version of this Operator is available, 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, 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] ==== @@ -48,4 +52,6 @@ The *Manual* approval strategy requires a user with appropriate credentials to a . Click *Install*. -. On the *Subscription Overview* page, select the `openshift-operators` project. Wait until you see that the {OTELName} Operator shows a status of "InstallSucceeded" before continuing. +. Navigate to *Operators* -> *Installed Operators*. + +. On the *Installed Operators* page, select the `openshift-operators` project. Wait until you see that the {OTELName} Operator shows a status of "Succeeded" before continuing.