[STF 1.3] Upgrading from STF 1.2 to STF 1.3

Makefile

@@ -2,14 +2,19 @@ all: html
 
 html: all-html
 
+downstream: all-html-downstream
+
 pdf: all-pdf
 
 clean: all-clean
 
 browser: all-browser
 
 all-html:
-	cd doc-Service-Telemetry-Framework && $(MAKE) html
+	cd doc-Service-Telemetry-Framework && $(MAKE) html && $(MAKE) html13
+
+all-html-downstream:
+	cd doc-Service-Telemetry-Framework && $(MAKE) html BUILD=downstream && $(MAKE) html13 BUILD=downstream
 
 all-pdf:
 	cd doc-Service-Telemetry-Framework && $(MAKE) pdf

doc-Service-Telemetry-Framework/assemblies/assembly_upgrading-service-telemetry-framework-to-version-1-3.adoc

@@ -0,0 +1,59 @@
+// This assembly is included in the following assemblies:
+//
+// <List assemblies here, each on a new line>
+
+////
+Retains the context of the parent assembly if this assembly is nested within another assembly.
+For more information about nesting assemblies, see: https://redhat-documentation.github.io/modular-docs/#nesting-assemblies
+See also the complementary step on the last line of this file.
+////
+
+ifdef::context[:parent-context: {context}]
+
+[id="assembly-upgrading-service-telemetry-framework-to-version-1-3_{context}"]
+= Upgrading Service Telemetry Framework to version 1.3
+
+// The `context` attribute enables module reuse. Every module's ID
+// includes {context}, which ensures that the module has a unique ID even if
+// it is reused multiple times in a guide.
+:context: assembly-upgrading-service-telemetry-framework-to-version-1-3
+
+[role="_abstract"]
+To migrate from {Project} ({ProjectShort}) v1.2 to {ProjectShort} v1.3, you must replace the `ClusterServiceVersion` and `Subscription` objects in the `service-telemetry` namespace on your {OpenShift} ({OpenShiftShort}) environment.
+
+.Prerequisites
+
+* You have upgraded your {OpenShiftShort} environment to v4.6. {ProjectShort} v1.3 does not run on {OpenShiftShort} v4.5 and lower. {ProjectShort} v1.2 does not run on {OpenShiftShort} v4.7 and higher.
+* You have backed up your data prior to any upgrade of the environment. Upgrading {ProjectShort} v1.2 to v1.3 results in a brief outage while the Smart Gateways are upgraded. Additionally, changes to the `ServiceTelemetry` and `SmartGateway` objects do not have any effect while the Operators are being replaced.
+
+To upgrade from {ProjectShort} v1.2 to v1.3, complete the following procedures:
+
+.Procedure
+
+. xref:removing-service-telemetry-framework-1-2-operators_assembly-upgrading-service-telemetry-framework-to-version-1-3[Remove the {ProjectShort} 1.2 Operators].
+. xref:subscribing-to-the-service-telemetry-operator_assembly-upgrading-service-telemetry-framework-to-version-1-3[Subscribe to the Service Telemetry Operator].
+
+
+include::../modules/proc_removing-service-telemetry-framework-1-2-operators.adoc[leveloffset=+1]
+include::../modules/proc_subscribing-to-the-service-telemetry-operator.adoc[leveloffset=+1]
+
+When the new Operators start, they reconcile the existing `ServiceTelemetry` and `SmartGateway` objects, resulting in the restart of Smart Gateway containers.
+
+* To check the state of the Smart Gateway containers, use the `oc get pods` command:
++
+[source,bash,options="nowrap",subs="+quotes"]
+----
+oc get pods
+
+NAME                                                      READY   STATUS        RESTARTS   AGE
+...
+default-cloud1-ceil-meter-smartgateway-5849c4cdb5-xgl42   1/1     Running       0          35s
+default-cloud1-coll-meter-smartgateway-749674f75c-k7pm7   2/2     Terminating   0          56m
+default-cloud1-coll-meter-smartgateway-868476456b-ksh9b   2/2     Running       0          26s
+...
+----
+
+// The following line is necessary to allow assemblies be included in other
+// assemblies. It restores the `context` variable to its previous state.
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]

doc-Service-Telemetry-Framework/master.adoc

