Installer Update CLI Command V3 Design #2406

diamonwiggins · 2025-07-03T19:20:36Z

What this PR does / why we need it:

Which issue(s) this PR fixes:

SC-125756

Does this PR require a test?

Does this PR require a release note?

Does this PR require documentation?

emosbaugh · 2025-07-03T21:42:20Z

design/embedded-cluster-cli-driven-update.md

+
+The binary needs to discover available updates by calling the replicated.app API.
+
+**New API Endpoint:** `GET /embedded/:appSlug/:channelSlug/versions`


does this send the current version? otherwise this list could get long.

Could use @sgalsaleh's feedback here to flush out the API a bit more. From my investigation of the KOTS code, it looks like we use a cursor to keep track of releases that have already been pulled down. That's of course requiring us to store some state in the database to keep track of that.

why does this need to be a new endpoint? can't we just use the existing endpoint? we would have all the information we need about the current release and can send the channel cursor, version label, etc... and the current endpoint would return available updates

Which existing endpoint? The one where we download the binary currently, GET /embedded/:appSlug/:channelSlug/:versionLabel? Or the existing endpoint(s) already being used to check for available releases, /release/{appSlug}/pending?

design/embedded-cluster-cli-driven-update.md

github-actions · 2025-07-07T14:18:41Z

This PR has been released (on staging) and is available for download with a embedded-cluster-smoke-test-staging-app license ID.

Online Installer:

curl "https://staging.replicated.app/embedded/embedded-cluster-smoke-test-staging-app/ci/appver-dev-0a9c5ed" -H "Authorization: $EC_SMOKE_TEST_LICENSE_ID" -o embedded-cluster-smoke-test-staging-app-ci.tgz

Airgap Installer (may take a few minutes before the airgap bundle is built):

curl "https://staging.replicated.app/embedded/embedded-cluster-smoke-test-staging-app/ci-airgap/appver-dev-0a9c5ed?airgap=true" -H "Authorization: $EC_SMOKE_TEST_LICENSE_ID" -o embedded-cluster-smoke-test-staging-app-ci.tgz

Happy debugging!

sgalsaleh · 2025-07-07T14:58:51Z

design/embedded-cluster-cli-driven-update.md

+#### 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


if it's just for skipping prompts, then i believe it should be --yes

sgalsaleh · 2025-07-07T15:01:03Z

design/embedded-cluster-cli-driven-update.md

+  - Channel-specific and may restart across different channels
+  - Essential for efficient API communication
+
+- **Version labels**: User-facing identifiers (e.g., v1.2.0, v1.2.1)


why not just support version labels? what's the need to support channel sequences and embedded cluster technical versions?

i had the same question, and raised it at the bottom of the doc in the questions section. I think just supported version labels is the way to go as well.

sgalsaleh · 2025-07-07T15:02:53Z

design/embedded-cluster-cli-driven-update.md

+Cursor: 1251    →   Version: v1.3.0   →   EC: 1.6.0+k8s-1.30
+```
+
+This multi-layered approach allows the binary to handle API efficiency, user experience, and technical compatibility as separate concerns.


not sure i understand what this means. seems like complexity that isn't necessary?

yeah, this section isn't totally clear. I'll update. Its sort of conflating which versions the API will care about with what role each version plays in the CLI-driven update architecture as a whole.

sgalsaleh · 2025-07-07T15:12:18Z

design/embedded-cluster-cli-driven-update.md

+
+**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


That's not how it works in KOTS, and I don't think this makes sense either. I can mark the same version / semver as required on a certain channel, but not required on another.

sgalsaleh · 2025-07-07T15:15:29Z

design/embedded-cluster-cli-driven-update.md

+- 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


i don't think the client (EC CLI) should even care about semver being enabled or not. the sorting mechanism lives in replicated.app, and the client should simply check a linear list for required / non-required releases. for example, if you're trying to deploy a specific release, can just check if there's a required release before it in the list of available updates returned from replicated.app. there's no need to sort or even know if it's semver or not in this case.

Makes sense. Is this how it works in KOTS as well? Either way, with us not worrying about sequences and just versions, this is the natural conclusion as well i think.

sgalsaleh · 2025-07-07T15:16:21Z

design/embedded-cluster-cli-driven-update.md

+
+This multi-layered approach allows the binary to handle API efficiency, user experience, and technical compatibility as separate concerns.
+
+#### Version Comparison Logic


i don't think this should be a thing in embedded cluster. all this logic should only live in replicated.app

This was confusing for me when digging into the code for KOTS. It felt like KOTS handled a lot client side when it came to semver and required releases. Is that understanding incorrect?

JGAntunes · 2025-07-08T09:05:10Z

design/embedded-cluster-cli-driven-update.md

+
+#### Command Options (V3 Mode)
+- `--license`: **Required** - License file for authentication with replicated.app
+- `--version`: Optional parameter to specify target version (defaults to latest)


My understanding from reading the story is that the --version flag will be added later on and not expected to be part of this initial work piece, is that not the case anymore or are we just outlining what should happen in the future?

Outlining what will happen in the future. We converted from a regular story to a Spike after realizing this was more than just self updating the binary, and that we'll eventually be replacing the current in-UI functionality of checking for updates. So needing to consider how we'll handle things like required releases, etc.

Output of this document will be an Epic with multiple stories.

diamonwiggins added 3 commits July 3, 2025 14:51

add design doc for v3 update command

8967bdc

update doc

6c13e4c

update doc

2dda149

diamonwiggins added the type::chore label Jul 3, 2025

emosbaugh reviewed Jul 3, 2025

View reviewed changes

design/embedded-cluster-cli-driven-update.md Show resolved Hide resolved

emosbaugh reviewed Jul 3, 2025

View reviewed changes

design/embedded-cluster-cli-driven-update.md Show resolved Hide resolved

emosbaugh reviewed Jul 3, 2025

View reviewed changes

design/embedded-cluster-cli-driven-update.md Show resolved Hide resolved

diamonwiggins added 2 commits July 7, 2025 10:02

update design doc

93cada7

update title

0a9c5ed

diamonwiggins requested review from sgalsaleh, JGAntunes and screspod July 7, 2025 14:04

diamonwiggins marked this pull request as ready for review July 7, 2025 14:04

sgalsaleh reviewed Jul 7, 2025

View reviewed changes

JGAntunes reviewed Jul 8, 2025

View reviewed changes

diamonwiggins marked this pull request as draft July 9, 2025 22:27


		The binary needs to discover available updates by calling the replicated.app API.

		New API Endpoint: `GET /embedded/:appSlug/:channelSlug/versions`


		This multi-layered approach allows the binary to handle API efficiency, user experience, and technical compatibility as separate concerns.

		#### Version Comparison Logic

Installer Update CLI Command V3 Design #2406

Are you sure you want to change the base?

Installer Update CLI Command V3 Design #2406

Uh oh!

Conversation

diamonwiggins commented Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does / why we need it:

Which issue(s) this PR fixes:

Does this PR require a test?

Does this PR require a release note?

Does this PR require documentation?

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

diamonwiggins Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Jul 7, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

diamonwiggins commented Jul 3, 2025 •

edited

Loading

diamonwiggins Jul 7, 2025 •

edited

Loading