Skip to content

docs: update friction log with EC3 airgap and config findings #59

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aa-replicated merged 2 commits into from
May 13, 2026
Merged

docs: update friction log with EC3 airgap and config findings #59

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0db92c7
docs: log invalid config during setup leaves install unrecoverable
aa-replicated Apr 18, 2026
f873144
Merge branch 'main' into demo/tier4
aa-replicated May 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions FRICTION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,6 @@
3. preflights on a fresh VM fail fast. It seems there's easily scripted fixes we could provide to streamline the onboarding
4. Host preflights run during in-place upgrades and fail on ports already in use by the running cluster (e.g. etcd on 2379/TCP). These checks should be skipped for upgrades since the cluster is already installed — flagging in-use ports as blockers on an existing node is incorrect behavior and blocks the upgrade flow in the web UI.
5. In-place upgrade via the web UI fails because EC3 attempts to reinstall k0s rather than upgrade the existing cluster. The UI shows "installation" state during what should be an upgrade flow, then errors on k0s already being present. Upgrade appears to not be supported or is broken in this EC3 alpha version.
6. **In-place upgrade via web UI fails; headless upgrade works** — The EC3 web UI upgrade flow fails (see items 4 and 5). Running `sudo ./gameshelf upgrade` headlessly succeeds. Additionally, the headless upgrade on beta.1 fails with `daemon binary not found: expected /usr/local/bin/assets/gameshelf-service` — the binary exists at `/usr/local/bin/gameshelf-service` but beta.1 expects it in an `assets/` subdirectory. Workaround: `sudo mkdir -p /usr/local/bin/assets && sudo ln -s /usr/local/bin/gameshelf-service /usr/local/bin/assets/gameshelf-service`. Severity: Blocker for web UI upgrade path; headless path requires a manual symlink workaround.
6. **Invalid config during setup leaves install in an unrecoverable state** — If a config value fails validation (e.g. a password that's too short), the install fails and there is no way to retry or correct the value. The only option is to start over with a fresh install. There is no "go back and fix config" path in the EC3 setup UI.
7. **`ReplicatedImageRegistry` docs don't distinguish behavior by image origin** — The docs show using `ReplicatedImageRegistry (HelmValue ".replicated.image.registry")` to handle the replicated SDK image for airgap. This implies the function works uniformly for all images regardless of origin. In practice, calling `ReplicatedImageRegistry` on `proxy.replicated.com` (the SDK's native registry) in beta.1 does not work: without `noProxy=true` it produces a doubled proxy URL (`proxy.replicated.com/proxy/gameshelf/proxy.replicated.com/...`); with `noProxy=true` it returns an empty string for online installs, causing the image to resolve to `docker.io/library/replicated-sdk-image` (wrong). The SDK chart already uses `proxy.replicated.com` natively and works without any `helmchart.yaml` override — EC3 handles routing for it automatically. The docs don't make clear that the replicated SDK image is a special case that should be left alone. Resolution: removed the `replicated.image.registry` override entirely. ~3 hours of debugging across multiple PRs.


Loading