Design
Last modified 17 Aug 2023 20:58 +02:00
Since 4.8
This functionality is available since version 4.8.
Table of Contents
This page is a work in progress.

Introduction

This document contains description of design for upgrade features and related components.

Terms definition

  1. Old midpoint - Version of midPoint currently running.

  2. New midPoint - version of midPoint to which we plan to upgrade.

Upgrade steps

Upgrade process will have two main phases. First phase can be started while old midPoint is still running. Second phase will be started after midPoint was shut down and is ready for main upgrade.

First phase:

  1. Verify installation details

    1. Version checks for midPoint and database schema

  2. Verify objects in midPoint

    1. CSV output with warnings, schema issues and changes that will be done during upgrade

    2. XML dump of raw schema changes

  3. Review CSV (and optionally XML), by administrator preparing upgrade

  4. Update objects that can be changed before midPoint is upgraded (db schema, executable)

Notes regarding first phase

  • Schema will be updated in last 4.4.* and 4.7.* to be able to handle schema changes and parsing

Second phase:

  1. Check current midPoint status, whether it’s down

  2. Download distribution

  3. Upgrade database schema

    1. MidPoint internal repository

    2. Audit database

  4. Upgrade midpoint.home directory

  5. Upgrade objects in midPoint repository (more details in "verification and upgrade of midpoint objects")

    1. Initial objects

    2. All other based on CSV from first phase (if it’s available)

      1. There will be option to skip object update

Notes regarding second phase

  • Tasks doesn’t have to be suspended before starting second phase, because midPoint will not run during this phase - only repository will be initialized.

  • Resources using bundled connectors (CSV, DBTable, LDAP related) should be upgraded to use new connector version

    • Old connector xml should be removed (the one which will not have JAR library available after upgrade)

  • Audit DB schema and data upgrade is expected to be schema compatible, fast. No data upgrade expected.

    • Potential option is via renaming existing tables and creating correct new ones

Upgrade steps

Verification

TODO

CSV export columns

  • Object OID

  • Object name

  • Object type

  • Schema change identifier: Unique identifier of type of schema change

  • Item Validation status

  • Item path for validation item

  • Message

  • Upgrade phase: When change can be applied during upgrade

    • First - for changes that can be done during first phase of upgrade (before midPoint is shutdown).

    • Second - changed done after DB schema was upgraded (after midPoint was shutdown)

  • Upgrade type: Type of change that will be done by upgrade process.

    • Seamless - for 1:1 changes, without functional changes.

    • Preview - change should be reviewed by admin. For changes that are not exactly 1:1 in terms of

    • Manual - manual update by admin is needed.

  • Upgrade priority: Whether object update is a precondition for upgrade.

    • Necessary - midPoint will not start without this change.

    • Optional - Change can be ignored and resolved (executed) later.

  • Upgrade status: Yes/no column. Default value (or empty) is yes.

    • yes - object will be upgraded if possible.

    • no - object processing will be skipped.

XML delta dump

ZIP file will be created containing one or more XML files. Each file will contain object delta XML for 1000 objects.

Distribution download

TODO

Database schema upgrade

TODO

Upgrade of midpoint.home directory

TODO

Objects upgrade

TODO

Upgrade of initial objets

TODO

Objects upgrade

TODO

Upgrade of resources referencing bundled connectors

TODO

Ninja notes

  • Switch to Spring shell & batch seems to be overkill

    • JCommander + JANSI is good enough

Opened Questions

  • Currently, only warning to log - if schema migration exist, else exception is thrown.

  • Objects upgrade in database

    • What if we want to dry run objects upgrade to review changes?

      • I’d verify objects and execute upgrade on them but then store delta in h2 table (as report from tool). How to dump delta otherwise for many objects?

  • How can upgrade tool upload objects (with recompute) if we’re only on repo layer?

  • How to wrap up upgrade after new version was started

    • What if upgrade process needs to recompute something?

  • Initial objects

    • diff previous version with next (how to display changes)

    • diff next version with current state of repository (how to display delta)

  • Upgrade of objects in projects (midPoint studio), since objects in midPoint will be upgraded by CMD tool

Next steps

  • Qualify schema changes, see Schema cleanup

  • Introduce XSD annotations that will describe upgrade priority

    • Optionally this can be done directly in implementation classes created for each schema change

  • Ninja code cleanup

Was this page helpful?
YES NO
Thanks for your feedback