Chapter 10. Managing upgrades

Procedure

1. Ensure you have a backup of all necessary Kubernetes resources, including SonataFlow custom resource definitions (CRDs), ConfigMaps, or any other related custom configurations.

2. Delete the workflow by executing the following command:

   $ oc delete -f <my-workflow.yaml> -n <target_namespace>

Procedure

1. If you are using persistence, back up the workflow database and ensure the backup includes both database objects and table data.
2. Ensure you have a backup of all necessary Kubernetes resources, including SonataFlow CRDs, ConfigMaps, or any other related custom configurations.

3. Delete the workflow by executing the following command:

   $ oc delete -f <my-workflow.yaml> -n <target_namespace>

4. If you are using persistence, you must execute the following database migration script:

   ALTER TABLE flyway_schema_history
       RENAME CONSTRAINT flyway_schema_history_pk TO kie_flyway_history_runtime_persistence_pk;
   
   ALTER INDEX flyway_schema_history_s_idx
     RENAME TO kie_flyway_history_runtime_persistence_s_idx;
   
   ALTER TABLE flyway_schema_history RENAME TO kie_flyway_history_runtime_persistence;

Procedure

1. Modify the my-workflow.yaml CRD and scale down each workflow to zero before upgrading as shown in the following example:

   spec:
     podTemplate:
       replicas: 0

2. Apply the updated CRD by running the following command:

   $ oc apply -f <my-workflow.yaml> -n <target_namespace>

3. (Optional) Scale the workflow to 0 by running the following command:

   $ oc patch sonataflow <my-workflow> -n <target_namespace> --type=merge -p '{"spec": {"podTemplate": {"replicas": 0}}}'

Procedure

1. Verify the new ReplicaSet exists by listing all ReplicaSets by running the following command:

   $ oc get replicasets -n <target_namespace> -o custom-columns=Name:metadata.name,Image:spec.template.spec.containers[*].image

2. Identify the old Data Index ReplicaSet (with version 1.34.0) and delete it:

   $ oc delete replicaset <old_replicaset_name> -n <target_namespace>

Procedure

1. Delete the old Jobs Service deployment by running the following command:

   $ oc delete deployment <jobs-service-deployment-name> -n <target_namespace>

   This will trigger automatic cleanup of the older Pods and ReplicaSets and initiate a fresh deployment using version 1.35.0.

Procedure

1. Ensure all required resources are restored, including SonataFlow CRDs, ConfigMaps, or any other related custom configurations.

2. Redeploy the workflow by running the following command:

   $ oc apply -f <my-workflow.yaml> -n <target_namespace>

Procedure

1. If the workflow uses persistence, add the following property to the ConfigMap associated with the workflow:

   apiVersion: v1
   kind: ConfigMap
   metadata:
     labels:
       app: my-workflow
     name: my-workflow-props
   data:
     application.properties: |
       kie.flyway.enabled=true

2. Ensure all required resources are recreated, including SonataFlow CRDs, ConfigMaps, or any other related custom configurations.

3. Redeploy the workflow by running the following command:

   $ oc apply -f <my-workflow.yaml> -n <target_namespace>

Procedure

1. Modify the my-workflow.yaml CRD and scale up each workflow to one before upgrading as shown in the following example:

   spec:
     podTemplate:
       replicas: 1

2. Apply the updated CRD by running the following command:

   $ oc apply -f <my-workflow.yaml> -n <target_namespace>

3. (Optional) Scale the workflow back to 1 by running the following command:

   $ oc patch sonataflow <my-workflow> -n <target_namespace> --type=merge -p '{"spec": {"podTemplate": {"replicas": 1}}}'

Procedure

1. Check if all workflows and services are running by entering the following command:

   $ oc get pods -n <target_namespace>

   Ensure that all pods related to workflows, Data Index, and Jobs Service are in a Running or Completed state.

