MCM-10 — Upgrade an MCM Instance via Nexus

← Back to MCM Nexus overview

As a Customer User,
I want to trigger an upgrade from within my deployed MCM Instance's own web UI, and choose between a same-line patch and a newer version if both are available,
so that I don't have to run any separate manual commands, and I'm never silently jumped to a new version when all I wanted was a hotfix for the version I'm already running.

Acceptance Criteria

• The upgrade action lives inside the deployed MCM Instance's own web UI — it is not a customer-run CLI command.
• Clicking the upgrade action causes the instance's backend, authenticated as its MCM App User, to ask Nexus what's available for its licensed role/plan, relative to its own currently-installed version.
• Nexus's answer can include up to two independent, separately-offered options (see MCM-33 — Release Catalog and Version Approval for how release lines and approval work):
  • A recommended update — the latest APPROVED version within the instance's own release line (e.g. an instance on 1.1.0 is offered the 1.1.1 hotfix). This is the safe, in-line patch path.
  • A new version available — the latest APPROVED version in a newer release line (e.g. 1.2.0), offered as a separate, explicit choice. Taking the in-line patch never silently carries the customer onto a newer line, and vice versa — each is applied only if the customer picks it.
  • Either, both, or neither may be present, depending on what the Nexus Admin currently has APPROVED.
• If the instance's currently-installed version has since been marked DEPRECATED, the UI shows an informational notice that it's deprecated and recommends upgrading — this never blocks usage, it only nudges.
• Whichever option the customer picks, the instance fetches that specific upgrade package (image tarballs / config deltas) through Nexus and applies it using the same underlying mechanics mcm-devops's upgrade.sh already performs (including its --skip-images fast path where images are already present locally) — only the trigger point and the choice of target version are new; the apply mechanics are unchanged.
• An instance whose license is not ACTIVE cannot fetch upgrade packages, even if it has valid MCM App credentials — expired/deactivated subscriptions block upgrades, not just new installs.
• Upgrade check-ins and applied-version results are recorded per Organization, visible to the Nexus Admin alongside the subscription check-in data from MCM-08.
• A failed upgrade attempt does not leave the instance's Nexus-reported version out of sync with what is actually running — the instance only reports success after the upgrade genuinely completes.

---

Technical Design

The customer-visible action is a single click inside the deployed MCM Instance's own web UI (outside mcm-nexus); everything else happens behind the scenes as the instance's backend, authenticated as its MCM App User, calls two new mcm-nexus/backend endpoints — GET /api/mcm-app/upgrade/latest and GET /api/mcm-app/upgrade/package?version=x.y.z, both HTTP Basic Auth, both requiring an ACTIVE license. GET /api/mcm-app/upgrade/latest now resolves two independent queries against MCM-33's Release table — the latest APPROVED version in the instance's own majorMinorLine, and the latest APPROVED version in any strictly newer majorMinorLine — plus whether the instance's own currently-installed version is DEPRECATED, instead of a single global "latest." GET /api/mcm-app/upgrade/package now takes the specific version the customer picked, rather than implicitly always fetching "the latest." Both endpoints fetch the real upgrade artefact from the Artifact Registry using the Nexus-Admin-configured credentials from MCM-30 — Registry Configuration for Artifact Delivery, the same connection MCM-09 uses — one definition of "what version exists and is approved," not a separate one for install versus upgrade. The instance applies the fetched package using the same mechanics mcm-devops's upgrade.sh already performs (including its --skip-images fast path), and only reports success to Nexus once the upgrade has genuinely completed, so the reported version never gets ahead of reality.

---

UI / Frontend Changes

• Deployed MCM Instance's own web UI (outside mcm-nexus): new "Upgrade" area showing up to two distinct actions when applicable — "Apply Patch <x.y.z+1>" (recommended, same line) and "Upgrade to <newer version>" (a different line) — each independently triggerable, with a loading state while in flight.
• Deprecated-version notice: an informational banner if the currently-installed version is DEPRECATED, recommending an upgrade — never blocking.
• Success/no-op state: if neither a patch nor a newer version is offered, the UI communicates the instance is already up to date rather than showing empty upgrade actions.
• Error state: if the license is not ACTIVE, the upgrade action is disabled or shows why it is blocked.
• Error state: if the upgrade package fetch succeeds but application fails, the UI reflects that the upgrade did not complete (no false "upgraded" success message).
• Nexus Admin console ((admin)/admin/customers, see MCM Instance Subscription Validation): surfaces upgrade check-ins and applied-version results alongside subscription check-in data.