From d4d1a4e73beca5cf43d8c582d11ec229ea1644c2 Mon Sep 17 00:00:00 2001 From: mickogeary Date: Tue, 5 Dec 2023 17:29:32 +0000 Subject: [PATCH] mg_master_517_minor-style-edits --- .../con_configuring-multiple-clouds.adoc | 2 +- ...meters-of-the-servicetelemetry-object.adoc | 35 +++++++++---------- ...oc_configuring-observability-strategy.adoc | 4 +-- ...proc_deploying-observability-operator.adoc | 6 ++-- 4 files changed, 22 insertions(+), 25 deletions(-) diff --git a/doc-Service-Telemetry-Framework/modules/con_configuring-multiple-clouds.adoc b/doc-Service-Telemetry-Framework/modules/con_configuring-multiple-clouds.adoc index dae872f3..518c467e 100644 --- a/doc-Service-Telemetry-Framework/modules/con_configuring-multiple-clouds.adoc +++ b/doc-Service-Telemetry-Framework/modules/con_configuring-multiple-clouds.adoc @@ -6,7 +6,7 @@ You can configure multiple {OpenStack} ({OpenStackShort}) clouds to target a sin [WARNING] ==== -Be sure that every cloud deployment has a unique cloud domain configuration. For more information about configuring the domain for your cloud deployment, see xref:setting-a-unique-cloud-domain_assembly-completing-the-stf-configuration[]. +Ensure that you deploy each cloud with a unique cloud domain configuration. For more information about configuring the domain for your cloud deployment, see xref:setting-a-unique-cloud-domain_assembly-completing-the-stf-configuration[]. ==== [[osp-stf-multiple-clouds]] diff --git a/doc-Service-Telemetry-Framework/modules/con_primary-parameters-of-the-servicetelemetry-object.adoc b/doc-Service-Telemetry-Framework/modules/con_primary-parameters-of-the-servicetelemetry-object.adoc index 7926e44f..ab1c5ebd 100644 --- a/doc-Service-Telemetry-Framework/modules/con_primary-parameters-of-the-servicetelemetry-object.adoc +++ b/doc-Service-Telemetry-Framework/modules/con_primary-parameters-of-the-servicetelemetry-object.adoc @@ -2,7 +2,7 @@ = Primary parameters of the ServiceTelemetry object [role="_abstract"] -The `ServiceTelemetry` object comprises the following primary configuration parameters: +You can set the following primary configuration parameters of the `ServiceTelemetry` object to configure your {ProjectShort} deployment: * `alerting` * `backends` @@ -11,16 +11,13 @@ The `ServiceTelemetry` object comprises the following primary configuration para * `highAvailability` * `transports` - -You can configure each of these configuration parameters to provide different features in an {ProjectShort} deployment. - [id="backends_{context}"] [discrete] == The backends parameter -Use the `backends` parameter to control which storage back ends are available for storage of metrics and events, and to control the enablement of Smart Gateways that the `clouds` parameter defines. For more information, see xref:clouds_assembly-installing-the-core-components-of-stf[]. +Set the value of the `backends` parameter to allocate the storage back ends for metrics and events, and to enable the Smart Gateways that the `clouds` parameter defines. For more information, see xref:clouds_assembly-installing-the-core-components-of-stf[]. -You can use Prometheus as the metrics storage back end and Elasticsearch as the events storage back end. The Service Telemetry Operator can create custom resource objects that the Prometheus Operator watches to create a Prometheus workload. For storage of events, an external deployment of Elasticsearch is required. +You can use Prometheus as the metrics storage back end and Elasticsearch as the events storage back end. The Service Telemetry Operator can create custom resource objects that the Prometheus Operator watches to create a Prometheus workload. You need an external deployment of Elasticsearch to store events. [discrete] === Enabling Prometheus as a storage back end for metrics @@ -57,11 +54,11 @@ spec: [discrete] === Configuring persistent storage for Prometheus -Use the additional parameters that are defined in `backends.metrics.prometheus.storage.persistent` to configure persistent storage options for Prometheus, such as storage class and volume size. +Set the additional parameters in `backends.metrics.prometheus.storage.persistent` to configure persistent storage options for Prometheus, such as storage class and volume size. -Use `storageClass` to define the back end storage class. If you do not set this parameter, the Service Telemetry Operator uses the default storage class for the {OpenShift} cluster. +Define the back end storage class with the `storageClass` parameter. If you do not set this parameter, the Service Telemetry Operator uses the default storage class for the {OpenShift} cluster. -Use the `pvcStorageRequest` parameter to define the minimum required volume size to satisfy the storage request. If volumes are statically defined, it is possible that a volume size larger than requested is used. By default, Service Telemetry Operator requests a volume size of `20G` (20 Gigabytes). +Define the minimum required volume size for the storage request with the `pvcStorageRequest` parameter. By default, Service Telemetry Operator requests a volume size of `20G` (20 Gigabytes). .Procedure @@ -83,7 +80,7 @@ standard-csi cinder.csi.openstack.org Delete WaitForFirstCons $ oc edit stf default ---- -. Set the value of the backends.metrics.prometheus.enabled parameter to `true` and the value of backends.metrics.prometheus.storage.strategy to `persistent`: +. Set the value of the `backends.metrics.prometheus.enabled` parameter to `true` and the value of `backends.metrics.prometheus.storage.strategy` to `persistent`: + [source,yaml] ---- @@ -110,7 +107,7 @@ spec: [NOTE] ==== -Older versions of {ProjectShort} would manage Elasticsearch objects for the community supported Elastic Cloud on Kubernetes Operator (ECK). Elasticsearch management functionality is deprecated as of {ProjectShort} 1.5.3. Future versions of Service Telemetry Operator will continue to support forwarding to an existing Elasticsearch instance (which can be deployed and managed by ECK), but will not manage the creation of Elasticsearch objects. When upgrading an {ProjectShort} deployment, any existing Elasticsearch object and deployment will remain intact, but will no longer be managed by {ProjectShort}. +Previous versions of {ProjectShort} managed Elasticsearch objects for the community supported Elastic Cloud on Kubernetes Operator (ECK). Elasticsearch management functionality is deprecated in {ProjectShort} 1.5.3. You can still forward to an existing Elasticsearch instance that you deploy and manage with ECK, but you cannot manage the creation of Elasticsearch objects. When you upgrade your {ProjectShort} deployment, existing Elasticsearch objects and deployments remain, but are no longer managed by {ProjectShort}. ifeval::["{build}" == "downstream"] For more information about using Elasticsearch with {ProjectShort}, see the Red Hat Knowledge Base article https://access.redhat.com/articles/7031236[Using Service Telemetry Framework with Elasticsearch]. @@ -129,7 +126,7 @@ To enable events forwarding to Elasticsearch as a storage back end, you must con $ oc edit stf default ---- -. Set the value of the backends.events.elasticsearch.enabled parameter to `true` and configure the hostUrl to match the Elasticsearch instance you would like to forward to: +. Set the value of the `backends.events.elasticsearch.enabled` parameter to `true` and configure the `hostUrl` with the relevant Elasticsearch instance: + [source,yaml] ---- @@ -153,14 +150,14 @@ spec: useTls: true ---- -. Create the secret named in the `userSecretName` parameter to store the basic auth credentials +. Create the secret named in the `userSecretName` parameter to store the basic `auth` credentials + [source,bash] ---- $ oc create secret generic elasticsearch-es-elastic-user --from-literal=elastic='' ---- -. Copy the CA certificate into a file called `EXTERNAL-ES-CA.pem`, then create the secret named in the `tlsSecretName` parameter to make it available to {ProjectShort} +. Copy the CA certificate into a file named `EXTERNAL-ES-CA.pem`, then create the secret named in the `tlsSecretName` parameter to make it available to {ProjectShort} + [source,bash] ---- @@ -176,7 +173,7 @@ $ oc create secret generic elasticsearch-es-cert --from-file=ca.crt=EXTERNAL-ES- [discrete] == The clouds parameter -Use the `clouds` parameter to define which Smart Gateway objects deploy, thereby providing the interface for multiple monitored cloud environments to connect to an instance of {ProjectShort}. If a supporting back end is available, then metrics and events Smart Gateways for the default cloud configuration are created. By default, the Service Telemetry Operator creates Smart Gateways for `cloud1`. +Configure the `clouds` parameter to define which Smart Gateway objects deploy and provide the interface for monitored cloud environments to connect to an instance of {ProjectShort}. If a supporting back end is available, metrics and events Smart Gateways for the default cloud configuration are created. By default, the Service Telemetry Operator creates Smart Gateways for `cloud1`. ifndef::include_when_13[] You can create a list of cloud objects to control which Smart Gateways are created for the defined clouds. Each cloud consists of data types and collectors. Data types are `metrics` or `events`. Each data type consists of a list of collectors, the message bus subscription address, and a parameter to enable debugging. Available collectors for metrics are `collectd`, `ceilometer`, and `sensubility`. Available collectors for events are `collectd` and `ceilometer`. Ensure that the subscription address for each of these collectors is unique for every cloud, data type, and collector combination. @@ -237,13 +234,13 @@ You can use the optional Boolean parameter `debugEnabled` within the `collectors [discrete] == The alerting parameter -Use the `alerting` parameter to control creation of an Alertmanager instance and the configuration of the storage back end. By default, `alerting` is enabled. For more information, see xref:alerts_assembly-advanced-features[]. +Set the `alerting` parameter to create an Alertmanager instance and a storage back end. By default, `alerting` is enabled. For more information, see xref:alerts_assembly-advanced-features[]. [id="graphing_{context}"] [discrete] == The graphing parameter -Use the `graphing` parameter to control the creation of a Grafana instance. By default, `graphing` is disabled. For more information, see xref:dashboards_assembly-advanced-features[]. +Set the `graphing` parameter to create a Grafana instance. By default, `graphing` is disabled. For more information, see xref:dashboards_assembly-advanced-features[]. [id="highAvailability_{context}"] [discrete] @@ -254,10 +251,10 @@ Use the `graphing` parameter to control the creation of a Grafana instance. By d {ProjectShort} high availability (HA) mode is deprecated and is not supported in production environments. {OpenShift} is a highly-available platform, and you can cause issues and complicate debugging in {ProjectShort} if you enable HA mode. ==== -Use the `highAvailability` parameter to control the instantiation of multiple copies of {ProjectShort} components to reduce recovery time of components that fail or are rescheduled. By default, `highAvailability` is disabled. For more information, see xref:high-availability_assembly-advanced-features[]. +Set the `highAvailability` parameter instantiate multiple copies of {ProjectShort} components to reduce recovery time of components that fail or are rescheduled. By default, `highAvailability` is disabled. For more information, see xref:high-availability_assembly-advanced-features[]. [id="transports_{context}"] [discrete] == The transports parameter -Use the `transports` parameter to control the enablement of the message bus for a {ProjectShort} deployment. The only transport currently supported is {MessageBus}. By default, the `qdr` transport is enabled. +Set the `transports` parameter to enable the message bus for a {ProjectShort} deployment. The only transport currently supported is {MessageBus}. By default, the `qdr` transport is enabled. diff --git a/doc-Service-Telemetry-Framework/modules/proc_configuring-observability-strategy.adoc b/doc-Service-Telemetry-Framework/modules/proc_configuring-observability-strategy.adoc index 43fb10fe..e406ae5d 100644 --- a/doc-Service-Telemetry-Framework/modules/proc_configuring-observability-strategy.adoc +++ b/doc-Service-Telemetry-Framework/modules/proc_configuring-observability-strategy.adoc @@ -2,7 +2,7 @@ = Configuring an alternate observability strategy [role="_abstract"] -To configure {ProjectShort} to skip the deployment of storage, visualization, and alerting backends, add `observabilityStrategy: none` to the ServiceTelemetry spec. In this mode, only {MessageBus} routers and Smart Gateways are deployed, and you must configure an external Prometheus-compatible system to collect metrics from the {ProjectShort} Smart Gateways, and an external Elasticsearch to receive forwarded events. +To skip the deployment of storage, visualization, and alerting backends, add `observabilityStrategy: none` to the ServiceTelemetry spec. In this mode, you only deploy {MessageBus} routers and Smart Gateways, and you must configure an external Prometheus-compatible system to collect metrics from the {ProjectShort} Smart Gateways, and an external Elasticsearch to receive the forwarded events. .Procedure . Create a `ServiceTelemetry` object with the property `observabilityStrategy: none` in the `spec` parameter. The manifest shows results in a default deployment of {ProjectShort} that is suitable for receiving telemetry from a single cloud with all metrics collector types. @@ -20,7 +20,7 @@ spec: EOF ---- + -. Delete the left over objects that are managed by community operators +. Delete the remaining objects that are managed by community operators + [source,bash] ---- diff --git a/doc-Service-Telemetry-Framework/modules/proc_deploying-observability-operator.adoc b/doc-Service-Telemetry-Framework/modules/proc_deploying-observability-operator.adoc index eed17ed4..bb8a87ab 100644 --- a/doc-Service-Telemetry-Framework/modules/proc_deploying-observability-operator.adoc +++ b/doc-Service-Telemetry-Framework/modules/proc_deploying-observability-operator.adoc @@ -5,13 +5,13 @@ [role="_abstract"] // https://access.redhat.com/articles/7011708 covers migration to COO from community-operators Prometheus Operator. -The Cluster Observability Operator (COO) must be pre-installed before creating an instance of Service Telemetry Framework (STF) if the `observabilityStrategy` is set to `use_redhat` and the `backends.metrics.prometheus.enabled` is set to `true` in the `ServiceTelemetry` object. For more information about COO, see link:https://docs.openshift.com/container-platform/{NextSupportedOpenShiftVersion}/monitoring/cluster_observability_operator/cluster-observability-operator-overview.html[Cluster Observability Operator overview] in the _OpenShift Container Platform Documentation_. +You must install the Cluster Observability Operator (COO) before you create an instance of {Project} ({ProjectShort}) if the `observabilityStrategy` is set to `use_redhat` and the `backends.metrics.prometheus.enabled` is set to `true` in the `ServiceTelemetry` object. For more information about COO, see link:https://docs.openshift.com/container-platform/{NextSupportedOpenShiftVersion}/monitoring/cluster_observability_operator/cluster-observability-operator-overview.html[Cluster Observability Operator overview] in the _OpenShift Container Platform Documentation_. .Procedure . Log in to your {OpenShift} environment where {ProjectShort} is hosted. -. To store metrics in Prometheus, enable the {ObservabilityOperator} by using the redhat-operators CatalogSource: +. To store metrics in Prometheus, enable the {ObservabilityOperator} by using the `redhat-operators` CatalogSource: + [source,yaml,options="nowrap",role="white-space-pre"] ---- @@ -30,7 +30,7 @@ spec: EOF ---- -. Verify that the ClusterServiceVersion for {ObservabilityOperator} `Succeeded`: +. Verify that the `ClusterServiceVersion` for {ObservabilityOperator} has a status of `Succeeded`: + [source,bash,options="nowrap",role="white-space-pre"] ----