Am I impacted ?

This section describes the actions to take to migrate from one version of Optimization Server to the other. You are concerned by this guide if:

  • You develop an application client of Optimization Server by calling the Master API through the Java library (to start a job for instance)

  • You develop your own Java worker by using the Optimization Server worker library

  • You develop your own Python worker by using the Optimization Server worker bridge.

  • You deploy Optimization Server by using the provided Helm charts.

If Optimization Server provides Backward compatible, there is no mandatory action to take.

If Optimization Server provides backward compatibility but introduces Deprecations, you may take some actions.

If Optimization Server doesn't provide backward compatibility, it introduces Break changes , and you must take some actions.

For the development of an application (either client of Optimization Server or worker) these actions may be:

  • The upgrade of the version of the library

  • Code adjustment

For the deployment of Optimization Server by using the Helm charts, this action may be:

  • Code adjustment

Development of applications

What is referred next as a 'library' can be either:

Backward compatibility

Your application embeds one of these libraries, the new version of Optimization Server is Backward compatible only if your application doesn't need to upgrade the version of the library to remain fully functional.

For instance your application embeds the Master API library from Optimization Server 3.2.1, you upgrade Optimization Server to 3.2.2, your application remains functional without upgrading the version of the Master API library, Optimization Server 3.2.2 is then said backward compatible regarding the Master API library.

In that case, there is no action to take at all.

Deprecations

If Optimization Server is backward compatible but introduces Deprecations, it means some aspects (code, properties) of the library has been reworked in the new version.

For instance Optimization Server 3.1.0 has renamed the property scripted-tasks into shell-tasks in the worker.yml.

Your application should include some adjustments accordingly.

'Should' means it's not mandatory, but it's highly recommended since deprecations are meant to become break changes when Optimization Server releases a new major version.

The actions to take are then:

  • The upgrade of the version of the library

  • Code adjustment

Break changes with no code adjustment.

If Optimization Server is NOT backward compatible, your application needs to upgrade the library to the new version of Optimization Server. If this new library has kept the same API signature than the former version, even though it is a Break changes, no code adjustment is required, and the action to take is then:

  • The upgrade of the version of the library

Break changes with code adjustment.

If Optimization Server is NOT backward compatible, your application needs to upgrade the library to the new version of Optimization Server. If this new library has changed the API signature, The actions to take to resolve the Break changes are then:

  • The upgrade of the version of the library

  • Code adjustment

Deployment of Optimization Server

If you deployed Optimization Server by using the Helm charts, you had to write your own 'values.yaml' files to feed as input to the charts.

Backward compatibility

The new version of Optimization Server is Backward compatible if the 'values.yaml' files you wrote can be re-used with no change.

In that case, there is no action to take at all.

Deprecations

If Optimization Server is backward compatible but introduces Deprecations, some properties should be adjusted in the values.yaml files.

For instance Optimization Server 3.3.0 has renamed the property MASTER_URL into OPTIMSERVER_URL in the worker library.

The action to take is then:

  • Code adjustment

Break changes

If Optimization Server is NOT backward compatible, then you have to adjust your values.yaml files to resolve the Break changes.

The action to take is then:

  • Code adjustment

The migration tool

Optimization Server provides a Python script that helps to migrate the YAML configuration files.

For the development of a worker application these files are:

  • worker.yaml

  • application.yaml

For an Optimization Server deployment there files are:

  • values.yaml

The script is installed with:

pip3 install --extra-index-url "https://nexus.decisionbrain.cloud/repository/dbos-pypi/simple" optimserver-migration-tools==4.4.0

It does most of the work for you (remove obsolete values, move to the new sections), but it must be reviewed

Usage to upgrade the YAML files of a worker

You can call it with the following arguments:

// Might be 'python' instead of 'python3' on Windows systems
python3 -m optimserver.workerapp.migration.migrate_workerapp_config [-h] --src --dst --type --input INPUT --output OUTPUT
  -h, --help                            show this help message and exit
  --src                                 The DBOS version the input file complies with
  --dst                                 The DBOS version the output file must comply with
  --type {WORKER_YAML, APPLICATION_YAML} The type of configuration to update: worker.yaml or application.yaml
  --input INPUT                         The input file to migrate, worker.yaml or application.yaml
  --output OUTPUT                       The output file to write the result to

Usage to upgrade the values.yaml files of a Helm chart

You can call it with the following arguments:

// Might be 'python' instead of 'python3' on Windows systems
python3 -m optimserver.helm.migration.migrate_helm_values [-h] --src --dst --chart --input INPUT --output OUTPUT
  -h, --help                                  show this help message and exit
  --src                                       The DBOS version the input file complies with
  --dst                                       The DBOS version the output file must comply with
  --chart {DBOS_INFRA, DBOS_APP, DBOS_WORKER} The chart the values file is applied to
  --input INPUT                               The DBOS Helm chart values input file to migrate
  --output OUTPUT                             The DBOS Helm chart values output file to write the result to