SRVLOGIC-774: Operator, DI, JS and Workflows migration from OSL 1.37.2 to OSL 1.38.0 (#135)

Author: wmedvede

modules/ROOT/nav.adoc

@@ -95,6 +95,7 @@
 ****** xref:serverless-logic:cloud/operator/upgrade-serverless-operator/upgrade_1_36_0_to_1_37_0.adoc[OSL 1.36.0 to 1.37.0]
 ****** xref:serverless-logic:cloud/operator/upgrade-serverless-operator/upgrade_1_37_0_to_1_37_1.adoc[OSL 1.37.0 to 1.37.1]
 ****** xref:serverless-logic:cloud/operator/upgrade-serverless-operator/upgrade_1_37_1_to_1_37_2.adoc[OSL 1.37.1 to 1.37.2]
+****** xref:serverless-logic:cloud/operator/upgrade-serverless-operator/upgrade_1_37_2_to_1_38_0.adoc[OSL 1.37.2 to 1.38.0]
 ***** xref:serverless-logic:cloud/operator/global-configuration.adoc[Admin Configuration]
 ***** xref:serverless-logic:cloud/operator/developing-workflows.adoc[Development Mode]
 ***** xref:serverless-logic:cloud/operator/referencing-resource-files.adoc[Referencing Workflow Resources]

modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_gitops_worklow_upgrade_procedure_with_image_build_primera_version.adoc

@@ -0,0 +1,98 @@
+// Regular procedure for gitops workflows migration that requires (or the user optionally wants) a rebuild of the workflow image.
+// The caller document must set the following attributes: (see: upgrade_1_37_0_to_1_37_1.adoc as example)
+// current_operator_version, next_operator_version and next_swf_builder_image.
+:page-partial:
+
+*Pre-operator upgrade steps:*
+
+. If the workflow is configured to use persistence, you must back up the workflow database.
+Ensure that your database backup includes all database objects, not just the table's information.
+
++
+. Ensure that you have a copy of the corresponding `SonataFlow` CR, as well as any other Kubernetes resources created for that workflow.
+For example, if you are using custom property configurations, you will need a copy of the user-provided `ConfigMap` with the `application.properties` file.
+
++
+. Delete the workflow by using the following command:
+
++
+[source,terminal]
+----
+$ oc delete -f <my-workflow.yaml> -n <target_namespace>
+----
+
+*Post-operator upgrade steps:*
+
+[start=4]
+. Rebuild the workflow image using the new {product_name} `{next_operator_version}` workflow builder `{next_swf_builder_image}`, by considering the following:
+
++
+By default, the {operator_name} generates a workflow `Deployment` with the `imagePullPolicy: IfNotPresent`.
+Meaning that, if an already deployed workflow `my-wofklow`, is redeployed with the same image name, even when that image was rebuild, the old already downloaded image will be picked-up.
++
+To ensure the new image is picked-up you can:
+
+* Use a new tag, and configure the workflow with it.
++
+[source,yaml]
+----
+current image: quay.io/my-images/my-workflow:1.0
+new image: quay.io/my-images/my-workflow:1.0-1
+----
++
+[source,yaml]
+----
+apiVersion: sonataflow.org/v1alpha08
+kind: SonataFlow
+metadata:
+  name: my-workflow
+  annotations:
+    sonataflow.org/description: My Workflow
+    sonataflow.org/version: '1.0'
+    sonataflow.org/profile: gitops
+spec:
+  podTemplate:
+    container:
+      # only change the image name/tag
+      image: quay.io/my-images/my-workflow:1.0-1
+  flow:
+    # the workflow definition (don't change)
+----
++
+* Preserve the image name, and configure the workflow with the `imagePullPolicy: Always`.
++
+[source,yaml]
+----
+apiVersion: sonataflow.org/v1alpha08
+kind: SonataFlow
+metadata:
+  name: my-workflow
+  annotations:
+    sonataflow.org/description: My Workflow
+    sonataflow.org/version: '1.0'
+    sonataflow.org/profile: gitops
+spec:
+  podTemplate:
+    container:
+      image: quay.io/my-images/my-workflow:1.0
+      # only change the imagePullStrategy
+      imagePullPolicy: Always
+  flow:
+    # the workflow definition (don't change).
+----
++
+[IMPORTANT]
+====
+In any of the alternatives, when you rebuild the image (in your local environment), and when you redeploy the workflow (using the `SonataFlow` CR), you must not change
+the workflow definition, nor any workflow related assets. This includes the name, version, and description.
+====
+
+. Ensure that any Kubernetes resource for that workflow, such as the user-provided `ConfigMap` with `application.properties`, is created before you redeploy the workflow.
+
++
+. Redeploy the workflow by using the following command.
++
+[source,terminal]
+----
+$ oc apply -f <my-workflow.yaml> -n <target_namespace>
+----

modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_operator_upgrade_procedure.adoc

@@ -3,7 +3,6 @@
 // current_operator_version, next_operator_version
 :page-partial:
 
-+
 . Execute the following command to query the available installation plan for the Operator upgrade to `{next_operator_version}`:
 +
 [source,bash]

modules/serverless-logic/pages/cloud/operator/upgrade-serverless-operator/upgrade_1_37_2_to_1_38_0.adoc

@@ -0,0 +1,131 @@
+// NOTE: Do not externally parametrize these versions, they are specific to this migration guide.
+:current_operator_version: 1.37.2
+:next_operator_version: 1.38.0
+:next_swf_builder_image: registry.redhat.io/openshift-serverless-1/logic-swf-builder-rhel9:1.38.0
+
+= Upgrade {operator_name} from {current_operator_version} to {next_operator_version}
+:compat-mode!:
+// Metadata:
+:description: Upgrade OSL Operator from 1.37.2 to 1.38.0
+:keywords: kogito, sonataflow, workflow, serverless, operator, kubernetes, minikube, openshift, containers
+// links
+:openshift_operator_install_url: https://docs.openshift.com/container-platform/4.13/operators/admin/olm-adding-operators-to-cluster.html
+:openshift_operator_uninstall_url: https://docs.openshift.com/container-platform/4.13/operators/admin/olm-deleting-operators-from-cluster.html
+:kubernetes_operator_install_url: https://operatorhub.io/how-to-install-an-operator
+:kubernetes_operator_uninstall_url: https://olm.operatorframework.io/docs/tasks/uninstall-operator/
+:operatorhub_url: https://operatorhub.io/
+
+This guide describes how to upgrade the {operator_name} `{current_operator_version}` installed in an OpenShift cluster to the version `{next_operator_version}`.
+
+.Prerequisites
+* An OpenShift cluster with admin privileges and `oc` installed.
+
+== Procedure
+
+To upgrade an {operator_name} `{current_operator_version}` installation to the version `{next_operator_version}`, you must execute this procedure:
+
+=== Overall upgrade procedure
+
+It is recommended to read and understand all the steps of the procedure before executing.
+Interested parties might automate the procedure according to their convenience or infrastructure, for example, keeping all the `SonataFlow` CRs in a GitHub repository, might help considerably to implement automation, etc.
+
+. Increase the Job Service retry interval before starting the upgrade by following these <<config_jobs_service_retry_interval, steps>>.
+. Execute the steps `1` and `2` of the upgrade for every workflow with the <<workflows_dev_profile, dev profile>>.
+. Execute the steps `1`, `2` and `3` of the upgrade for every workflow with the <<workflows_preview_profile, preview profile>>.
+. Execute the steps `1`, `2`, `3` and `4` of the upgrade for every workflow with the <<workflows_gitops_profile_image_rebuild, gitops profile>>.
+. Execute the step `1` of the <<data_index_upgrade, Data Index>> upgrade.
+. Execute the step `1` of the <<jobs_service_upgrade, Job Service>> upgrade.
+. Upgrade the {operator_name} to the version `{next_operator_version}` <<operator_upgrade_procedure, following this procedure>>, and verify that the new version is running.
+. Finalize the <<data_index_upgrade, Data Index>> upgrade by continuing from step `2`.
+. Finalize the <<jobs_service_upgrade, Job Service>> upgrade by continuing from step `2`.
+. Finalize the upgrade for the workflows with the <<workflows_gitops_profile_image_rebuild, gitops profile>> by continuing from step `5`.
+. Finalize the upgrade for the workflows with the <<workflows_preview_profile, preview profile>> by continuing from step `4`.
+. Finalize the upgrade for the workflows with the <<workflows_dev_profile, dev profile>> by continuing from step `3`.
+. Restore the Job Service retry interval by following these <<restore_jobs_service_retry_interval, steps>>.
+
+[#config_jobs_service_retry_interval]
+==== Increase the Jobs Service retry interval
+
+include::../../../_common-content/cloud/operator/upgrade-serverless-operator/regular_jobs_service_increase_retry_interval_procedure.adoc[]
+
+[#workflows_dev_profile]
+==== Workflows with the `dev` profile
+
+include::../../../_common-content/cloud/operator/upgrade-serverless-operator/regular_dev_workflow_upgrade_procedure.adoc[]
+
+[#workflows_preview_profile]
+==== Workflows with the `preview` profile
+
+include::../../../_common-content/cloud/operator/upgrade-serverless-operator/regular_preview_workflow_upgrade_procedure.adoc[]
+
+[#workflows_gitops_profile_image_rebuild]
+==== Workflows with the `gitops` profile
+
+For every workflow with the `gitops` profile, it is strongly recommended to rebuild the workflow image generated for version `{current_operator_version}` before applying the upgrade, to ensure full compatibility with OpenShift Serverless Logic `{next_operator_version}`.
+
+For every workflow my-workflow with the `gitops` profile you must:
+
+include::../../../_common-content/cloud/operator/upgrade-serverless-operator/regular_gitops_worklow_upgrade_procedure_with_image_build.adoc[]
+
+[#data_index_upgrade]
+==== Data Index upgrade
+
+Every Data Index deployment must be upgraded with the following procedure:
+
+*Pre-operator upgrade steps:*
+
+. Back up the Data Index database, including all database objects, not just the table information.
+
+*Post-operator upgrade steps:*
+
+[start=2]
+. The Data Index service will be automatically restarted with the version {next_operator_version}.
+
+
+[#jobs_service_upgrade]
+==== Job Service upgrade
+
+*Pre-operator upgrade steps:*
+
+. Back up the Job Service database, including all database objects, not just the table information.
+
+*Post-operator upgrade steps:*
+
+[start=2]
+
+. The Job Service will be automatically restarted with the version {next_operator_version}.
+
+[#operator_upgrade_procedure]
+==== Operator Upgrade Procedure
+To upgrade the {operator_name} from `{current_operator_version}` to `{next_operator_version}` you must execute these steps:
+
+include::../../../_common-content/cloud/operator/upgrade-serverless-operator/regular_operator_upgrade_procedure.adoc[]
+
+. Verify that a new Data Index and Jobs Service database initialization `Job` was created:
++
+Alternatively, in every namespace where you have installed a `SonataFlowPlatform`, that has configured the `dbMigrationStrategy: job`, for any of
+the Data Index or the Jobs Service, you can verify that a new `sonataflow-db-migrator-job` was created with the following command:
+
++
+[source,bash,subs="attributes"]
+----
+kubectl get jobs \
+  -n &lt;target-namespace&gt; \
+  -l app=&lt;platform-name&gt;,app.kubernetes.io/version={next_operator_version}
+----
+
++
+You must get an output similar to this:
++
+[source, terminal]
+----
+NAME                                  STATUS     COMPLETIONS   DURATION   AGE
+sonataflow-db-migrator-job-b81d6bb3   Complete   1/1           15s        16m
+----
+
+[#restore_jobs_service_retry_interval]
+==== Restore the Jobs Service retry interval
+
+include::../../../_common-content/cloud/operator/upgrade-serverless-operator/regular_jobs_service_restore_retry_interval_procedure.adoc[]
+
+include::../../../../pages/_common-content/report-issue.adoc[]