From 5b9dfa3c3da17153cec81cb87c0d16811fa5b399 Mon Sep 17 00:00:00 2001 From: Walter Medvedeo Date: Mon, 2 Feb 2026 18:06:18 +0100 Subject: [PATCH] SRVLOGIC-773: Operator, DI, JS and Workflows migration from OSL 1.37.0 to OSL 1.37.1 --- modules/ROOT/nav.adoc | 1 + ...egular_dev_workflow_upgrade_procedure.adoc | 31 ++++ ...ow_upgrade_procedure_with_image_build.adoc | 103 +++++++++++++ ...egular_jobs_service_upgrade_procedure.adoc | 36 +++++ .../regular_operator_upgrade_procedure.adoc | 44 ++++++ ...ar_preview_workflow_upgrade_procedure.adoc | 35 +++++ .../upgrade_1_37_0_to_1_37_1.adoc | 143 ++++++++++++++++++ 7 files changed, 393 insertions(+) create mode 100644 modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_dev_workflow_upgrade_procedure.adoc create mode 100644 modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_gitops_worklow_upgrade_procedure_with_image_build.adoc create mode 100644 modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_jobs_service_upgrade_procedure.adoc create mode 100644 modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_operator_upgrade_procedure.adoc create mode 100644 modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_preview_workflow_upgrade_procedure.adoc create mode 100644 modules/serverless-logic/pages/cloud/operator/upgrade-serverless-operator/upgrade_1_37_0_to_1_37_1.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 28eb1a68..4ea2f962 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -93,6 +93,7 @@ ****** xref:serverless-logic:cloud/operator/upgrade-serverless-operator/upgrade_1_34_0_to_1_35_0.adoc[OSL 1.34.0 to 1.35.0] ****** xref:serverless-logic:cloud/operator/upgrade-serverless-operator/upgrade_1_35_0_to_1_36_0.adoc[OSL 1.35.0 to 1.36.0] ****** 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/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] diff --git a/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_dev_workflow_upgrade_procedure.adoc b/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_dev_workflow_upgrade_procedure.adoc new file mode 100644 index 00000000..ded80e09 --- /dev/null +++ b/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_dev_workflow_upgrade_procedure.adoc @@ -0,0 +1,31 @@ +// Regular procedure for dev profile workflows migration. +// 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 +:page-partial: + +Every workflow with the `dev` profile must be deleted before applying the Operator upgrade to the version `{next_operator_version}`, and then, redeployed after the upgrade is completed. + +For every workflow `my-workflow` with the `dev` profile you must: + +*Pre-operator upgrade steps:* + +. 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 -n +---- + +*Post-operator upgrade steps:* + +[start=3] +. 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 -n +---- diff --git a/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_gitops_worklow_upgrade_procedure_with_image_build.adoc b/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_gitops_worklow_upgrade_procedure_with_image_build.adoc new file mode 100644 index 00000000..0be89361 --- /dev/null +++ b/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_gitops_worklow_upgrade_procedure_with_image_build.adoc @@ -0,0 +1,103 @@ +// 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:* + +. Rebuild the workflow image using the new {product_name} `{next_operator_version}` workflow builder `{next_swf_builder_image}` and reconfigure your workflow, considering the following: + ++ +By default, the {product_name} generates a workflow `Deployment` with `imagePullPolicy: IfNotPresent`. +This means that if an already deployed workflow is redeployed using the same image name, the previously downloaded image will be reused, even if the image was rebuilt. + ++ +[IMPORTANT] +==== +In all cases, you are not generating a new workflow version, but a new image build. Therefore, you must not change the workflow definition or any related assets, including the name, version, and description. +==== + ++ +To ensure that the new image is pulled, you can: ++ + + +* Use a new image tag and configure the workflow to use it (recommended): ++ +[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: # don't change + 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: # don't change + 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). +---- ++ + +. 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 -n +---- + +[#workflows_gitops_profile_image_rebuild_post_upgrade] +*Post-operator upgrade steps:* + +[start=5] +. 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 reconfigured workflow using the following command: ++ +[source,terminal] +---- +$ oc apply -f -n +---- diff --git a/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_jobs_service_upgrade_procedure.adoc b/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_jobs_service_upgrade_procedure.adoc new file mode 100644 index 00000000..e93c02a4 --- /dev/null +++ b/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_jobs_service_upgrade_procedure.adoc @@ -0,0 +1,36 @@ +// Regular Jobs service upgrade procedure. +// 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 +:page-partial: + +Every Job Service deployment must be upgraded with the following procedure: + +*Pre-operator upgrade steps:* + +. Back up the Job Service database, including all database objects, not just the table information. + +. Scale the Job Service to zero ++ +You can scale the Job Service to zero with the following command: + ++ +[source, bash] +---- +oc patch sonataflowplatform -n \ + --type merge \ + -p '{"spec":{"services":{"jobService":{"podTemplate":{"replicas":0}}}}}' +---- + +*Post-operator upgrade steps:* + +[start=3] +. Rescale the Job Service ++ +After redeploying and rescaling all the workflows, you must rescale the Job Service to 1 with the following command: ++ +[source, bash] +---- +oc patch sonataflowplatform -n \ + --type merge \ + -p '{"spec":{"services":{"jobService":{"podTemplate":{"replicas":1}}}}}' +---- diff --git a/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_operator_upgrade_procedure.adoc b/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_operator_upgrade_procedure.adoc new file mode 100644 index 00000000..7d5996fa --- /dev/null +++ b/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_operator_upgrade_procedure.adoc @@ -0,0 +1,44 @@ +// Regular operator upgrade procedure by executing the available installing plan for the next version. +// 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 +:page-partial: + ++ +. Execute the following command to query the available installation plan for the Operator upgrade to `{next_operator_version}`: ++ +[source,bash] +---- +oc get installplan -n openshift-serverless-logic +---- ++ +You must get an output like this: ++ +[source,terminal,subs="attributes"] +---- +NAME CSV APPROVAL APPROVED +install-YYYY logic-operator.v{next_operator_version} Manual false +install-XXXX logic-operator.v{current_operator_version} Manual true +---- ++ +Approve the installation plan corresponding to `logic-operator.v{next_operator_version}` with a command like this: ++ +[source,bash,subs="attributes"] +---- +oc patch installplan install-YYYY -n openshift-serverless-logic --type merge -p '{"spec":{"approved":true}}' +---- +. Verify that the {operator_name} `{next_operator_version}` was updated correctly: ++ +When the installation plan is executed, you can execute the following command to verify the upgrade was successful: ++ +[source,bash] +---- +oc get csv -n openshift-serverless-logic +---- ++ +You must get an output like this: ++ +[source,terminal,subs="attributes"] +---- +NAME DISPLAY VERSION REPLACES PHASE +logic-operator.v{next_operator_version} OpenShift Serverless Logic Operator {next_operator_version} logic-operator.v{current_operator_version} Succeeded +---- \ No newline at end of file diff --git a/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_preview_workflow_upgrade_procedure.adoc b/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_preview_workflow_upgrade_procedure.adoc new file mode 100644 index 00000000..4dbe4dc3 --- /dev/null +++ b/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_preview_workflow_upgrade_procedure.adoc @@ -0,0 +1,35 @@ +// Regular procedure for preview profile workflows migration. +// 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 +:page-partial: + +Every workflow with the `preview` profile must be deleted before applying the Operator upgrade to the version `{next_operator_version}`, and then, redeployed after the upgrade is completed. + +For every workflow `my-workflow` with the `preview` profile you must: + +*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 -n +---- + +*Post-operator upgrade steps:* + +[start=4] +. 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 -n +---- diff --git a/modules/serverless-logic/pages/cloud/operator/upgrade-serverless-operator/upgrade_1_37_0_to_1_37_1.adoc b/modules/serverless-logic/pages/cloud/operator/upgrade-serverless-operator/upgrade_1_37_0_to_1_37_1.adoc new file mode 100644 index 00000000..d052d485 --- /dev/null +++ b/modules/serverless-logic/pages/cloud/operator/upgrade-serverless-operator/upgrade_1_37_0_to_1_37_1.adoc @@ -0,0 +1,143 @@ +// NOTE: Do not externally parametrize these versions, they are specific to this migration guide. +:current_operator_version: 1.37.0 +:next_operator_version: 1.37.1 +:next_swf_builder_image: registry.redhat.io/openshift-serverless-1/logic-swf-builder-rhel9:1.37.1 + += Upgrade {operator_name} from {current_operator_version} to {next_operator_version} +:compat-mode!: +// Metadata: +:description: Upgrade OSL Operator from 1.37.0 to 1.37.1 +: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. + +. Execute the steps `1` and `2` of the upgrade for every workflow with the <>. +. Execute the steps `1`, `2` and `3` of the upgrade for every workflow with the <>. +. Execute the steps `1`, `2`, `3` and `4` of the upgrade for every workflow with the <>. +. Execute the step `1` of the <> upgrade. +. Execute the step `1` of the <> upgrade. +. Upgrade the {operator_name} to the version `{next_operator_version}` <>, and verify that the new version is running. +. Finalize the <> upgrade by continuing from step `2`. +. Finalize the <> upgrade by continuing from step `2`. +. Finalize the upgrade for the workflows with the <> by continuing from step `5`. +. Finalize the upgrade for the workflows with the <> by continuing from step `4`. +. Finalize the upgrade for the workflows with the <> by continuing from step `3`. + +[#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: + +. Remove Data Index and Jobs Service database initialization `Job`: ++ +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 must remove the associated `sonataflow-db-migrator-job` with the following command: ++ +[source,bash] +---- + oc delete job sonataflow-db-migrator-job -n +---- + ++ +include::../../../_common-content/cloud/operator/upgrade-serverless-operator/regular_operator_upgrade_procedure.adoc[] + +. Verify the Data Index and Jobs Service database initialization `Job` was created: + ++ +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 the `sonataflow-db-migrator-job` was created with the following command: + ++ +[source,bash] +---- + oc get job sonataflow-db-migrator-job -n +---- + ++ +Alternatively, you can verify the Data Index database was migrated correctly with the following command: + ++ +[source,bash] +---- +oc logs job/sonataflow-db-migrator-job -n +---- + ++ +You must get an output containing these lines: ++ +[source,terminal] +---- +2026-02-02 11:45:09,606 INFO [org.kie.kog.mig.pos.MigrationService] (main) Migrating data-index +2026-02-02 11:45:09,778 INFO [org.fly.cor.int.com.DbValidate] (main) Successfully validated 22 migrations (execution time 00:00.043s) +2026-02-02 11:45:09,810 INFO [org.fly.cor.int.com.DbMigrate] (main) Current version of schema "sonataflow-platform-data-index-service": 1.45.1.4 +2026-02-02 11:45:09,824 INFO [org.fly.cor.int.com.DbMigrate] (main) Migrating schema "sonataflow-platform-data-index-service" to version "1.46.0 - add user task id column" +2026-02-02 11:45:09,861 INFO [org.fly.cor.int.com.DbMigrate] (main) Migrating schema "sonataflow-platform-data-index-service" to version "1.47.0 - adjust column sizes in tables updated by hibernate" +2026-02-02 11:45:09,882 INFO [org.fly.cor.int.com.DbMigrate] (main) Successfully applied 2 migrations to schema "sonataflow-platform-data-index-service", now at version v1.47.0 (execution time 00:00.010s) + +---- + +include::../../../../pages/_common-content/report-issue.adoc[]