Skip to content

Commit

Permalink
MDL-65471 upgrade: framework to reduce maintenance mode
Browse files Browse the repository at this point in the history
  • Loading branch information
@Peterburnett
Peterburnett committed Apr 6, 2023
1 parent fba0658 commit 027c770
Show file tree
Hide file tree
Showing 8 changed files with 701 additions and 356 deletions.
142 changes: 114 additions & 28 deletions admin/cli/upgrade.php
View file
Expand Up @@ -48,12 +48,16 @@
$lang = isset($SESSION->lang) ? $SESSION->lang : $CFG->lang;
list($options, $unrecognized) = cli_get_params(
array(
'non-interactive' => false,
'allow-unstable' => false,
'help' => false,
'lang' => $lang,
'verbose-settings' => false,
'is-pending' => false,
'allow-unstable' => false,
'help' => false,
'is-maintenance-required' => false,
'is-pending' => false,
'lang' => $lang,
'maintenance' => true,
'non-interactive' => false,
'set-ui-upgrade-lock' => false,
'unset-ui-upgrade-lock' => false,
'verbose-settings' => false,
),
array(
'h' => 'help'
Expand All @@ -79,19 +83,35 @@
Site defaults may be changed via local/defaults.php.
Options:
--non-interactive No interactive questions or confirmations
--allow-unstable Upgrade even if the version is not marked as stable yet,
required in non-interactive mode.
--lang=CODE Set preferred language for CLI output. Defaults to the
site language if not set. Defaults to 'en' if the lang
parameter is invalid or if the language pack is not
installed.
--verbose-settings Show new settings values. By default only the name of
new core or plugin settings are displayed. This option
outputs the new values as well as the setting name.
--is-pending If an upgrade is needed it exits with an error code of
2 so it distinct from other types of errors.
-h, --help Print out this help
--allow-unstable Upgrade even if the version is not marked as stable yet,
required in non-interactive mode.
-h, --help Print out this help.
--is-maintenance-required Returns exit code 2 if the upgrade requires maintenance mode.
Returns exit code 3 if no maintenance is required for the upgrade.
--is-pending Exit with error code 2 if an upgrade is required.
--lang=CODE Set preferred language for CLI output. Defaults to the
site language if not set. Defaults to 'en' if the lang
parameter is invalid or if the language pack is not
installed.
--maintenance Sets whether this upgrade will use maintenance mode.
If not possible, the upgrade will not happen and the script will exit.
WARNING: Caches (except theme) will be STALE and MUST be purged after upgrading.
DO NOT USE if the upgrade contains known breaking changes to the way data
and the database interact.
RECOMMENDED for lightweight deployments, to allow for a graceful purge and
rebuild of the cache.
--non-interactive No interactive questions or confirmations.
--set-ui-upgrade-lock Sets the upgrade to CLI only and unable to be triggered from the frontend.
If called with --maintenance=false, the lock WILL NOT be released when the
upgrade finishes, and MUST be manually removed.
If called with --is-maintenance-required before an upgrade,
The lock WILL be released when the upgrade finishes.
--unset-ui-upgrade-lock Removes the frontend upgrade lock, if the lock exists.
Useful when an error during the upgrade leaves the upgrade locked,
or there is need to control the time where the unlock happens.
--verbose-settings Show new settings values. By default only the name of
new core or plugin settings are displayed. This option
outputs the new values as well as the setting name.
Example:
\$sudo -u www-data /usr/bin/php admin/cli/upgrade.php
Expand All @@ -115,12 +135,58 @@
$oldversion = "$CFG->release ($CFG->version)";
$newversion = "$release ($version)";

if (!moodle_needs_upgrading()) {
if ($options['unset-ui-upgrade-lock']) {
// Unconditionally unset this config if requested.
set_config('outagelessupgrade', false);
cli_writeln(get_string('cliupgradeunsetlock', 'admin'));
}

$allhash = core_component::get_all_component_hash();

// Initialise allcomponent hash if not set. It will be correctly set after upgrade.
$CFG->allcomponenthash = $CFG->allcomponenthash ?? '';
if (!$options['maintenance']) {
if ($allhash !== $CFG->allcomponenthash) {
// Throw an error here, we can't proceed, this needs to set maintenance.
cli_error(get_string('cliupgrademaintenancerequired', 'core_admin'), 2);
}

// Set a constant to stop any upgrade var from being set during processing.
// This protects against the upgrade setting timeouts and maintenance during the upgrade.
define('CLI_UPGRADE_RUNNING', true);

// This database control is the control to block the GUI from doing upgrade related actions.
set_config('outagelessupgrade', true);
}

// We should ignore all upgrade locks here.
if (!moodle_needs_upgrading(false)) {
cli_error(get_string('cliupgradenoneed', 'core_admin', $newversion), 0);
}

if ($options['is-pending']) {
cli_error(get_string('cliupgradepending', 'core_admin'), 2);
// Handle exit based options for outputting upgrade state.
if ($options['is-pending'] || $options['is-maintenance-required']) {
// If we aren't doing a maintenance check, plain pending check.
if (!$options['is-maintenance-required']) {
cli_error(get_string('cliupgradepending', 'core_admin'), 2);
}

// Can we do this safely with no maintenance/outage? Detect if there is a schema or other application state change.
if ($allhash !== $CFG->allcomponenthash) {
// State change here, we need to do this in maintenance.
cli_writeln(get_string('cliupgradepending', 'core_admin'));
cli_error(get_string('cliupgrademaintenancerequired', 'core_admin'), 2);
}

// If requested, we should always set the upgrade lock here, so this cannot be run from frontend.
if ($options['set-ui-upgrade-lock']) {
set_config('outagelessupgrade', true);
cli_writeln(get_string('cliupgradesetlock', 'admin'));
}

// We can do an upgrade without maintenance!
cli_writeln(get_string('cliupgradepending', 'core_admin'));
cli_error(get_string('cliupgrademaintenancenotrequired', 'core_admin'), 3);
}

// Test environment first.
Expand Down Expand Up @@ -187,12 +253,18 @@
}

if ($version > $CFG->version) {
// We purge all of MUC's caches here.
// Caches are disabled for upgrade by CACHE_DISABLE_ALL so we must set the first arg to true.
// This ensures a real config object is loaded and the stores will be purged.
// This is the only way we can purge custom caches such as memcache or APC.
// Note: all other calls to caches will still used the disabled API.
cache_helper::purge_all(true);

// Only purge caches if this is a plain upgrade.
// In the case of a no-outage upgrade, we will gracefully roll caches after upgrade.
if ($options['maintenance']) {
// We purge all of MUC's caches here.
// Caches are disabled for upgrade by CACHE_DISABLE_ALL so we must set the first arg to true.
// This ensures a real config object is loaded and the stores will be purged.
// This is the only way we can purge custom caches such as memcache or APC.
// Note: all other calls to caches will still used the disabled API.
cache_helper::purge_all(true);
}

upgrade_core($version, true);
}
set_config('release', $release);
Expand Down Expand Up @@ -230,4 +302,18 @@
upgrade_themes();

echo get_string('cliupgradefinished', 'admin', $a)."\n";

if (!$options['maintenance']) {
cli_writeln(get_string('cliupgradecompletenomaintenanceupgrade', 'admin'));

// Here we check if upgrade lock has not been specifically set during this upgrade run.
// This supports wider server orchestration actions happening, which should call with no-maintenance AND set-ui-upgrade-lock,
// such as a new docker container deployment, of which the moodle upgrade is only a component.
if (!$options['set-ui-upgrade-lock']) {
// In this case we should release the lock now, as the upgrade is finished.
// We weren't told to keep the lock with set-ui-upgrade-lock, so release.
set_config('outagelessupgrade', false);
}
}

exit(0); // 0 means success

0 comments on commit 027c770

Please sign in to comment.