siderolabs / siderolabs/docs

TEL migration guide: state that the move to Talos Enterprise Linux is one-way

Open Beginner friendly
#768 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation omni
Dominant language
MDX
Stars
11
Forks
76
Avg merge
3d 5h
Merged PRs (30d)
26

Description

Fast follow to docs#757, which is being merged as part of the Talos Enterprise Linux launch section. Part of #649.

The migration how-to (tel/how-to-guides/migrate-clusters-to-tel) tells a customer how to move a cluster onto Talos Enterprise Linux, but does not tell them the move cannot be undone. That is the one thing a reader most needs before they trigger the upgrade, so it should be stated on the page rather than learned afterwards.

What to add

A short note in the migration guide saying the move is one-way, placed before the steps rather than after them.

The mechanics, from omni#2760:

  • Talos Enterprise Linux exists only for Talos v1.13.0 and later.
  • Omni is connected to both factories and prefers the enterprise one for any version the two have in common. A user cannot choose the open-source factory for a version that Enterprise Image Factory also serves.
  • Downgrading from Talos Enterprise Linux back to open-source Talos is prohibited.

So for a cluster already on v1.13.0 or later, the next upgrade of any kind moves it to enterprise images and there is no supported route back.

Also worth considering for the same page

The same issue records a second consequence that is arguably sharper for the reader: if Omni loses its connection to the factory a machine's images came from, it treats those machines as orphaned and will not upgrade them. The only permitted operation is to destroy them. Whether that belongs in the migration guide or somewhere in the enterprise factory concept pages is a judgement call, but it is currently written down nowhere a customer will see it.

Why it was not in the original PR

The point surfaced during launch-day discussion in #proj-omni on September 15, after the PR had been reviewed and approved. Splitting it out rather than holding the merge.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Open the migration how-to at tel/how-to-guides/migrate-clusters-to-tel and read the introductory content before the migration steps. Add a short warning there that moving to Talos Enterprise Linux is one-way and cannot be reverted to open-source Talos; the page is done when readers see this before starting the upgrade.

Written by the indexing model from the issue text.

Assessment

Tech stack
linux
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
90/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.