From 8967bdc9e90df0544b38a846c6ee08ff7a91e1de Mon Sep 17 00:00:00 2001 From: Diamon Wiggins Date: Thu, 3 Jul 2025 14:51:43 -0400 Subject: [PATCH 1/5] add design doc for v3 update command --- ...cluster-self-update-implementation-plan.md | 213 ++++++++++++++++++ 1 file changed, 213 insertions(+) create mode 100644 design/embedded-cluster-self-update-implementation-plan.md diff --git a/design/embedded-cluster-self-update-implementation-plan.md b/design/embedded-cluster-self-update-implementation-plan.md new file mode 100644 index 000000000..3178204f0 --- /dev/null +++ b/design/embedded-cluster-self-update-implementation-plan.md @@ -0,0 +1,213 @@ +# Embedded Cluster Self-Update Implementation Plan + +## Overview + +This document outlines the high-level changes required to implement a self-updating mechanism for embedded cluster binaries, similar to the Replicated CLI's `version upgrade` command. The implementation will **modify the existing `./binary update` command** to perform binary self-updating when `ENABLE_V3=1` is set, instead of its current behavior of updating applications with airgap bundles. + +## Architecture Overview + +The self-update mechanism will leverage the existing embedded cluster download infrastructure while adding new components for version management, update detection, and safe binary replacement. + +``` +Embedded Cluster Binary → Version Check → Download New Binary → Atomic Replacement + ↓ ↓ ↓ ↓ +[Current Binary] [Version API] [Download Endpoint] [selfupdate] +``` + +## High-Level Changes Required + +### 1. Command Line Interface Changes + +#### Modified Update Command Behavior +- **Conditional behavior**: Check `ENABLE_V3` environment variable to determine update mode +- **V2 mode**: Current behavior (application airgap bundle updates) +- **V3 mode**: Binary self-updating behavior +- **Command signature (V3)**: `./binary update --license [--version=] [--force]` +- **License requirement**: The `--license` flag is **required** when `ENABLE_V3=1` for authentication with replicated.app +- **Validation**: Verify the binary can be updated (not installed via package manager) + +#### Command Options (V3 Mode) +- `--license`: **Required** - License file for authentication with replicated.app +- `--version`: Optional parameter to specify target version (defaults to latest) +- `--force`: Skip confirmation prompts for automated scenarios + +#### Backward Compatibility +- **Preserve V2 behavior**: When `ENABLE_V3` is not set or set to 0, maintain current airgap bundle update functionality + +### 2. Version Management Infrastructure + +**Current State:** Most version infrastructure already exists in the embedded cluster binary. + +**What's Already Available:** +- Version information: `pkg/versions/versions.go` (EC version, k0s version) +- Embedded release data: App slug, channel, version label via `pkg/release/release.go` +- Version display: Existing `./binary version` command + +**What Needs to be Added:** +- **Version comparison logic**: Compare current vs latest version using semantic versioning or cursor-based ordering depending on channel configuration +- **API integration**: Call new endpoint to check for latest version +- **Combined version info function**: Consolidate existing version data into single response + +**Required Release Handling Strategy:** +Following the KOTS architecture pattern, the embedded cluster implementation should use a clear separation of responsibilities: + +**API Responsibility:** +- **Return all available versions** with complete metadata including `required` flags +- **No filtering or blocking** - provide raw data to client +- **Include version ordering information** (channel sequence, release dates) + +**Client Responsibility (Binary Update Logic):** +- **Determine update eligibility** based on required release rules +- **Enforce installation order** - prevent skipping required releases +- **Provide clear user feedback** when updates are blocked +- **Handle edge cases**: + - User specifies `--version` but skips required releases + - Multiple required releases between current and target version + - Rollback scenarios with required releases + +**User Experience Examples:** +```bash +# Normal update +./binary update --license license.yaml +→ "Update available: 1.6.0. Proceed? [y/N]" + +# Blocked by required release +./binary update --version 1.6.0 --license license.yaml +→ "Cannot update to 1.6.0. Required release 1.5.2 must be installed first." +→ "Run: ./binary update --version 1.5.2 --license license.yaml" + +# Multiple required releases +./binary update --version 1.7.0 --license license.yaml +→ "Cannot update to 1.7.0. Required releases 1.5.2, 1.6.1 must be installed first." +→ "Suggested: ./binary update --license license.yaml (installs 1.5.2)" +``` + +**Semver vs Non-Semver Channel Handling:** +Following the KOTS pattern, the embedded cluster should handle these channel types differently in the client: + +**API Behavior (Identical for Both):** +- Returns all releases with same metadata structure +- No semver-specific filtering or ordering by the API +- Provides `semverRequired` flag in channel metadata + +**Client Logic Differences:** + +**Non-Semver Channels (`semverRequired: false`):** +- **Cursor-based ordering**: Use channel sequence numbers for version comparison +- **Channel-scoped comparisons**: Only compare versions within the same channel +- **Required release scope**: Required releases only apply within current channel +- **Fallback ordering**: Use release dates or sequence numbers when other ordering fails + +**Semver Channels (`semverRequired: true`):** +- **Semantic version ordering**: Parse and compare using semver rules (e.g., v1.2.3 > v1.2.1) +- **Cross-channel compatibility**: Can compare versions across different channels +- **Required release scope**: Required releases can block updates across ALL channels +- **Mixed version handling**: Handle channels with mix of semver and non-semver releases + +**User Experience Differences:** +```bash +# Non-semver channel: sequence-based ordering +./binary update --license license.yaml +→ "Update available: sequence 156 (was 155). Proceed? [y/N]" + +# Semver channel: semantic version ordering +./binary update --license license.yaml +→ "Update available: v1.6.0 (from v1.5.2). Proceed? [y/N]" + +# Cross-channel semver comparison +./binary update --version v1.7.0 --license license.yaml +→ "Cannot update to v1.7.0 from beta channel. Required release v1.6.5 from stable channel must be installed first." +``` + +**Key Point:** This leverages existing infrastructure rather than building new version management from scratch. + +### 3. Update Discovery Mechanism + +The system needs to discover available updates by calling the replicated.app API. + +**New API Endpoint:** `GET /embedded/:appSlug/:channelSlug/versions` +- **Architecture**: Follow same proxy pattern as download endpoint (replicated-app → market-api) +- **Authentication**: Same license-based authentication as download endpoint +- **Authorization**: License ID in `Authorization` header +- **Validation**: Same app/channel access controls and feature flag checks + +**API Response Format:** +```json +{ + "channel": { + "id": "channel-123", + "name": "Stable", + "slug": "stable", + "semverRequired": true, + "latestVersion": "1.2.3" + }, + "versions": [ + { + "versionLabel": "1.2.3", + "channelSequence": 456, + "ecVersion": "1.5.0+k8s-1.29", + "releaseDate": "2024-01-15T10:30:00Z", + "available": true, + "airgapSupported": true, + "required": false + }, + { + "versionLabel": "1.2.2", + "channelSequence": 455, + "ecVersion": "1.4.0+k8s-1.28", + "releaseDate": "2024-01-10T14:20:00Z", + "available": true, + "airgapSupported": true, + "required": false + } + ] +} +``` + +**Key Implementation Requirements:** +- **Reuse existing infrastructure**: Same authentication, validation, and proxy patterns as download endpoint +- **Database optimization**: Efficient queries to avoid N+1 problems with large version lists +- **Error handling**: Consistent error responses and HTTP status codes with download endpoint +- **Performance**: Reasonable response times with appropriate caching headers + +### 4. Binary Download and Replacement (TODO - Self-Update Logic) + +**Current State:** No existing self-update logic in embedded cluster binary. + +#### Download Process +Leverage existing embedded cluster download infrastructure: +- **Reuse download endpoint**: Use current `/embedded/:appSlug/:channelSlug/:versionLabel` pattern +- **Authentication**: Pass license ID from `--license` flag in Authorization header +- **Streaming download**: Handle large binaries efficiently without excessive memory usage +- **Progress indication**: Show download progress with percentage and transfer rates +- **Resume capability**: Support interrupted download resumption for reliability +- **Temporary storage**: Download to temp location before replacement + +#### Atomic Replacement Strategy +Use proven `selfupdate` library approach (same as Replicated CLI): +- **Backup creation**: Always create backup of current binary before replacement +- **Atomic operation**: Use filesystem moves/renames for atomicity where possible +- **Permission preservation**: Maintain original executable permissions and ownership +- **Cross-platform support**: Handle platform-specific file replacement quirks +- **Verification post-replacement**: Confirm new binary works correctly + +#### Error Handling and Rollback +Comprehensive error recovery mechanisms: +- **Download failures**: Network timeouts, authentication errors, disk space issues +- **Verification failures**: Checksum mismatches, corrupted downloads +- **Replacement failures**: Permission errors, file locks, disk full +- **Automatic rollback**: Restore backup if new binary fails basic validation +- **User guidance**: Clear error messages with suggested remediation steps +- **Cleanup**: Remove temporary files and failed downloads + +#### Security Considerations +- **HTTPS enforcement**: All downloads over secure connections +- **License validation**: Verify license before attempting download +- **File permissions**: Ensure downloaded files have appropriate restrictions +- **Audit logging**: Log all update attempts for security monitoring + +**Implementation Notes:** +- Mirror Replicated CLI's proven patterns for reliability +- Handle edge cases like running binary being updated +- Support both interactive and automated (scripted) usage +- Graceful degradation when self-update not possible From 6c13e4cedc38f7b88a70747a202c4673b40ccbda Mon Sep 17 00:00:00 2001 From: Diamon Wiggins Date: Thu, 3 Jul 2025 15:07:50 -0400 Subject: [PATCH 2/5] update doc --- ...d => embedded-cluster-cli-driven-update.md} | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) rename design/{embedded-cluster-self-update-implementation-plan.md => embedded-cluster-cli-driven-update.md} (89%) diff --git a/design/embedded-cluster-self-update-implementation-plan.md b/design/embedded-cluster-cli-driven-update.md similarity index 89% rename from design/embedded-cluster-self-update-implementation-plan.md rename to design/embedded-cluster-cli-driven-update.md index 3178204f0..048f64265 100644 --- a/design/embedded-cluster-self-update-implementation-plan.md +++ b/design/embedded-cluster-cli-driven-update.md @@ -1,12 +1,14 @@ -# Embedded Cluster Self-Update Implementation Plan +# Embedded Cluster CLI-Driven Update Design ## Overview -This document outlines the high-level changes required to implement a self-updating mechanism for embedded cluster binaries, similar to the Replicated CLI's `version upgrade` command. The implementation will **modify the existing `./binary update` command** to perform binary self-updating when `ENABLE_V3=1` is set, instead of its current behavior of updating applications with airgap bundles. +This document outlines the implementation of **CLI-driven updates** to support the new architecture where customers will download a new binary to get the new release of software, compared to before where customers could check for versions in the UI to download and apply new versions. + +The implementation will **modify the existing `./binary update` command** to perform CLI-driven binary updating when `ENABLE_V3=1` is set, instead of its current behavior of updating applications with airgap bundles. ## Architecture Overview -The self-update mechanism will leverage the existing embedded cluster download infrastructure while adding new components for version management, update detection, and safe binary replacement. +The CLI-driven update mechanism will leverage the existing embedded cluster download infrastructure while adding new components for version management, update detection, and safe binary replacement. ``` Embedded Cluster Binary → Version Check → Download New Binary → Atomic Replacement @@ -21,7 +23,7 @@ Embedded Cluster Binary → Version Check → Download New Binary → Atomic Rep #### Modified Update Command Behavior - **Conditional behavior**: Check `ENABLE_V3` environment variable to determine update mode - **V2 mode**: Current behavior (application airgap bundle updates) -- **V3 mode**: Binary self-updating behavior +- **V3 mode**: CLI-driven binary updating behavior - **Command signature (V3)**: `./binary update --license [--version=] [--force]` - **License requirement**: The `--license` flag is **required** when `ENABLE_V3=1` for authentication with replicated.app - **Validation**: Verify the binary can be updated (not installed via package manager) @@ -123,7 +125,7 @@ Following the KOTS pattern, the embedded cluster should handle these channel typ ### 3. Update Discovery Mechanism -The system needs to discover available updates by calling the replicated.app API. +The binary needs to discover available updates by calling the replicated.app API. **New API Endpoint:** `GET /embedded/:appSlug/:channelSlug/versions` - **Architecture**: Follow same proxy pattern as download endpoint (replicated-app → market-api) @@ -170,9 +172,9 @@ The system needs to discover available updates by calling the replicated.app API - **Error handling**: Consistent error responses and HTTP status codes with download endpoint - **Performance**: Reasonable response times with appropriate caching headers -### 4. Binary Download and Replacement (TODO - Self-Update Logic) +### 4. Binary Download and Replacement (CLI-Driven Update Logic) -**Current State:** No existing self-update logic in embedded cluster binary. +**Current State:** No existing binary update logic in embedded cluster binary. #### Download Process Leverage existing embedded cluster download infrastructure: @@ -210,4 +212,4 @@ Comprehensive error recovery mechanisms: - Mirror Replicated CLI's proven patterns for reliability - Handle edge cases like running binary being updated - Support both interactive and automated (scripted) usage -- Graceful degradation when self-update not possible +- Graceful degradation when binary update not possible From 2dda1496d355e61a344b73f98b9d5e86c23cefe4 Mon Sep 17 00:00:00 2001 From: Diamon Wiggins Date: Thu, 3 Jul 2025 15:19:52 -0400 Subject: [PATCH 3/5] update doc --- design/embedded-cluster-cli-driven-update.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/design/embedded-cluster-cli-driven-update.md b/design/embedded-cluster-cli-driven-update.md index 048f64265..f211d77fd 100644 --- a/design/embedded-cluster-cli-driven-update.md +++ b/design/embedded-cluster-cli-driven-update.md @@ -4,7 +4,7 @@ This document outlines the implementation of **CLI-driven updates** to support the new architecture where customers will download a new binary to get the new release of software, compared to before where customers could check for versions in the UI to download and apply new versions. -The implementation will **modify the existing `./binary update` command** to perform CLI-driven binary updating when `ENABLE_V3=1` is set, instead of its current behavior of updating applications with airgap bundles. +This implementation would **modify the existing `./binary update` command** to perform CLI-driven binary updates when `ENABLE_V3=1` is set. ## Architecture Overview From 93cada76aae1f77bcccd190723c61fe617d28640 Mon Sep 17 00:00:00 2001 From: Diamon Wiggins Date: Mon, 7 Jul 2025 10:02:37 -0400 Subject: [PATCH 4/5] update design doc --- design/embedded-cluster-cli-driven-update.md | 195 ++++++++++++------- 1 file changed, 129 insertions(+), 66 deletions(-) diff --git a/design/embedded-cluster-cli-driven-update.md b/design/embedded-cluster-cli-driven-update.md index f211d77fd..303749a37 100644 --- a/design/embedded-cluster-cli-driven-update.md +++ b/design/embedded-cluster-cli-driven-update.md @@ -1,14 +1,28 @@ -# Embedded Cluster CLI-Driven Update Design +# Embedded Cluster CLI-First Update Management Implementation Plan ## Overview -This document outlines the implementation of **CLI-driven updates** to support the new architecture where customers will download a new binary to get the new release of software, compared to before where customers could check for versions in the UI to download and apply new versions. +This document outlines the implementation of a **CLI-first update management system** for embedded cluster binaries, representing a fundamental architectural shift from the traditional KOTS web UI-centric approach to direct command-line operations. -This implementation would **modify the existing `./binary update` command** to perform CLI-driven binary updates when `ENABLE_V3=1` is set. +### Architectural Transformation + +**Traditional KOTS Approach (Web UI-Centric):** +- Install kotsadm admin console (web UI) into the cluster +- Use port forwarding to access web interface on localhost:8800 +- Manage applications through browser-based admin console +- CLI primarily used for bootstrapping the web UI + +**New Embedded Cluster Approach (CLI-First):** +- Direct CLI commands for all operations without web UI dependency +- Self-updating binary that can manage both itself and applications +- All management happens through command-line interface +- No requirement for in-cluster web console + +The implementation will **modify the existing `./binary update` command** to perform binary self-updating when `ENABLE_V3=1` is set, instead of its current behavior of updating applications with airgap bundles. ## Architecture Overview -The CLI-driven update mechanism will leverage the existing embedded cluster download infrastructure while adding new components for version management, update detection, and safe binary replacement. +The self-update mechanism will leverage the existing embedded cluster download infrastructure while adding new components for version management, update detection, and safe binary replacement. ``` Embedded Cluster Binary → Version Check → Download New Binary → Atomic Replacement @@ -23,7 +37,7 @@ Embedded Cluster Binary → Version Check → Download New Binary → Atomic Rep #### Modified Update Command Behavior - **Conditional behavior**: Check `ENABLE_V3` environment variable to determine update mode - **V2 mode**: Current behavior (application airgap bundle updates) -- **V3 mode**: CLI-driven binary updating behavior +- **V3 mode**: Binary self-updating behavior - **Command signature (V3)**: `./binary update --license [--version=] [--force]` - **License requirement**: The `--license` flag is **required** when `ENABLE_V3=1` for authentication with replicated.app - **Validation**: Verify the binary can be updated (not installed via package manager) @@ -45,87 +59,103 @@ Embedded Cluster Binary → Version Check → Download New Binary → Atomic Rep - Embedded release data: App slug, channel, version label via `pkg/release/release.go` - Version display: Existing `./binary version` command -**What Needs to be Added:** -- **Version comparison logic**: Compare current vs latest version using semantic versioning or cursor-based ordering depending on channel configuration -- **API integration**: Call new endpoint to check for latest version -- **Combined version info function**: Consolidate existing version data into single response +#### Architecture Approach -**Required Release Handling Strategy:** -Following the KOTS architecture pattern, the embedded cluster implementation should use a clear separation of responsibilities: +**Dual Sequence Handling:** +The embedded cluster must handle multiple versioning schemes simultaneously, each serving different purposes: -**API Responsibility:** -- **Return all available versions** with complete metadata including `required` flags -- **No filtering or blocking** - provide raw data to client -- **Include version ordering information** (channel sequence, release dates) - -**Client Responsibility (Binary Update Logic):** -- **Determine update eligibility** based on required release rules -- **Enforce installation order** - prevent skipping required releases -- **Provide clear user feedback** when updates are blocked -- **Handle edge cases**: - - User specifies `--version` but skips required releases - - Multiple required releases between current and target version - - Rollback scenarios with required releases - -**User Experience Examples:** -```bash -# Normal update -./binary update --license license.yaml -→ "Update available: 1.6.0. Proceed? [y/N]" +- **Upstream cursors**: Channel sequence numbers from API (e.g., 1247, 1248, 1251, 1255) + - Used for API synchronization and incremental updates + - Can have gaps when releases are skipped or removed + - Channel-specific and may restart across different channels + - Essential for efficient API communication -# Blocked by required release -./binary update --version 1.6.0 --license license.yaml -→ "Cannot update to 1.6.0. Required release 1.5.2 must be installed first." -→ "Run: ./binary update --version 1.5.2 --license license.yaml" +- **Version labels**: User-facing identifiers (e.g., v1.2.0, v1.2.1) + - What customers see and use in commands + - May follow semantic versioning or custom labeling schemes + - Used for `--version` flag and user communication + - Channel-agnostic when semver is enabled -# Multiple required releases -./binary update --version 1.7.0 --license license.yaml -→ "Cannot update to 1.7.0. Required releases 1.5.2, 1.6.1 must be installed first." -→ "Suggested: ./binary update --license license.yaml (installs 1.5.2)" +- **Embedded cluster versions**: Technical versions (e.g., 1.5.0+k8s-1.29) + - Indicates the embedded cluster infrastructure version + - Includes Kubernetes version and other technical details + - Used for compatibility checks and technical validation + - Independent of application versioning + +**Example Mapping:** +``` +API Release User Experience Technical Details +───────────── ───────────────── ───────────────── +Cursor: 1247 → Version: v1.2.0 → EC: 1.5.0+k8s-1.29 +Cursor: 1248 → Version: v1.2.1 → EC: 1.5.0+k8s-1.29 +Cursor: 1251 → Version: v1.3.0 → EC: 1.6.0+k8s-1.30 ``` -**Semver vs Non-Semver Channel Handling:** -Following the KOTS pattern, the embedded cluster should handle these channel types differently in the client: +This multi-layered approach allows the binary to handle API efficiency, user experience, and technical compatibility as separate concerns. -**API Behavior (Identical for Both):** -- Returns all releases with same metadata structure -- No semver-specific filtering or ordering by the API -- Provides `semverRequired` flag in channel metadata +#### Version Comparison Logic -**Client Logic Differences:** +**Channel Configuration Driven:** +The comparison method depends on channel settings received from the API: **Non-Semver Channels (`semverRequired: false`):** -- **Cursor-based ordering**: Use channel sequence numbers for version comparison -- **Channel-scoped comparisons**: Only compare versions within the same channel -- **Required release scope**: Required releases only apply within current channel -- **Fallback ordering**: Use release dates or sequence numbers when other ordering fails +- Use channel sequence numbers for version comparison +- Compare versions only within the same channel +- Required releases apply within current channel only +- Fallback to release dates when sequences unavailable **Semver Channels (`semverRequired: true`):** -- **Semantic version ordering**: Parse and compare using semver rules (e.g., v1.2.3 > v1.2.1) -- **Cross-channel compatibility**: Can compare versions across different channels -- **Required release scope**: Required releases can block updates across ALL channels -- **Mixed version handling**: Handle channels with mix of semver and non-semver releases +- Parse and compare using semantic versioning rules +- Required releases apply within current channel +- Handle mixed semver/non-semver releases gracefully -**User Experience Differences:** -```bash -# Non-semver channel: sequence-based ordering -./binary update --license license.yaml -→ "Update available: sequence 156 (was 155). Proceed? [y/N]" +#### Required Release Processing + +**API Responsibility:** +- Return available versions (potentially cursor-based/incremental) +- Include `required` flags without filtering +- Provide version ordering information (sequences, dates) + +**Client Responsibility:** +- Determine update eligibility based on required release rules +- Enforce installation order without skipping required releases +- Provide clear user feedback when updates are blocked +- Handle complex scenarios (multiple required releases, version validation) -# Semver channel: semantic version ordering +#### User Experience Examples + +**Normal Update:** +```bash ./binary update --license license.yaml → "Update available: v1.6.0 (from v1.5.2). Proceed? [y/N]" +``` -# Cross-channel semver comparison -./binary update --version v1.7.0 --license license.yaml -→ "Cannot update to v1.7.0 from beta channel. Required release v1.6.5 from stable channel must be installed first." +**Update to Specific Version:** +```bash +./binary update --version v1.5.9 --license license.yaml +→ "Update available: v1.5.9 (from v1.5.2). Proceed? [y/N]" ``` -**Key Point:** This leverages existing infrastructure rather than building new version management from scratch. +**Blocked by Required Release:** +```bash +./binary update --version v1.6.0 --license license.yaml +→ "Cannot update to v1.6.0. Required release v1.5.2 must be installed first." +→ "Run: ./binary update --version v1.5.2 --license license.yaml" +``` + +#### Implementation Considerations + +**What Needs to be Added:** +- **Version comparison utilities**: Handle both semver and cursor-based ordering +- **API integration**: Call new endpoint to retrieve complete version lists +- **Required release validator**: Implement client-side logic without persistent state +- **Channel-aware logic**: Handle different comparison rules per channel type + +**Key Point:** This leverages existing infrastructure while adapting proven version management patterns for a stateless, CLI-driven environment. ### 3. Update Discovery Mechanism -The binary needs to discover available updates by calling the replicated.app API. +The system needs to discover available updates by calling the replicated.app API. **New API Endpoint:** `GET /embedded/:appSlug/:channelSlug/versions` - **Architecture**: Follow same proxy pattern as download endpoint (replicated-app → market-api) @@ -172,9 +202,9 @@ The binary needs to discover available updates by calling the replicated.app API - **Error handling**: Consistent error responses and HTTP status codes with download endpoint - **Performance**: Reasonable response times with appropriate caching headers -### 4. Binary Download and Replacement (CLI-Driven Update Logic) +### 4. Binary Download and Replacement (TODO - Self-Update Logic) -**Current State:** No existing binary update logic in embedded cluster binary. +**Current State:** No existing self-update logic in embedded cluster binary. #### Download Process Leverage existing embedded cluster download infrastructure: @@ -213,3 +243,36 @@ Comprehensive error recovery mechanisms: - Handle edge cases like running binary being updated - Support both interactive and automated (scripted) usage - Graceful degradation when binary update not possible + +## Questions + +### 1. State Management and API Cursor Support in Stateless Architecture + +**Question:** How do we handle state-dependent operations like required release validation, cursor tracking, and deployment history in a stateless CLI environment, and should the versions API endpoint support cursor-based filtering or always return all versions? + +**Context:** Embedded cluster's stateless architecture creates challenges for operations that typically require persistent state tracking. Without a local database or persistent storage, we need alternative approaches for: +- Tracking user's previous update path for required release validation +- Maintaining cursor positions for incremental API synchronization + +### 2. Cross-Channel Semver Support + +**Question:** Do we need to account for cross-channel semantic version comparisons, or can we simplify by restricting version comparisons to the same channel? + +**Context:** The current design includes cross-channel semver functionality where: +- Semver-enabled channels can compare versions across different channels (e.g., v1.2.3 from stable > v1.2.1 from beta) +- Required releases can block updates across ALL channels when semver is enabled +- This adds significant complexity to the version comparison logic + +### 3. Cursor-Based vs Semver-Only Version Management + +**Question:** Should embedded cluster support cursor-based version management at all, or simplify by only supporting semantic versioning? + +**Context:** The current design supports both cursor-based and semver version management like KOTS: +- **Cursor-based channels**: Use channel sequence numbers for ordering (1247, 1248, 1251, 1255) +- **Semver channels**: Use semantic version parsing and comparison (v1.2.0, v1.2.1, v1.3.0) + +**Considerations:** +- **Complexity**: Supporting both systems significantly increases implementation complexity +- **Stateless challenges**: Cursor-based systems typically rely on persistent state for tracking +- **User experience**: Semver is more intuitive and widely understood +- **Compatibility**: Some existing channels may not use semantic versioning From 0a9c5ed341115349fb3dfe60d547cedf39661b19 Mon Sep 17 00:00:00 2001 From: Diamon Wiggins Date: Mon, 7 Jul 2025 10:03:39 -0400 Subject: [PATCH 5/5] update title --- design/embedded-cluster-cli-driven-update.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/design/embedded-cluster-cli-driven-update.md b/design/embedded-cluster-cli-driven-update.md index 303749a37..e6e110448 100644 --- a/design/embedded-cluster-cli-driven-update.md +++ b/design/embedded-cluster-cli-driven-update.md @@ -1,4 +1,4 @@ -# Embedded Cluster CLI-First Update Management Implementation Plan +# Embedded Cluster CLI-Driven Update Design ## Overview