2. Verify that the OpenShift Serverless Logic Operator is running correctly by entering the following command:

   $ oc get clusterserviceversion logic-operator-rhel8.v1.35.0 -n openshift-serverless-logic

   Expected output

   NAME                           DISPLAY                               VERSION   REPLACES                       PHASE
   logic-operator-rhel8.v1.35.0   OpenShift Serverless Logic Operator   1.35.0    logic-operator-rhel8.v1.34.0   Succeeded

3. Check Operator logs for any errors by entering the following command:

   $ oc logs -l control-plane=sonataflow-operator -n openshift-serverless-logic

Procedure

1. Ensure you have a backup of all necessary Kubernetes resources, including SonataFlow custom resources (CRs), ConfigMap resources, or any other related custom configurations.

2. Delete the workflow by executing the following command:

   $ oc delete workflow <workflow_name> -n <target_namespace>

Procedure

1. If you are using persistence, back up the workflow database and ensure the backup includes both database objects and table data.
2. Ensure you have a backup of all necessary Kubernetes resources, including SonataFlow custom resources (CRs), ConfigMap resources, or any other related custom configurations.

3. Delete the workflow by executing the following command:

   $ oc delete workflow <workflow_name> -n <target_namespace>

Procedure

1. Modify the my-workflow.yaml custom resources (CR) and scale down each workflow to 0 before upgrading as shown in the following example:

   spec:
     podTemplate:
       replicas: 0
     # ...

2. Apply the updated my-workflow.yaml CR by running the following command:

   $ oc apply -f my-workflow.yaml -n <target_namespace>

3. Optional: Scale the workflow to 0 by running the following command:

   $ oc patch workflow <workflow_name> -n <target_namespace> --type=merge -p '{"spec": {"podTemplate": {"replicas": 0}}}'

Procedure

1. List all the triggers by running the following command:

   $ oc get triggers -n <target_namespace>

   Example output

   NAME                                                              BROKER              SUBSCRIBER_URI
   data-index-jobs-a25c8405-f740-47d2-a9a5-f80ccaec2955              example-broker      http://sonataflow-platform-data-index-service.<target_namespace>.svc.cluster.local/jobs
   data-index-process-definition-473e1ddbb3ca1d62768187eb80de99bca   example-broker      http://sonataflow-platform-data-index-service.<target_namespace>.svc.cluster.local/definitions
   data-index-process-error-a25c8405-f740-47d2-a9a5-f80ccaec2955     example-broker      http://sonataflow-platform-data-index-service.<target_namespace>.svc.cluster.local/processes
   data-index-process-instance-mul07f593476e8c14353a337590e0bfd5ae   example-broker      http://sonataflow-platform-data-index-service.<target_namespace>.svc.cluster.local/processes
   data-index-process-node-a25c8405-f740-47d2-a9a5-f80ccaec2955      example-broker      http://sonataflow-platform-data-index-service.<target_namespace>.svc.cluster.local/processes
   data-index-process-state-a25c8405-f740-47d2-a9a5-f80ccaec2955     example-broker      http://sonataflow-platform-data-index-service.<target_namespace>.svc.cluster.local/processes
   data-index-process-variable-487e9a6777fff650e60097c9e17111aea25   example-broker      http://sonataflow-platform-data-index-service.<target_namespace>.svc.cluster.local/processes
   
   jobs-service-create-job-a25c8405-f740-47d2-a9a5-f80ccaec2955      example-broker      http://sonataflow-platform-jobs-service.<target_namespace>.svc.cluster.local/v2/jobs/events
   jobs-service-delete-job-a25c8405-f740-47d2-a9a5-f80ccaec2955      example-broker      http://sonataflow-platform-jobs-service.<target_namespace>.svc.cluster.local/v2/jobs/events

2. Based on the generated example output, delete the old data-index-process-definition trigger by running the following command:

   $ oc delete trigger data-index-process-definition-473e1ddbb3ca1d62768187eb80de99bca -n <target_namespace>

   After deletion, a new trigger compatible with OpenShift Serverless Logic 1.36.0 is automatically created.

