[FOLIO-464] Design and implement module upgrade procedure Created: 07/Feb/17  Updated: 11/Oct/19  Resolved: 19/Apr/17

Status: Closed
Project: FOLIO
Components: None
Affects versions: None
Fix versions: None

Type: Umbrella Priority: P2
Reporter: Jakub Skoczen Assignee: Adam Dickmeiss
Resolution: Done Votes: 0
Labels: sprint8
Remaining Estimate: Not Specified
Time Spent: 1 day, 1 hour
Original estimate: Not Specified

Issue links:
Relates
relates to OKAPI-232 Initialize modules Closed
relates to OKAPI-525 POST /install return 500 when enablin... Closed
relates to FOLIO-406 Design module life cycle Closed
relates to FOLIO-574 ModuleDescriptor Implementation Version Closed
relates to OKAPI-254 upgrade module for tenant facility Closed
relates to OKAPI-262 POST moduleInfo.schema body for /_/te... Closed
relates to OKAPI-263 Use POST rather than PUT for module u... Closed
relates to UXPROD-1815 support for upgrading schemas without... Closed
relates to UXPROD-2120 support for upgrading schemas without... Closed
relates to OKAPI-252 Okapi not to call tenant DELETE on di... Closed
relates to OKAPI-350 upgrade all modules in an Okapi instance Closed
Sprint:

 Description   

We need to be able to handle module upgrades (from an older to a newer version, including major/breaking version changes) in a safe and reliable fashion, This includes all the logic around starting a new isolated instance, migrating data over (handling rollbacks in error conditions), switching over selected tenant to the new version to run tests, then migrating the rest of tenant.



 Comments   
Comment by Heikki Levanto [ 07/Feb/17 ]

I have speculated about upgrades in FOLIO-406 Closed , in my usual rambling style. MIght be worth checking...

Comment by Jakub Skoczen [ 10/Feb/17 ]

Guys, to summarize what has been discussed on the call today:

1. Tenant POST (init call) will be extended to support upgrades through a new parameter/JSON value (TBD), if attached the module will attempt migration of the schema, with the following outcomes:

  • 204 – nothing happened, schema already existed and was good enough
  • 201 – new schema was created (we could also use 200 if it doesn't make sense to differentiate from the one below)
  • 200 – schema was upgraded fine
  • 400 – the module doesn't know how to create or upgrade the schema
  • 500 – create/upgrade procedure failed, the module should always attempt a rollback to leave the storage in in the same condition

2. Tenant DELETE means: purge all tenant data for this module, Okapi will NOT make this call when disassociating the module from a tenant.

3. We will consider (discuss/design issue) whether Tenant dissociate call is needed/useful.

Comment by Adam Dickmeiss [ 10/Feb/17 ]

First proposal - as discussed is to leave the /_/tenant call as is and use it for install and upgrades.. For upgrades Okapi will disassociate a tenant for module X1 and associate it with module X2 in one transaction.. We'll design a way to extract and compare versions from a module ID. The version(X2) > version(X1) > 0 for upgrades.. And version(X2)<version(X1) for downgrades.

For install only X2 is passed as parameter version_to=X2 as parameter to /_/tenant.
For upgrade version_to and version_from are passed to to /_/tenant call.

We propose to use PUT on the existing ("from module) tenant module selection and provide the new selection in the Body.. That's is:

Associate X1 with tenantID first time:

POST /_/proxy/tenants/tenantID/modules
{ "id" : "X1" }

returns location of testlib + X1 binding - that is used in next call below.

Disassociate X1 and associate with X2:

POST /_/proxy/tenants/tenantID/modules/X1
{ "id" : "X2"}

returns location of testlib + X2 binding - that may be used to upgrade again.

Comment by Adam Dickmeiss [ 13/Feb/17 ]

Implemented and merged with master now (from okapi-254 branch)

Comment by Adam Dickmeiss [ 20/Feb/17 ]

Changing method from PUT to POST in upgrade.. OKAPI-263 Closed .

Comment by Adam Dickmeiss [ 19/Apr/17 ]

The Tenant POST call is called for a running module before any proxy requests are sent to it . It is the the point where a module should expect whether it needs to either initialize, upgrade, leave data intact (unmodified), reject. Since the Tenant POST call can be called after Okapi has been shut down or other reason the upgrade should always be a consideration if there is existing data. Should the upgrade fail, the module should roll back to the previous state.. If that requires some kind of cloning of data to ensure data integrity that is a possibility. The module has know knowledge of its own implementation and what it expects - schema wise and other.. and it should be able to inspect existing data reliably WRT what the existing schema is.

The upgrade tenant call mentioned earlier is an on-the-fly way to move a tenant from using one module (version) to another. It is not a special case. It should not be considered diffferent from the originanl POST call. In both cases, the module should consult existing data - or initialize if none exist.

Comment by Adam Dickmeiss [ 20/Jun/17 ]

As mentioned we need to be able to get an implementation version of a module from the MD so we can sort them! See FOLIO-574 Closed

Generated at Thu Feb 08 23:05:59 UTC 2024 using Jira 1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d.