Update install guide for dependent operators (#513)

* Update install guide for dependent operators Update the installation guide for dependent operators. Adds installation instructions for Cluster Observability Operator and cert-manager for Red Hat OpenShift using the latest channels available for those Operators. The result is that deployment of observabilityStrategy: use_redhat is now possible as the default installation method. Related: STF-1636 * Update doc-Service-Telemetry-Framework/modules/proc_deploying-certificate-manager-for-openshift-operator.adoc Co-authored-by: Chris Sibbitt <csibbitt@redhat.com> * Add prerequisites to STF deployment * Adjust wording based on editorial feedback --------- Co-authored-by: Chris Sibbitt <csibbitt@redhat.com>
infrawatch · Nov 23, 2023 · 9c79b75 · 9c79b75
1 parent e2f1961
commit 9c79b75
Show file tree

Hide file tree

Showing 4 changed files with 54 additions and 38 deletions.
diff --git a/...emetry-Framework/assemblies/assembly_installing-the-core-components-of-stf.adoc b/...emetry-Framework/assemblies/assembly_installing-the-core-components-of-stf.adoc
@@ -8,10 +8,12 @@ ifdef::context[:parent-context: {context}]
 [role="_abstract"]
 You can use Operators to load the {Project} ({ProjectShort}) components and objects. Operators manage each of the following {ProjectShort} core components:
 
-* cert-manager
+* Certificate Management
 * {MessageBus}
-* Smart Gateway
-* Prometheus and AlertManager
+* Smart Gateways
+* Prometheus and Alertmanager
+
+{Project} ({ProjectShort}) uses other supporting Operators as part of the deployment. {ProjectShort} can resolve most dependencies automatically, but you need to pre-install some Operators, such as {ObservabilityOperator}, which provides an instance of Prometheus and Alertmanager, and cert-manager for Red Hat OpenShift, which provides management of certificates.
 
 .Prerequisites
 
@@ -43,14 +45,10 @@ endif::[]
 include::../modules/con_deploying-stf-to-the-openshift-environment.adoc[leveloffset=+1]
 
 include::../modules/proc_deploying-observability-operator.adoc[leveloffset=+2]
-
-ifeval::[{SupportedOpenShiftVersion} < 4.12]
 include::../modules/proc_deploying-certificate-manager-for-openshift-operator.adoc[leveloffset=+2]
-endif::[]
 include::../modules/proc_deploying-service-telemetry-operator.adoc[leveloffset=+2]
-
-
 include::../modules/proc_creating-a-servicetelemetry-object-in-openshift.adoc[leveloffset=+1]
+
 include::../modules/con_primary-parameters-of-the-servicetelemetry-object.adoc[leveloffset=+2]
 include::../modules/proc_accessing-uis-for-stf-components.adoc[leveloffset=+1]
 include::../modules/proc_configuring-observability-strategy.adoc[leveloffset=+1]

diff --git a/...try-Framework/modules/proc_creating-a-servicetelemetry-object-in-openshift.adoc b/...try-Framework/modules/proc_creating-a-servicetelemetry-object-in-openshift.adoc
@@ -4,9 +4,16 @@
 [role="_abstract"]
 Create a `ServiceTelemetry` object in {OpenShift} to result in the Service Telemetry Operator creating the supporting components for a {Project} ({ProjectShort}) deployment. For more information, see xref:primary-parameters-of-the-servicetelemetry-object_assembly-installing-the-core-components-of-stf[].
 
+.Prerequisites
+
+. You have installed {ObservabilityOperator} to allow storage of metrics. For more information, see xref:deploying-observability-operator_assembly-installing-the-core-components-of-stf[].
+. You have installed cert-manager for Red Hat OpenShift to allow certificate management. For more information, see xref:deploying-certificate-manager-for-openshift-operator_assembly-installing-the-core-components-of-stf[].
+
 .Procedure
 
-. To create a `ServiceTelemetry` object that results in an {ProjectShort} using the core components for metrics delivery, create a `ServiceTelemetry` object:
+. Log in to your {OpenShift} environment where {ProjectShort} is hosted.
+
+. To deploy {ProjectShort} that results in the core components for metrics delivery being configured, create a `ServiceTelemetry` object:
 +
 [source,yaml,options="nowrap",role="white-space-pre"]
 ----
@@ -97,12 +104,9 @@ $ oc get pods
 
 NAME                                                        READY   STATUS    RESTARTS   AGE
 alertmanager-default-0                                      3/3     Running   0          123m
-cert-manager-operator-controller-manager-54f7679467-46pjj   2/2     Running   0          139m
 default-cloud1-ceil-meter-smartgateway-7dfb95fcb6-bs6jl     3/3     Running   0          122m
 default-cloud1-coll-meter-smartgateway-674d88d8fc-858jk     3/3     Running   0          122m
-ifndef::include_when_13[]
 default-cloud1-sens-meter-smartgateway-9b869695d-xcssf      3/3     Running   0          122m
-endif::[]
 default-interconnect-6cbf65d797-hk7l6                       1/1     Running   0          123m
 interconnect-operator-7bb99c5ff4-l6xc2                      1/1     Running   0          138m
 prometheus-default-0                                        3/3     Running   0          122m

diff --git a/...ramework/modules/proc_deploying-certificate-manager-for-openshift-operator.adoc b/...ramework/modules/proc_deploying-certificate-manager-for-openshift-operator.adoc
@@ -1,13 +1,27 @@
 :_content-type: PROCEDURE
 
 [id="deploying-certificate-manager-for-openshift-operator_{context}"]
-= Deploying Certificate Manager for OpenShift Operator
+= Deploying cert-manager for Red Hat OpenShift
 
 [role="_abstract"]
-The Certificate Manager for OpenShift is pre-installed from the `stable-v1` channel with Service Telemetry Framework ({ProjectShort}) on {OpenShift} 4.12 or later. When installing {ProjectShort} on {OpenShift} 4.10 pre-installation is required due to only the `tech-preview` channel being available. Pre-installation is only required on versions of {OpenShift} prior to 4.12.
+The cert-manager for Red Hat OpenShift (cert-manager) Operator must be pre-installed before creating an instance of {Project} ({ProjectShort}). For more information about cert-manager, see link:https://docs.openshift.com/container-platform/{NextSupportedOpenShiftVersion}/security/cert_manager_operator/index.html[cert-manager for Red Hat OpenShift overview].
+
+In previous versions of {ProjectShort}, the only available cert-manager channel was `tech-preview` which is available until {OpenShift} v4.12. Installations of cert-manager on versions of {OpenShift} v4.14 and later must be installed from the `stable-v1` channel. For new installations of {ProjectShort} it is recommended to install cert-manager from the `stable-v1` channel.
+
+[WARNING]
+Only one deployment of cert-manager can be installed per {OpenShift} cluster. Subscribing to cert-manager in more than one project causes the deployments to conflict with each other.
 
 .Procedure
 
+. Log in to your {OpenShift} environment where {ProjectShort} is hosted.
+
+. Verify cert-manager is not already installed on the {OpenShift} cluster. If any results are returned, do not install another instance of cert-manager:
++
+[source,bash,options="nowrap"]
+----
+$ oc get sub --all-namespaces -o json | jq '.items[] | select(.metadata.name | match("cert-manager")) | .metadata.name'
+----
+
 . Create a namespace for the cert-manager Operator:
 +
 [source,yaml,options="nowrap",role="white-space-pre"]
@@ -16,7 +30,7 @@ $ oc create -f - <<EOF
 apiVersion: project.openshift.io/v1
 kind: Project
 metadata:
-  name: openshift-cert-manager-operator
+  name: cert-manager-operator
 spec:
   finalizers:
   - kubernetes
@@ -31,9 +45,12 @@ $ oc create -f - <<EOF
 apiVersion: operators.coreos.com/v1
 kind: OperatorGroup
 metadata:
-  name: openshift-cert-manager-operator
-  namespace: openshift-cert-manager-operator
-spec: {}
+  name: cert-manager-operator
+  namespace: cert-manager-operator
+spec:
+  targetNamespaces:
+  - cert-manager-operator
+  upgradeStrategy: Default
 EOF
 ----
 
@@ -46,9 +63,11 @@ apiVersion: operators.coreos.com/v1alpha1
 kind: Subscription
 metadata:
   name: openshift-cert-manager-operator
-  namespace: openshift-cert-manager-operator
+  namespace: cert-manager-operator
+  labels:
+    operators.coreos.com/openshift-cert-manager-operator.cert-manager-operator: ""
 spec:
-  channel: tech-preview
+  channel: stable-v1
   installPlanApproval: Automatic
   name: openshift-cert-manager-operator
   source: redhat-operators
@@ -60,8 +79,8 @@ EOF
 +
 [source,bash,options="nowrap",role="white-space-pre"]
 ----
-$ oc get csv --namespace openshift-cert-manager-operator --selector=operators.coreos.com/openshift-cert-manager-operator.openshift-cert-manager-operator
+oc get csv --namespace cert-manager-operator --selector=operators.coreos.com/openshift-cert-manager-operator.cert-manager-operator
 
-NAME                            DISPLAY                                       VERSION   REPLACES   PHASE
-openshift-cert-manager.v1.7.1   cert-manager Operator for Red Hat OpenShift   1.7.1-1              Succeeded
+NAME                            DISPLAY                                       VERSION   REPLACES                        PHASE
+cert-manager-operator.v1.12.1   cert-manager Operator for Red Hat OpenShift   1.12.1    cert-manager-operator.v1.12.0   Succeeded
 ----
diff --git a/doc-Service-Telemetry-Framework/modules/proc_deploying-observability-operator.adoc b/doc-Service-Telemetry-Framework/modules/proc_deploying-observability-operator.adoc
@@ -4,42 +4,37 @@
 = Deploying {ObservabilityOperator}
 
 [role="_abstract"]
-// TODO: https://access.redhat.com/articles/7011708 covers migration to OBO from community-operators Prometheus Operator. This documentation references community-operators as the installation CatalogSource. It is hoping OBO is available from redhat-operators CatalogSource prior to STF 1.5.3. If so, then we will need to update this.
-{Project} ({ProjectShort}) uses other supporting Operators as part of the deployment. {ProjectShort} can resolve most dependencies automatically, but you need to pre-install some Operators, such as {ObservabilityOperator}, which provides an instance of Prometheus.
+// 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].
 
 .Procedure
 
-. To store metrics in Prometheus, enable the {ObservabilityOperator} by using the community-operators CatalogSource:
-+
-[WARNING]
-====
-Community Operators are Operators which have not been vetted or verified by Red Hat. Community Operators should be used with caution because their stability is unknown. Red Hat provides no support for community Operators.
+. Log in to your {OpenShift} environment where {ProjectShort} is hosted.
 
-https://access.redhat.com/third-party-software-support[Learn more about Red Hat’s third party software support policy]
-====
+. To store metrics in Prometheus, enable the {ObservabilityOperator} by using the redhat-operators CatalogSource:
 +
 [source,yaml,options="nowrap",role="white-space-pre"]
 ----
 $ oc create -f - <<EOF
 apiVersion: operators.coreos.com/v1alpha1
 kind: Subscription
 metadata:
-  name: observability-operator
+  name: cluster-observability-operator
   namespace: openshift-operators
 spec:
   channel: development
   installPlanApproval: Automatic
-  name: observability-operator
-  source: community-operators
+  name: cluster-observability-operator
+  source: redhat-operators
   sourceNamespace: openshift-marketplace
 EOF
 ----
 
-. Verify that the ClusterServiceVersion for Observability Operator `Succeeded`:
+. Verify that the ClusterServiceVersion for {ObservabilityOperator} `Succeeded`:
 +
 [source,bash,options="nowrap",role="white-space-pre"]
 ----
-$ oc wait --for jsonpath="{.status.phase}"=Succeeded csv --namespace=openshift-operators -l operators.coreos.com/observability-operator.openshift-operators
+$ oc wait --for jsonpath="{.status.phase}"=Succeeded csv --namespace=openshift-operators -l operators.coreos.com/cluster-observability-operator.openshift-operators
 
-clusterserviceversion.operators.coreos.com/observability-operator.v0.0.25 condition met
+clusterserviceversion.operators.coreos.com/observability-operator.v0.0.26 condition met
 ----