3. Optional: Identify the old ReplicaSet resource by running the following command:

   $ oc get replicasets -o custom-columns=Name:metadata.name,Image:spec.template.spec.containers[*].image -n <target_namespace>

   Example output

   Name                                                Image
   sonataflow-platform-data-index-service-1111111111   registry.redhat.io/openshift-serverless-1/logic-data-index-postgresql-rhel8:1.35.0
   
   sonataflow-platform-data-index-service-2222222222   registry.redhat.io/openshift-serverless-1/logic-data-index-postgresql-rhel8:1.36.0

4. Optional: Delete your old ReplicaSet resource by running the following command:

   $ oc delete replicaset <old_replicaset_name> -n <target_namespace>

   Example command based on the example output

   $ oc delete replicaset sonataflow-platform-data-index-service-1111111111 -n <target_namespace>

Procedure

1. Identify the old ReplicaSet resource by running the following command:

   $ oc get replicasets -o custom-columns=Name:metadata.name,Image:spec.template.spec.containers[*].image -n <target_namespace>

   Example output

   Name                                                Image
   sonataflow-platform-jobs-service-1111111111         registry.redhat.io/openshift-serverless-1/logic-jobs-service-postgresql-rhel8:1.35.0
   sonataflow-platform-jobs-service-2222222222         registry.redhat.io/openshift-serverless-1/logic-jobs-service-postgresql-rhel8:1.36.0

2. Delete your old ReplicaSet resource by running the following command:

   $ oc delete replicaset <old_replicaset_name> -n <target_namespace>

   Example command based on the example output

   $ oc delete replicaset sonataflow-platform-jobs-service-1111111111 -n <target_namespace>

Procedure

1. Ensure that all required Kubernetes resources, including the ConfigMap with the application.properties field, are restored before redeploying the workflow.

2. Redeploy the workflow by running the following command:

   $ oc apply -f <workflow_name> -n <target_namespace>

Procedure

1. Ensure that all required Kubernetes resources, including the ConfigMap with the application.properties field, are restored before redeploying the workflow.

2. Redeploy the workflow by running the following command:

   $ oc apply -f <workflow_name> -n <target_namespace>

Procedure

1. Modify the my-workflow.yaml custom resources (CR) and scale up each workflow to 1 as shown in the following example:

   spec:
     podTemplate:
       replicas: 1
     # ...

2. Apply the updated CR by running the following command:

   $ oc apply -f my-workflow.yaml -n <target_namespace>

3. Optional: Scale the workflow back to 1 by running the following command:

   $ oc patch workflow <workflow_name> -n <target_namespace> --type=merge -p '{"spec": {"podTemplate": {"replicas": 1}}}'

Procedure

1. Ensure you have a backup of all necessary Kubernetes resources, including SonataFlow custom resources (CRs), ConfigMap resources, or any other related custom configurations.

2. Delete the workflow by running the following command:

   $ oc delete -f <workflow.yaml> -n <target_namespace>

Procedure

1. If you are using persistence, back up the workflow database and ensure the backup includes both database objects and table data.
2. Ensure you have a backup of all necessary Kubernetes resources, including SonataFlow custom resources (CRs), ConfigMap resources, or any other related custom configurations.

3. Delete the workflow by running the following command:

   $ oc delete -f <workflow.yaml> -n <target_namespace>

Procedure

1. If you are using persistence, back up the workflow database and ensure the backup includes both database objects and table data.
2. Ensure you have a backup of all necessary Kubernetes resources, including SonataFlow custom resources (CRs), ConfigMap resources, or any other related custom configurations.

3. Delete the workflow by running the following command:

   $ oc delete -f <workflow.yaml> -n <target_namespace>

Procedure

