-
Notifications
You must be signed in to change notification settings - Fork 516
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add Upgrading ACA-Py document #2200
Merged
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
ff5e61f
Add Upgrading ACA-Py document
swcurran 2093fce
Merge branch 'main' into add-upgrade-doc
swcurran efd02cd
Merge branch 'main' into add-upgrade-doc
swcurran 8832592
Updating the document to clarify, adding issue and PR links
swcurran d14c502
Merge branch 'main' into add-upgrade-doc
swcurran File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,98 @@ | ||
# Upgrading ACA-Py Data | ||
|
||
Some releases of ACA-Py may be improved by, or even require, an upgrade when | ||
moving to a new version. Such changes are documented in the [CHANGELOG.md], | ||
and those with ACA-Py deployments should take note of those upgrades. This | ||
document summarizes the upgrade system in ACA-Py. | ||
|
||
## Version Information and Automatic Upgrades | ||
|
||
The file [version.py] contains the current version of a running instance of | ||
ACA-Py. In addition, a record is made in the ACA-Py secure storage (database) | ||
about the "most recently upgraded" version. When deploying a new version of | ||
ACA-Py, the [version.py] value will be higher than the version in | ||
secure storage. When that happens, an upgrade is executed, and on successful | ||
completion, the version is updated in secure storage to match what is | ||
in [version.py]. | ||
|
||
Upgrades are defined in the [Upgrade Definition YML file]. For a given | ||
version listed in the follow, the corresponding entry is what actions are | ||
required when upgrading from a previous version. If a version is not listed | ||
in the file, there is no upgrade defined for that version from its immediate | ||
predecessor version. | ||
|
||
Once an upgrade is identified as needed, the process is: | ||
|
||
- Collect (if any) the actions to be taken to get from the version recorded in | ||
secure storage to the current [version.py] | ||
- Execute the actions from oldest to newest. | ||
- If the same action is collected more than once (e.g., "Resave the | ||
Connection Records" is defined for two different versions), perform the action | ||
only once. | ||
- Store the current ACA-Py version (from [version.py]) in the secure storage | ||
database. | ||
|
||
## Forced Offline Upgrades | ||
|
||
In some cases, it may be necessary to do an offline upgrade, where ACA-Py is | ||
taken off line temporarily, the database upgraded explicitly, and then | ||
ACA-Py re-deployed as normal. As yet, we do not have any use cases for this, but | ||
those deploying ACA-Py should be aware of this possibility. For example, | ||
we may at some point need an upgrade that **MUST NOT** be executed by more | ||
than one ACA-Py instance. In that case, a "normal" upgrade could be dangerous | ||
for deployments on container orchestration platforms like Kubernetes. | ||
|
||
If the Maintainers of ACA-Py recognize a case where ACA-Py must be upgraded | ||
while offline, a new Upgrade feature will be added that will prevent the "auto | ||
upgrade" process from executing. See [Issue 2201] and [Pull Request 2204] for | ||
the status of that feature. | ||
|
||
[Issue 2201]: https://github.com/hyperledger/aries-cloudagent-python/issues/2201 | ||
[Pull Request 2204]: https://github.com/hyperledger/aries-cloudagent-python/pull/2204 | ||
|
||
Those deploying ACA-Py upgrades for production installations (forced offline or | ||
not) should check in each [CHANGELOG.md] release entry about what upgrades (if | ||
any) will be run when upgrading to that version, and consider how they want | ||
those upgrades to run in their ACA-Py installation. In most cases, simply | ||
deploying the new version should be OK. If the number of records to be upgraded | ||
is high (such as a "resave connections" upgrade to a deployment with many, many | ||
connections), you may want to do a test upgrade offline first, to see if there | ||
is likely to be a service disruption during the upgrade. Plan accordingly! | ||
|
||
## Exceptions | ||
|
||
There are a couple of upgrade exception conditions to consider, as outlined | ||
in the following sections. | ||
|
||
### No version in secure storage | ||
|
||
Versions prior to ACA-Py 0.8.1 did not automatically populate the secure storage | ||
"version" record. That only occurred if an upgrade was explicitly executed. As | ||
of ACA-Py 0.8.1, the version record is added immediately after the secure | ||
storage database is created. If you are upgrading to ACA-Py 0.8.1 or later, and | ||
there is no version record in the secure storage, ACA-Py will assume you are | ||
running version 0.7.5, and execute the upgrades from version 0.7.5 to the | ||
current version. The choice of 0.7.5 as the default is safe because the same | ||
upgrades will be run on any version of ACA-Py up to and including 0.7.5, as can | ||
be seen in the [Upgrade Definition YML file]. Thus, even if you are really | ||
upgrading from (for example) 0.6.2, the same upgrades are needed as from 0.7.5 | ||
to a post-0.8.1 version. | ||
|
||
### Forcing an upgrade | ||
|
||
If you need to force an upgrade from a given version of ACA-Py, a pair of | ||
configuration options can be used together. If you specify "`--from-version | ||
<ver>`" and "`--force-upgrade`", the `--from-version` version will override what | ||
is found (or not) in secure storage, and the upgrade will be from that version | ||
to the current one. For example, if you have "0.8.1" in your "secure storage" | ||
version, and you know that the upgrade for version 0.8.1 has not been executed, | ||
you can use the parameters `--from-version v0.7.5 --force-upgrade` to force the | ||
upgrade on next starting an ACA-Py instance. However, given the few upgrades | ||
defined prior to version 0.8.1, and the "[no version in secure | ||
storage](#no-version-in-secure-storage)" handling, it is unlikely this | ||
capability will ever be needed. We expect to deprecate and remove these | ||
options in future (post-0.8.1) ACA-Py versions. | ||
|
||
[CHANGELOG.md]: https://github.com/hyperledger/aries-cloudagent-python/blob/main/CHANGELOG.md | ||
[version.py]: https://github.com/hyperledger/aries-cloudagent-python/blob/main/aries_cloudagent/version.py | ||
[Upgrade Definition YML file]: https://github.com/hyperledger/aries-cloudagent-python/blob/main/aries_cloudagent/commands/default_version_upgrade_config.yml |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we should also mention:
There are 2 flavours of this explicit upgrade mechanism,
"critical"
and"warning"
. Withcritical
, it will stop the "auto upgrade" process, raise an exception and force users to do the upgrade offline first. Withwarning
, it will stop the "auto upgrade" process, log a warning but allows ACA-Py to startup normally. In this case, the version is not updated in secure storage and it will only update when doing the upgrade offline.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've referenced the docs. We'll update this once when the merge of the #2204 is done -- perhaps as part of that PR, even.