Upgrade Paths

The UpgradePathCalculationService manages the registration and calculation of upgrade paths between component versions. It uses BFS-based graph traversal to find all possible routes from a source version to a target version, ranking them by step count, risk level, downtime requirements, and estimated duration.

Register an Upgrade Path

Endpoint: POST /api/v1/registry/upgrade-paths

curl -X POST http://localhost:8084/api/v1/registry/upgrade-paths \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "fromVersion": { "id": "aaa-111" },
    "toVersion": { "id": "bbb-222" },
    "direct": true,
    "requiresDowntime": false,
    "estimatedDurationMinutes": 15,
    "riskLevel": "LOW",
    "preUpgradeSteps": "[\"Backup current configuration\", \"Verify disk space\"]",
    "upgradeSteps": "[\"Apply Helm chart update\", \"Wait for rolling restart\"]",
    "postUpgradeSteps": "[\"Run smoke tests\", \"Verify data integrity\"]",
    "rollbackSteps": "[\"Revert Helm chart\", \"Restore configuration backup\"]",
    "validationSteps": "[\"Check health endpoints\", \"Run integration tests\"]",
    "tested": true,
    "notes": "Backward-compatible minor upgrade"
  }'

When an upgrade path is registered, the service automatically determines the upgrade type (PATCH, MINOR, MAJOR) by comparing the semantic versions. If no risk level is specified, it defaults based on upgrade type: PATCH maps to LOW, MINOR to MEDIUM, MAJOR to HIGH.

UpgradePath Structure

Field	Type	Description
`id`	UUID	Path identifier
`componentId`	UUID	Component this path belongs to
`fromVersion`	ComponentVersion	Source version
`toVersion`	ComponentVersion	Target version
`upgradeType`	UpgradeType	Classification of the upgrade
`direct`	boolean	Whether this is a single-step path
`requiresDowntime`	boolean	Whether downtime is needed
`estimatedDurationMinutes`	Integer	Estimated upgrade duration
`riskLevel`	RiskLevel	Risk assessment
`preUpgradeSteps`	JSON	Steps to execute before upgrade
`upgradeSteps`	JSON	Core upgrade procedure steps
`postUpgradeSteps`	JSON	Steps to execute after upgrade
`rollbackSteps`	JSON	Procedure to roll back the upgrade
`validationSteps`	JSON	Steps to validate upgrade success
`migrationScripts`	JSON	Data migration scripts to run
`breakingChanges`	String	Description of breaking changes
`tested`	boolean	Whether this path has been tested
`testResults`	JSON	Results from path testing

Upgrade Types

Type	Description	Default Risk
`PATCH`	Bug fixes only, no API changes	LOW
`MINOR`	New features, backward compatible	MEDIUM
`MAJOR`	Breaking changes, API modifications	HIGH
`HOTFIX`	Critical security or bug fix	LOW

Risk Levels

Level	Description	Recommendation
`LOW`	Safe to upgrade, minimal risk	Can proceed with standard monitoring
`MEDIUM`	Some care needed, minor risks	Test in staging first
`HIGH`	Significant changes, potential issues	Full staging validation required
`CRITICAL`	Major breaking changes	Requires maintenance window and backup

Calculate Upgrade Paths

Endpoint: GET /api/v1/registry/upgrade-paths/calculate?fromVersionId=:fromId&toVersionId=:toId

Calculates all possible upgrade routes between two versions using breadth-first search. The algorithm traverses the graph of registered upgrade paths, building multi-step routes when no direct path exists.

The service returns up to 10 routes, sorted by preference:

Fewer steps (direct paths preferred)
Lower risk level
No downtime required
Shorter estimated duration

UpgradeRoute Structure

Field	Type	Description
`steps`	List	Ordered list of UpgradePath entries
`totalSteps`	int	Number of steps in the route
`totalDurationMinutes`	int	Sum of estimated durations across all steps
`requiresDowntime`	boolean	True if any step requires downtime
`maxRiskLevel`	RiskLevel	Highest risk level across all steps
`breakingChanges`	List	Aggregated breaking changes from all steps

Optimal Upgrade Path

Endpoint: GET /api/v1/registry/upgrade-paths/optimal?fromVersionId=:fromId&toVersionId=:toId

Returns the single best upgrade route based on the sorting criteria described above. This is a convenience endpoint that returns the first result from the full path calculation.

Upgrade to Latest

Endpoint: GET /api/v1/registry/versions/:versionId/upgrade-to-latest

Calculates the optimal upgrade path from the specified version to the latest version of the same component. Returns 404 if the specified version is already the latest.

Upgrade to Recommended

Endpoint: GET /api/v1/registry/versions/:versionId/upgrade-to-recommended

Calculates the optimal upgrade path from the specified version to the recommended version of the same component. Returns 404 if the specified version is already the recommended version or no recommended version is set.

Available Upgrade Targets

Endpoint: GET /api/v1/registry/versions/:versionId/upgrade-targets

Lists all stable versions that are newer than the specified version, along with metadata about the upgrade path to each target.

UpgradeTarget Structure

Field	Type	Description
`targetVersion`	ComponentVersion	The target version details
`hasDirectPath`	boolean	Whether a single-step path exists
`stepsRequired`	int	Number of steps needed (-1 if no path exists)
`isRecommended`	boolean	Whether this is the recommended version
`isLts`	boolean	Whether this is a long-term support version
`riskLevel`	RiskLevel	Risk level of the optimal path
`requiresDowntime`	boolean	Whether the optimal path requires downtime

Targets are sorted by preference: recommended versions first, then LTS versions, then lower risk, then fewer steps.

Validate Upgrade

Endpoint: POST /api/v1/registry/upgrade-paths/validate?fromVersionId=:fromId&toVersionId=:toId

Validates whether an upgrade is safe to execute by checking dependency compatibility, version status, path testing status, and risk level.

curl -X POST "http://localhost:8084/api/v1/registry/upgrade-paths/validate?fromVersionId=aaa&toVersionId=bbb" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "kafka": "3.6.0",
    "postgresql": "16.1"
  }'

UpgradeValidation Structure

Field	Type	Description
`valid`	boolean	Whether the upgrade can proceed (no blockers)
`blockers`	List	Issues that prevent the upgrade
`warnings`	List	Non-blocking concerns
`prerequisites`	List	Actions required before proceeding
`suggestedRoute`	UpgradeRoute	The recommended upgrade path

Validation checks include:

Upgrade path existence between the two versions
Required dependency availability in installed components
No end-of-life versions in the upgrade path
Deprecation warnings for deprecated intermediate versions
Untested path warnings
Downtime scheduling requirements for paths that require downtime
Backup prerequisites for critical risk paths

Zero-Downtime Paths

Endpoint: GET /api/v1/registry/components/:componentId/upgrade-paths/zero-downtime

Returns all registered upgrade paths for a component that do not require downtime, useful for planning live upgrades.

Component Versioning Upgrade Execution