1. Optional: Verify that a new ReplicaSet for the Data Index 1.37.0 version is created by running the following command:

   $ oc get replicasets -o custom-columns=Name:metadata.name,Image:spec.template.spec.containers[*].image -n <target_namespace>

   You will get an output similar to the following example:

   Name                                                Image
   sonataflow-platform-data-index-service-1111111111   registry.redhat.io/openshift-serverless-1/logic-data-index-postgresql-rhel8:1.36.0
   
   sonataflow-platform-data-index-service-2222222222   registry.redhat.io/openshift-serverless-1/logic-data-index-postgresql-rhel9:1.37.0

2. Optional: Delete your old ReplicaSet resource by running the following command:

   $ oc delete replicaset sonataflow-platform-data-index-service-1111111111 -n <target_namespace>

Procedure

1. Optional: Verify that a new ReplicaSet for the Job Service 1.37.0 version is created by running the following command:

   $ oc get replicasets -o custom-columns=Name:metadata.name,Image:spec.template.spec.containers[*].image -n <target_namespace>

   You will get an output similar to the following example:

   sonataflow-platform-jobs-service-1111111111    registry.redhat.io/openshift-serverless-1/logic-jobs-service-postgresql-rhel8:1.36.0
   
   sonataflow-platform-jobs-service-2222222222     registry.redhat.io/openshift-serverless-1/logic-jobs-service-postgresql-rhel9:1.37.0

2. Optional: Delete your old ReplicaSet running the Job Service 1.36.0 version by running the following command:

   $ oc delete replicaset sonataflow-platform-jobs-service-1111111111 -n <target_namespace>

Procedure

1. Ensure that all required Kubernetes resources are restored before redeploying the workflow. The resources also include the ConfigMap resource with the application.properties field.

2. Redeploy the workflow by running the following command:

   $ oc apply -f <workflow_yaml> -n <target_namespace>

Procedure

1. Ensure that all required Kubernetes resources, including the ConfigMap with the application.properties field, are created before redeploying the workflow.

2. Redeploy the workflow by running the following command:

   $ oc apply -f <workflow_yaml> -n <target_namespace>

Procedure

1. Rebuild the workflow image using the OpenShift Serverless Logic 1.37.0 serverless workflow builder image:

   registry.redhat.io/openshift-serverless-1/logic-swf-builder-rhel9:1.37.0

   Note

   When rebuilding the image, the OpenShift Serverless Logic Operator generates a workflow deployment with imagePullPolicy: IfNotPresent by default. This means that if an already deployed workflow <workflow_name> is redeployed with the same image name, even when that image was rebuilt, the previously downloaded image is reused.

2. Ensure that the new image is picked up by using one of the following alternatives:

   1. Use a new image tag and configure the workflow to use it.

      Use the current image tag by running the following command:

      quay.io/my-images/my-workflow:1.0

      Use the new image tag by running the following command:

      quay.io/my-images/my-workflow:1.0-1

      Update the workflow custom resource (CR) similar to the following example:

      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)

   2. Preserve the image name and configure the workflow with imagePullPolicy: Always as follows:

      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).

      Note

      When rebuilding the image and redeploying the workflow, do not change the workflow definition or any workflow-related assets. This includes the workflow name, version, and description.

3. Ensure that all Kubernetes resources required by the workflow are created. This includes any user-provided resources, such as a ConfigMap containing the application.properties file.

4. Redeploy the workflow by running the following command:

   $ oc apply -f <workflow_yaml> -n <target_namespace>

Procedure

1. Edit your SonataFlowPlatform custom resource (CR) and add the KOGITO_JOBS_SERVICE_MAXINTERVALLIMITTORETRYMILLIS environment variable to jobService.podTemplate.container:

   apiVersion: sonataflow.org/v1alpha08
   kind: SonataFlowPlatform
   metadata:
     name: sonataflow-platform-example
     namespace: example-namespace
   spec:
     # Preserve all existing fields in your SonataFlowPlatform
     services:
       jobService:
         podTemplate:
           container:
             env:
               - name: KOGITO_JOBS_SERVICE_MAXINTERVALLIMITTORETRYMILLIS
                 # Example: retry interval of 4 hours
                 value: "14400000"

