From fdbef4080e84f21a85cf128d5a9f0d7e39522c67 Mon Sep 17 00:00:00 2001 From: Walter Medvedeo Date: Fri, 20 Mar 2026 19:33:17 +0100 Subject: [PATCH 1/2] SRVLOGIC-892: Operator, DI, JS and Workflows migration from OSL 1.37.1 to OSL 1.37.2 --- modules/ROOT/nav.adoc | 1 + .../upgrade_1_37_1_to_1_37_2.adoc | 163 ++++++++++++++++++ 2 files changed, 164 insertions(+) create mode 100644 modules/serverless-logic/pages/cloud/operator/upgrade-serverless-operator/upgrade_1_37_1_to_1_37_2.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 4ea2f962..5b42fa6d 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -94,6 +94,7 @@ ****** 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/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/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/cloud/operator/upgrade-serverless-operator/upgrade_1_37_1_to_1_37_2.adoc b/modules/serverless-logic/pages/cloud/operator/upgrade-serverless-operator/upgrade_1_37_1_to_1_37_2.adoc new file mode 100644 index 00000000..70b7a8a1 --- /dev/null +++ b/modules/serverless-logic/pages/cloud/operator/upgrade-serverless-operator/upgrade_1_37_1_to_1_37_2.adoc @@ -0,0 +1,163 @@ +// NOTE: Do not externally parametrize these versions, they are specific to this migration guide. +:current_operator_version: 1.37.1 +:next_operator_version: 1.37.2 +:next_swf_builder_image: registry.redhat.io/openshift-serverless-1/logic-swf-builder-rhel9:1.37.2 + += Upgrade {operator_name} from {current_operator_version} to {next_operator_version} +:compat-mode!: +// Metadata: +:description: Upgrade OSL Operator from 1.37.1 to 1.37.2 +: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 <>. +. 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`. +. Restore the Job Service retry interval by following these <>. + +[#config_jobs_service_retry_interval] +==== Increase the Jobs Service retry interval + +During system upgrades or migrations, job executions may temporarily fail due to transitional states (e.g., partial availability of workflows being migrated). +To prevent jobs from being prematurely discarded during this process, you must increase the retry interval before starting the upgrade. +This ensures that potential failing jobs are retained in the system while the upgrade is in progress, and have sufficient time to be retried successfully once the system stabilizes. + +To increase the retry interval you must: + +. Add the environment variable `KOGITO_JOBS_SERVICE_MAXINTERVALLIMITTORETRYMILLIS` with a relaxed configuration to the `jobService.podTemplate.container` in your `SonataFlowPlatform` (CR). +. Make sure to keep all existing fields in your `SonataFlowPlatform` (CR) unchanged. +. Reapply the `SonataFlowPlatform` (CR). When reapplied, the Jobs Service deployment will be updated and rolled out. + +[source,yaml] +---- +apiVersion: sonataflow.org/v1alpha08 +kind: SonataFlowPlatform +metadata: + name: sonataflow-platform-example + namespace: example-namespace +spec: +# all the fields in your SonataFlowPlatform must be preserved. + services + jobService: + container: + env: + - name: KOGITO_JOBS_SERVICE_MAXINTERVALLIMITTORETRYMILLIS + # e.g. retry period of 4 hs. + value: 14400000 +---- + + +[#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 +---- + +[#restore_jobs_service_retry_interval] +==== Restore the Jobs Service retry interval + +After redeploying all workflows you must restore the Job Service retry interval by following these steps: + +. Remove the environment variable `KOGITO_JOBS_SERVICE_MAXINTERVALLIMITTORETRYMILLIS` added in <>, or restore it to the previously configured value in cases where you have override the default value. +. Make sure to keep all existing fields in your `SonataFlowPlatform` (CR) unchanged. +. Reapply the `SonataFlowPlatform` (CR). When reapplied, the Jobs Service deployment will be updated and rolled out. + +include::../../../../pages/_common-content/report-issue.adoc[] From b4233859ce984898c4d0e55ce8876bccea4262c7 Mon Sep 17 00:00:00 2001 From: Walter Medvedeo Date: Tue, 24 Mar 2026 07:47:46 +0100 Subject: [PATCH 2/2] Refactor the jobs service retry inteval setups to reusable files --- ...ice_increase_retry_interval_procedure.adoc | 32 +++++++++++++++++ ...vice_restore_retry_interval_procedure.adoc | 10 ++++++ .../upgrade_1_37_1_to_1_37_2.adoc | 35 ++----------------- 3 files changed, 44 insertions(+), 33 deletions(-) create mode 100644 modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_jobs_service_increase_retry_interval_procedure.adoc create mode 100644 modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_jobs_service_restore_retry_interval_procedure.adoc diff --git a/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_jobs_service_increase_retry_interval_procedure.adoc b/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_jobs_service_increase_retry_interval_procedure.adoc new file mode 100644 index 00000000..4f278301 --- /dev/null +++ b/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_jobs_service_increase_retry_interval_procedure.adoc @@ -0,0 +1,32 @@ +// Regular Jobs service procedure for increasing the jobs retry interval. +// 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: + +During system upgrades or migrations, job executions may temporarily fail due to transitional states (e.g., partial availability of workflows being migrated). +To prevent jobs from being prematurely discarded during this process, you must increase the retry interval before starting the upgrade. +This ensures that potential failing jobs are retained in the system while the upgrade is in progress, and have sufficient time to be retried successfully once the system stabilizes. + +To increase the retry interval you must: + +. Add the environment variable `KOGITO_JOBS_SERVICE_MAXINTERVALLIMITTORETRYMILLIS` with a relaxed configuration to the `jobService.podTemplate.container` in your `SonataFlowPlatform` (CR). +. Make sure to keep all existing fields in your `SonataFlowPlatform` (CR) unchanged. +. Reapply the `SonataFlowPlatform` (CR). When reapplied, the Jobs Service deployment will be updated and rolled out. + +[source,yaml] +---- +apiVersion: sonataflow.org/v1alpha08 +kind: SonataFlowPlatform +metadata: + name: sonataflow-platform-example + namespace: example-namespace +spec: +# all the fields in your SonataFlowPlatform must be preserved. + services + jobService: + container: + env: + - name: KOGITO_JOBS_SERVICE_MAXINTERVALLIMITTORETRYMILLIS + # e.g. retry period of 4 hs. + value: 14400000 +---- \ No newline at end of file diff --git a/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_jobs_service_restore_retry_interval_procedure.adoc b/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_jobs_service_restore_retry_interval_procedure.adoc new file mode 100644 index 00000000..95ada5ca --- /dev/null +++ b/modules/serverless-logic/pages/_common-content/cloud/operator/upgrade-serverless-operator/regular_jobs_service_restore_retry_interval_procedure.adoc @@ -0,0 +1,10 @@ +// Regular Jobs service procedure for restoring the jobs retry interval. +// 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: + +After redeploying all workflows you must restore the Job Service retry interval by following these steps: + +. Remove the environment variable `KOGITO_JOBS_SERVICE_MAXINTERVALLIMITTORETRYMILLIS` added in <>, or restore it to the previously configured value in cases where you have override the default value. +. Make sure to keep all existing fields in your `SonataFlowPlatform` (CR) unchanged. +. Reapply the `SonataFlowPlatform` (CR). When reapplied, the Jobs Service deployment will be updated and rolled out. diff --git a/modules/serverless-logic/pages/cloud/operator/upgrade-serverless-operator/upgrade_1_37_1_to_1_37_2.adoc b/modules/serverless-logic/pages/cloud/operator/upgrade-serverless-operator/upgrade_1_37_1_to_1_37_2.adoc index 70b7a8a1..8ea3ae95 100644 --- a/modules/serverless-logic/pages/cloud/operator/upgrade-serverless-operator/upgrade_1_37_1_to_1_37_2.adoc +++ b/modules/serverless-logic/pages/cloud/operator/upgrade-serverless-operator/upgrade_1_37_1_to_1_37_2.adoc @@ -46,34 +46,7 @@ Interested parties might automate the procedure according to their convenience o [#config_jobs_service_retry_interval] ==== Increase the Jobs Service retry interval -During system upgrades or migrations, job executions may temporarily fail due to transitional states (e.g., partial availability of workflows being migrated). -To prevent jobs from being prematurely discarded during this process, you must increase the retry interval before starting the upgrade. -This ensures that potential failing jobs are retained in the system while the upgrade is in progress, and have sufficient time to be retried successfully once the system stabilizes. - -To increase the retry interval you must: - -. Add the environment variable `KOGITO_JOBS_SERVICE_MAXINTERVALLIMITTORETRYMILLIS` with a relaxed configuration to the `jobService.podTemplate.container` in your `SonataFlowPlatform` (CR). -. Make sure to keep all existing fields in your `SonataFlowPlatform` (CR) unchanged. -. Reapply the `SonataFlowPlatform` (CR). When reapplied, the Jobs Service deployment will be updated and rolled out. - -[source,yaml] ----- -apiVersion: sonataflow.org/v1alpha08 -kind: SonataFlowPlatform -metadata: - name: sonataflow-platform-example - namespace: example-namespace -spec: -# all the fields in your SonataFlowPlatform must be preserved. - services - jobService: - container: - env: - - name: KOGITO_JOBS_SERVICE_MAXINTERVALLIMITTORETRYMILLIS - # e.g. retry period of 4 hs. - value: 14400000 ----- - +include::../../../_common-content/cloud/operator/upgrade-serverless-operator/regular_jobs_service_increase_retry_interval_procedure.adoc[] [#workflows_dev_profile] ==== Workflows with the `dev` profile @@ -154,10 +127,6 @@ the Data Index or the Jobs Service, you can verify that a the `sonataflow-db-mig [#restore_jobs_service_retry_interval] ==== Restore the Jobs Service retry interval -After redeploying all workflows you must restore the Job Service retry interval by following these steps: - -. Remove the environment variable `KOGITO_JOBS_SERVICE_MAXINTERVALLIMITTORETRYMILLIS` added in <>, or restore it to the previously configured value in cases where you have override the default value. -. Make sure to keep all existing fields in your `SonataFlowPlatform` (CR) unchanged. -. Reapply the `SonataFlowPlatform` (CR). When reapplied, the Jobs Service deployment will be updated and rolled out. +include::../../../_common-content/cloud/operator/upgrade-serverless-operator/regular_jobs_service_restore_retry_interval_procedure.adoc[] include::../../../../pages/_common-content/report-issue.adoc[]