Skip to content

docs(operator): describe which files a NodeOpUpgrade installs - #794

Draft
jimmykarily wants to merge 3 commits into
mainfrom
docs/nodeopupgrade-image-files
Draft

jimmykarily wants to merge 3 commits into
mainfrom
docs/nodeopupgrade-image-files

Conversation

@jimmykarily

@jimmykarily jimmykarily commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Docs for kairos-io/kairos-operator#314, which fixes kairos-io/kairos#6109. Merge after that PR, since this page describes the operator's unreleased behaviour.

What changes for readers

The NodeOpUpgrade page currently says:

  • the operator always passes --exclude-path /etc/hostname --exclude-path /etc/hosts to kairos-agent upgrade;
  • spec.excludePaths "preserves" host paths during the upgrade;
  • to replace a node's /etc/hostname you need a manual NodeOp with an OCI source.

After kairos-io/kairos-operator#314, a NodeOpUpgrade copies the new system from a plain (non-recursive) bind mount of the upgrade Pod's root. The node gets the image's own /etc/resolv.conf, /etc/hosts and /etc/hostname, without the Pod-specific copies Kubernetes mounts into every Pod. The only exclusions the operator adds are for those of the three files the image does not ship, or ships empty.

The "preserves" wording was also wrong before that change. kairos-agent builds the new system image from scratch, so an excluded path is missing from the new system; the node's current copy is not kept.

Edits

Only operator-docs/nodeop-upgrade.md. The versioned pages describe released operators, which still behave the old way.

  • The excludePaths table row and the example comment drop the always-excluded pair and describe what an exclusion does.
  • "Preserving host paths from the upgrade" becomes "Which files the upgrade installs": why the Pod's files must not reach the node, the bind mount, and that the result matches a fresh install of spec.image.
  • A new "Leaving paths out of the new system" subsection explains excludePaths and points to /usr/local and the persistent bind-mounted paths for data that must survive an upgrade.
  • The same section explains that when spec.image lacks one of the three files, the container runtime creates an empty one to mount onto, and the upgrade leaves any of them that is missing or empty out of the new system. The example command shows the resulting --exclude-path.
  • "Requirements" says kairos-agent v3.6.0+ is needed when excludePaths is set or when the image lacks one of the three files.
  • The "Overwriting /etc/hostname on purpose" subsection is removed, since a NodeOpUpgrade now installs the image's /etc/hostname.

I did not build the site locally. No other page links to the removed anchors (#preserving-host-paths-from-the-upgrade, #overwriting-etchostname-on-purpose) outside the versioned docs, which keep their own copies of those sections.

🤖 Generated with Claude Code

The NodeOpUpgrade page said the operator always passes --exclude-path for
/etc/hostname and /etc/hosts, and that excludePaths "preserves" host
paths. With kairos-io/kairos-operator#314 the upgrade copies from a plain
bind mount of the upgrade Pod's root, so the node gets the image's own
/etc/resolv.conf, /etc/hosts and /etc/hostname and the operator adds no
exclusions of its own.

excludePaths was also described wrongly before that change: kairos-agent
builds the new system image from scratch, so an excluded path is missing
from the new system rather than kept from the node. The section now says
so and points to the persistent paths for data that must survive an
upgrade. The subsection about overwriting /etc/hostname through a manual
NodeOp is gone, since a NodeOpUpgrade now installs the image's
/etc/hostname.

Only the unreleased docs change. The versioned pages describe the
released operators, which still behave the old way.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Dimitris Karakasilis <dimitris@karakasilis.me>
@netlify

netlify Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for kairos-io ready!

Name Link
🔨 Latest commit 405381e
🔍 Latest deploy log https://app.netlify.com/projects/kairos-io/deploys/6af5c0b843e1f519c2e2df0e
😎 Deploy Preview https://deploy-preview-794--kairos-io.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

When the upgrade image has no /etc/resolv.conf, /etc/hosts or
/etc/hostname, the container runtime creates an empty file there to
mount the Pod's copy onto. kairos-io/kairos-operator#314 leaves any of
the three that is missing or empty out of the new system, so the node
matches a fresh install of the image. For /etc/resolv.conf that keeps
images that rely on systemd to create the symlink at boot working.

The page now explains this, shows the resulting --exclude-path in the
example command, and says the kairos-agent v3.6.0 requirement also
applies when the image lacks one of the files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Dimitris Karakasilis <dimitris@karakasilis.me>
kairos-io/kairos-operator#314 only leaves /etc/resolv.conf, /etc/hosts
and /etc/hostname out of the new system when they are missing or empty
regular files. A symlink is copied as is, so an image that ships
/etc/resolv.conf as a link to systemd-resolved's file keeps it. The page
said "missing or empty", which reads as if an empty or dangling link
target would also exclude the link.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Dimitris Karakasilis <dimitris@karakasilis.me>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

NodeOpUpgrade copies Pod resolv.conf into host OS, causing CoreDNS loops and image-pull failures

1 participant