2. Keep all existing fields in your SonataFlowPlatform CR unchanged.

3. Reapply the SonataFlowPlatform CR by running the following command:

   oc apply -f <sonataflowplatform.yaml>

4. Verify that the Jobs Service deployment updates successfully.

Procedure

1. Ensure you have a backup of all necessary Kubernetes resources, including SonataFlow custom resources (CRs), ConfigMap resources, or any other related custom configurations.

2. Delete the workflow by running the following command:

   $ oc delete -f <workflow.yaml> -n <target_namespace>

Procedure

1. If you are using persistence, back up the workflow database and ensure the backup includes both database objects and table data.
2. Ensure you have a backup of all necessary Kubernetes resources, including SonataFlow custom resources (CRs), ConfigMap resources, or any other related custom configurations.

3. Delete the workflow by running the following command:

   $ oc delete -f <workflow.yaml> -n <target_namespace>

Procedure

1. Rebuild the workflow image by using the OpenShift Serverless Logic 1.37.1 workflow builder image:

   $ registry.redhat.io/openshift-serverless-1/logic-swf-builder-rhel9:1.37.1

2. Reconfigure the workflow image by considering the following behavior:

   By default, OpenShift Serverless Logic generates a workflow Deployment with imagePullPolicy: IfNotPresent. If you redeploy a workflow with the same image name, the cluster reuses the earlier downloaded image, even if the image was rebuilt.

3. Do not change the workflow definition or any related metadata when rebuilding the image.

   Rebuilding the image creates a new image build, not a new workflow version. The workflow name, version, and description must remain unchanged.

4. Ensure that the cluster pulls the rebuilt image by using one of the following approaches:

   • Use a new image tag and update the workflow to reference the new tag (recommended).

     You get an output similar to the following example:

     current image: quay.io/my-images/my-workflow:1.0
     new image: quay.io/my-images/my-workflow:1.0-1
     
     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 imagePullPolicy: Always.

     You get an output similar to the following example:

     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
           # change only the image pull policy
           imagePullPolicy: Always
       flow:
         # do not change the workflow definition

5. If the workflow uses persistence, back up the workflow database. Ensure that the backup includes all database objects, not only table data.
6. Ensure that you have a copy of the corresponding SonataFlow custom resource (CR) and any related Kubernetes resources created for the workflow. For example, if the workflow uses custom property configurations, keep a copy of the user-provided ConfigMap that has the application.properties file.

7. Delete the workflow by running the following command:

   $ oc delete -f <my-workflow.yaml> -n <target_namespace>

Procedure

1. Restore all required Kubernetes resources before redeploying the workflow. These resources include the ConfigMap resource with the application.properties field.

2. Redeploy the workflow by running the following command:

   $ oc apply -f <workflow_yaml> -n <target_namespace>

Procedure

1. Restore all required Kubernetes resources before redeploying the workflow. These resources include the ConfigMap resource with the application.properties field.

2. Redeploy the workflow by running the following command:

   $ oc apply -f <workflow_yaml> -n <target_namespace>

Procedure

1. Restore all required Kubernetes resources before redeploying the workflow. These resources include the ConfigMap resource with the application.properties field.

2. Redeploy the workflow by running the following command:

   $ oc apply -f <workflow_yaml> -n <target_namespace>

Procedure

1. Edit your SonataFlowPlatform custom resource (CR) and update the KOGITO_JOBS_SERVICE_MAXINTERVALLIMITTORETRYMILLIS environment variable by one of the following steps:

   • Remove the environment variable if you added it only for the upgrade.
   • Restore the environment variable to its earlier value if you had overridden the default configuration.
2. Keep all existing fields in your SonataFlowPlatform CR unchanged.

3. Reapply the SonataFlowPlatform CR:

   oc apply -f <sonataflowplatform.yaml>

4. Verify that the Jobs Service deployment updates successfully.