@@ -28,5 +28,8 @@ include::assemblies/assembly_completing-the-stf-configuration.adoc[leveloffset=+
 //advanced features
 include::assemblies/assembly_advanced-features.adoc[leveloffset=+1]
 
+// upgrading to 1.3
+include::assemblies/assembly_upgrading-service-telemetry-framework-to-version-1-3.adoc[leveloffset=+1]
+
 //collectd plugins
 include::common/collectd/ref_collectd-plugins.adoc[leveloffset=+1]

doc-Service-Telemetry-Framework/modules/proc_removing-service-telemetry-framework-1-2-operators.adoc

@@ -0,0 +1,159 @@
+// Module included in the following assemblies:
+//
+// <List assemblies here, each on a new line>
+
+// This module can be included from assemblies using the following include statement:
+// include::<path>/proc_upgrading-service-telemetry-framework-to-version-1-3.adoc[leveloffset=+1]
+
+// The file name and the ID are based on the module title. For example:
+// * file name: proc_doing-procedure-a.adoc
+// * ID: [id='proc_doing-procedure-a_{context}']
+// * Title: = Doing procedure A
+//
+// The ID is used as an anchor for linking to the module. Avoid changing
+// it after the module has been published to ensure existing links are not
+// broken.
+//
+// The `context` attribute enables module reuse. Every module's ID includes
+// {context}, which ensures that the module has a unique ID even if it is
+// reused multiple times in a guide.
+//
+// Start the title with a verb, such as Creating or Create. See also
+// _Wording of headings_ in _The IBM Style Guide_.
+[id="removing-service-telemetry-framework-1-2-operators_{context}"]
+= Removing {Project} 1.2 Operators
+
+[role="_abstract"]
+Remove the Operators from {ProjectShort} v1.2, Smart Gateway Operator, and Service Telemetry Operator.
+
+[NOTE]
+Due to changes in the API interface, you must temporarily remove the `clouds` parameters. This results in the removal of all Smart Gateways until after the upgrade and the inability to deliver metrics and events during the upgrade.
+
+.Procedure
+
+. Retrieve the current `ServiceTelemetry` object and note the contents, in particular the `clouds` parameter because you must remove this parameter before you upgrade the Operators.
++
+[source,bash,options="nowrap"]
+----
+$ oc get stf default -oyaml
+----
+
+. Modify the ServiceTelemetry object to clear the `clouds` parameter and set it to an empty list. Set `cloudsRemoveOnMissing` to `true` to remove all Smart Gateways.
++
+WARNING: This command stops all monitoring functions until after the upgrade is completed and the `clouds` object is redefined. If you use the default clouds configuration, it is not defined in your ServiceTelemetry object.
++
+[source,bash,options="nowrap"]
+----
+$ oc patch stf default --patch $'spec:\n  clouds: []\n  cloudsRemoveOnMissing: true' --type=merge
+----
+
+. Monitor the Smart Gateway pods until they are fully terminated and removed.
++
+[source,bash,options="nowrap"]
+----
+$ oc get pods --selector app=smart-gateway --watch
+
+NAME                                                      READY   STATUS    RESTARTS   AGE
+default-cloud1-ceil-meter-smartgateway-58cc854f4-hgk92    1/1     Running   0          2m42s
+default-cloud1-coll-meter-smartgateway-6c76f9786d-crn9b   2/2     Running   0          2m55s
+default-cloud1-coll-meter-smartgateway-6c76f9786d-crn9b   2/2     Terminating   0          3m12s
+default-cloud1-ceil-meter-smartgateway-58cc854f4-hgk92    1/1     Terminating   0          3m
+...
+
+----
+. Retrieve the `Subscription` name of the Smart Gateway Operator:
++
+[source,bash,options="nowrap"]
+----
+$ oc get sub smart-gateway-operator-stable-1.2-redhat-operators-openshift-marketplace
+
+NAME                                                                       PACKAGE                  SOURCE             CHANNEL
+smart-gateway-operator-stable-1.2-redhat-operators-openshift-marketplace   smart-gateway-operator   redhat-operators   stable-1.2
+----
+. Delete the Smart Gateway Operator subscription:
++
+[source,bash,options="nowrap"]
+----
+$ oc delete sub smart-gateway-operator-stable-1.2-redhat-operators-openshift-marketplace
+
+subscription.operators.coreos.com "smart-gateway-operator-stable-1.2-redhat-operators-openshift-marketplace" deleted
+----
+
+. Retrieve the Smart Gateway Operator ClusterServiceVersion:
++
+[source,bash,options="nowrap"]
+----
+$ oc get csv -o name | grep -E 'smart-gateway'
+
+clusterserviceversion.operators.coreos.com/smart-gateway-operator.v2.2.1623675667
+----
+
+. Delete the Smart Gateway Operator ClusterServiceVersion:
++
+[source,bash,options="nowrap"]
+----
+$ oc delete clusterserviceversion.operators.coreos.com/smart-gateway-operator.v2.2.1623675667
+
+clusterserviceversion.operators.coreos.com "smart-gateway-operator.v2.2.1623675667" deleted
+----
+
+. Delete the SmartGateway Custom Resource Definition:
++
+[source,bash,options="nowrap"]
+----
+$ oc delete crd smartgateways.smartgateway.infra.watch
+
+customresourcedefinition.apiextensions.k8s.io "smartgateways.smartgateway.infra.watch" deleted
+----
+
+. Patch the Service Telemetry Operator Subscription to use the stable-1.3 channel:
++
+[source,bash,options="nowrap"]
+----
+$ oc patch sub service-telemetry-operator --patch $'spec:\n  channel: stable-1.3' --type=merge
+
+subscription.operators.coreos.com/service-telemetry-operator patched
+----
+
+. Monitor the output of the `oc get csv` command until the Smart Gateway Operator is installed and Service Telemetry Operator is `Pending` for version 1.2 and 1.3:
++
+[source,bash,options="nowrap"]
+----
+$ oc get csv
+
+NAME                                         DISPLAY                                         VERSION          REPLACES                                     PHASE
+amq7-cert-manager.v1.0.0                     Red Hat Integration - AMQ Certificate Manager   1.0.0                                                         Succeeded
+amq7-interconnect-operator.v1.2.4            Red Hat Integration - AMQ Interconnect          1.2.4            amq7-interconnect-operator.v1.2.3            Succeeded
+elastic-cloud-eck.v1.6.0                     Elasticsearch (ECK) Operator                    1.6.0            elastic-cloud-eck.v1.5.0                     Succeeded
+prometheusoperator.0.47.0                    Prometheus Operator                             0.47.0           prometheusoperator.0.37.0                    Succeeded
+service-telemetry-operator.v1.2.1623675667   Service Telemetry Operator                      1.2.1623675667                                                Pending
+service-telemetry-operator.v1.3.1622734200   Service Telemetry Operator                      1.3.1622734200   service-telemetry-operator.v1.2.1623675667   Pending
+smart-gateway-operator.v3.0.1622734308       Smart Gateway Operator                          3.0.1622734308                                                Succeeded
+----
+
+. Delete the Service Telemetry Operator v1.2 ClusterServiceVersion:
++
+[source,bash,options="nowrap"]
+----
+$ oc delete csv service-telemetry-operator.v1.2.1623675667
+
+clusterserviceversion.operators.coreos.com "service-telemetry-operator.v1.2.1623675667" deleted
+----
+
+. Edit the ServiceTelemetry object and insert the contents of your previously noted `clouds` parameter. If the `clouds` parameter was not previously defined because you used the default Smart Gateway instances, remove the `clouds: []` parameter.
++
+[source,bash,options="nowrap"]
+----
+$ oc edit stf default
+----
+
+. Validate that the Smart Gateways have been restored:
++
+[source,bash,options="nowrap"]
+----
+$ oc get pods --selector app=smart-gateway
+
+NAME                                                      READY   STATUS    RESTARTS   AGE
+default-cloud1-ceil-meter-smartgateway-6484b98b68-sl7mb   2/2     Running   0          5m56s
+default-cloud1-coll-meter-smartgateway-799f687658-nfzr6   2/2     Running   0          6m6s
+----

doc-Service-Telemetry-Framework/modules/proc_removing-the-service-telemetry-framework-v1-1-catalogsource.adoc

@@ -0,0 +1,38 @@
+// Module included in the following assemblies:
+//
+// <List assemblies here, each on a new line>
+
+// This module can be included from assemblies using the following include statement:
+// include::<path>/proc_removing-the-service-telemetry-framework-v1-1-catalogsource.adoc[leveloffset=+1]
+
+// The file name and the ID are based on the module title. For example:
+// * file name: proc_doing-procedure-a.adoc
+// * ID: [id='proc_doing-procedure-a_{context}']
+// * Title: = Doing procedure A
+//
+// The ID is used as an anchor for linking to the module. Avoid changing
+// it after the module has been published to ensure existing links are not
+// broken.
+//
+// The `context` attribute enables module reuse. Every module's ID includes
+// {context}, which ensures that the module has a unique ID even if it is
+// reused multiple times in a guide.
+//
+// Start the title with a verb, such as Creating or Create. See also
+// _Wording of headings_ in _The IBM Style Guide_.
+[id="removing-the-service-telemetry-framework-v1-1-catalogsource_{context}"]
+= Removing the Service Telemetry Framework v1.1 CatalogSource
+
+[role="_abstract"]
+Remove the {ProjectShort} v1.1 CatalogSource. {ProjectShort} v1.2 is shipped in the default-enabled redhat-operators CatalogSource.
+
+.Procedure
+
+* Delete the redhat-operators-stf CatalogSource:
++
+[source,bash,options="nowrap",subs="+quotes"]
+----
+$ oc delete catalogsource -nopenshift-marketplace redhat-operators-stf
+
+catalogsource.operators.coreos.com "redhat-operators-stf" deleted
+----