Add podman machine os upgrade command #27886

baude · 2026-01-09T16:50:47Z

Implements automatic OS upgrade functionality for Podman machines that requires no user input beyond running the command. The upgrade logic automatically determines the appropriate upgrade path using a three-way comparison between client version, machine version, and OCI registry:

When the client version is older than the machine version, no action is taken and an error is returned.
When the client version matches the machine version, the OCI registry is queried to check for in-band updates by comparing image digests. This handles minor, patch level, and updates oci image use cases.
When the client version is newer than the machine version, the machine is upgraded to match the client's major.minor version.
No manual image selection or version specification required.

The command supports dry-run mode and JSON (only) output format for automation.

Checklist

Ensure you have completed the following checklist for your pull request to be reviewed:

Certify you wrote the patch or otherwise have the right to pass it on as an open-source patch by signing all
commits. (git commit -s). (If needed, use git commit -s --amend). The author email must match
the sign-off email address. See CONTRIBUTING.md
for more information.
Referenced issues using Fixes: #00000 in commit message (if applicable)
Tests have been added/updated (or no tests are needed)
Documentation has been updated (or no documentation changes are needed)
All commits pass make validatepr (format/lint checks)
Release note entered in the section below (or None if no user-facing changes)

Does this PR introduce a user-facing change?

Addition of `podman machine os upgrade` which automatically updates the Podman virtual machine os based on its origin.

baude · 2026-01-09T16:52:34Z

Note to reviewers: We have absolutely no way to test this command at this point. os-apply is also not tested. I think this is a card entirely on itself. Nevertheless, to test this, the podman command needs to get built into the machine-os which is the problematic portion.

packit-as-a-service · 2026-01-09T18:42:48Z

Cockpit tests failed for commit 26394a4. @martinpitt, @jelly, @mvollmer please check.

ashley-cui

Tested manually on linux:

Init using old image

First machine upgrade succeeds
after a reboot, a secondary upgrade fails with Error: failed to parse ostree origin
Is this the preexisting issue with the new 6.1 OS not yet on quay? But plain init doesn't have output, so I'd assume it should be the same

plain podman machine init

no output, since it's on latest.

forced client lower version (client 6.0, machine-os 6.1

Error: client version 6.1.0 is older than your machine version 6.0.0-dev: upgrade your client
This message should be flipped, ie Error: client version 6.0.0-dev is older than your machine version 6.1.0 : upgrade your client

I believe these are the larger test cases, but if you need anything more specific.

packit-as-a-service · 2026-01-13T19:43:11Z

[NON-BLOCKING] Packit jobs failed. @containers/packit-build please check. Everyone else, feel free to ignore.

ashley-cui · 2026-01-14T14:49:24Z

Tested again, all comments were addressed and functionality LGTM.

pkg/machine/os/ostree.go

TomSweeneyRedHat · 2026-01-14T19:20:50Z

LGTM
but I'm not long in machine experience, I'd like another set of eyeballs

l0rd

The upgrade logic is perfect. I have a few comments on minor things that may be considered as post-merge follow up:

We should mention that WSL isn't supported in the doc
The command documentation could be improved (see comments below)
The changes to go.mod shouldn't be needed
Do you know why the bloat approved label is needed?
We should fail earlier if the provider is WSL
We should fail earlier if the provider is Hyper-V and the user is trying to restart without having the privileges to restart (not running as admin, not member of hyper-v admin group)
There are no machine tests and I understand that's not possible in this PR but will they be added later? Eventually uncommenting the tests for os apply command too?
Rather than having two separate commands (machine os apply and machine os upgrade) I find it simpler to have one unique command (machine update). The unique command would have the functionalities of both apply (specify a specific image) and upgrade (get the latest image if none is specified). I have checked a few packages managers (dnf, brew, winget) and they usually allow to specify a version in their upgrade/update command.

l0rd · 2026-01-15T11:26:21Z

cmd/podman/machine/os/upgrade.go

+var upgradeCmd = &cobra.Command{
+	Use:               "upgrade [options] [MACHINE]",
+	Short:             "Upgrade machine os",
+	Long:              "Upgrade the machine operating system to a newer version",


With this description, if I have an old CLI, I may still think that the machine will be updated. We can probably add another sentence that says that the new version will match the client major and minor version. And also I would find it useful to mention that the command machine os apply can update to a specific version.

l0rd · 2026-01-15T13:51:40Z

cmd/podman/machine/os/upgrade.go

+
+var upgradeCmd = &cobra.Command{
+	Use:               "upgrade [options] [MACHINE]",
+	Short:             "Upgrade machine os",


For apply we have: "Apply an OCI image to Podman Machine's OS". Compared to that, the cases of machine and os are inconsistent.

l0rd · 2026-01-15T13:55:45Z

cmd/podman/machine/os/upgrade.go

+)
+
+var upgradeCmd = &cobra.Command{
+	Use:               "upgrade [options] [MACHINE]",


For apply this is apply [options] IMAGE [NAME] where [NAME] is the corresponding machine name. Here it's called [MACHINE].

l0rd · 2026-01-15T13:58:01Z

cmd/podman/machine/os/upgrade.go

+	flags.StringVarP(&opts.format, formatFlagName, "f", "", "suppress output except for specified format. Implies -n")
+	_ = upgradeCmd.RegisterFlagCompletionFunc(formatFlagName, completion.AutocompleteNone)
+	restartFlagName := "restart"
+	flags.BoolVar(&opts.restart, restartFlagName, false, "Restart after upgrade")


For apply the help is Restart VM to apply changes, for consistency here we could use Restart VM to upgrade.

mtrmac

Just a drive-by, the dependency changes caught my eye. I didn’t read ~anything else.

pkg/machine/os/bootc.go

cmd/podman/machine/os/upgrade.go

mtrmac

A ~full review now, with the disclaimer that I never tried running it or studied the bootc CLI.

docs/source/markdown/podman-machine-os-upgrade.1.md

mtrmac · 2026-01-16T17:10:59Z

docs/source/markdown/podman-machine-os-upgrade.1.md

+Check if an update is available but the response will be in JSON format.  Note this
+exposes a boolean field that indicates if an update is available.
+
+Note: using a format option implies a dry-run.


This is not documented in the option’s primary paragraph, and I think it is critical to include.

(I’m also not sure it is a good idea — will we never have users trying to run the actual upgrade in a script, and needing a structured output?

Or are users wanting to trigger an actual upgrade expected to use the API directly? In that case it’s a bit curious — but still plausible — that the “check for upgrades” users are given a CLI with JSON output.)

the idea here is for consumers to be able to "check" if there is an upgrade (consider PD). And then the actual application of the update is done with the value there. That said, I'm asking PD to try this once it merges and they can provide feedback where we might make a change.

And yes, i missed adding dry-run to the format description.

And then the actual application of the update is done with the value there.

… for GUIs, note that things (in particular registry contents) can change between the “check” and the final update.

I suppose such callers would use os upgrade --format json to make an upgrade decision, and then os apply to actually upgrade to exactly that version — does that work?

correct, this is simply a mechanism to tell users that an update is available.

cmd/podman/machine/os/upgrade.go

pkg/machine/os/config.go

mtrmac · 2026-01-16T17:47:58Z

pkg/machine/os/ostree.go

+		}
+
+		args = []string{"bootc", "upgrade"}
+	default:


Most of machineInfo is left not updated — is it worth documenting which fields are set when?

Arguably letting users experiment might work fine … but they will only see the cross-version upgrade about two times a year, so that might be a surprise.

cmd/podman/machine/os/upgrade.go

pkg/machine/os/ostree_test.go

Implements automatic OS upgrade functionality for Podman machines that requires no user input beyond running the command. The upgrade logic automatically determines the appropriate upgrade path using a three-way comparison between client version, machine version, and OCI registry: * When the client version is older than the machine version, no action is taken and an error is returned. * When the client version matches the machine version, the OCI registry is queried to check for in-band updates by comparing image digests. This handles minor, patch level, and updates oci image use cases. * When the client version is newer than the machine version, the machine is upgraded to match the client's major.minor version. * No manual image selection or version specification required. The command supports dry-run mode and JSON (only) output format for automation. Signed-off-by: Brent Baude <[email protected]>

mheon · 2026-01-16T20:28:06Z

LGTM on my end. I think all comments are addressed?

baude added the No New Tests Allow PR to proceed without adding regression tests label Jan 9, 2026

baude marked this pull request as draft January 9, 2026 16:51

github-actions bot added the machine label Jan 9, 2026

baude force-pushed the machineosupgrade branch from 6f5eb5b to 26394a4 Compare January 9, 2026 18:17

baude added the bloat_approved Approve a PR in which binary file size grows by over 50k label Jan 9, 2026

baude force-pushed the machineosupgrade branch from 26394a4 to 63f99c3 Compare January 9, 2026 19:25

P4X-ng approved these changes Jan 10, 2026

View reviewed changes

baude force-pushed the machineosupgrade branch from 63f99c3 to 11c00be Compare January 12, 2026 16:46

ashley-cui reviewed Jan 13, 2026

View reviewed changes

baude force-pushed the machineosupgrade branch 2 times, most recently from 28dc900 to ea43274 Compare January 13, 2026 19:40

baude force-pushed the machineosupgrade branch 2 times, most recently from c117a54 to 3460fa0 Compare January 14, 2026 14:29

baude marked this pull request as ready for review January 14, 2026 15:11

TomSweeneyRedHat reviewed Jan 14, 2026

View reviewed changes

pkg/machine/os/ostree.go Show resolved Hide resolved

l0rd approved these changes Jan 15, 2026

View reviewed changes

baude removed the bloat_approved Approve a PR in which binary file size grows by over 50k label Jan 15, 2026

baude force-pushed the machineosupgrade branch from 3460fa0 to ca512c6 Compare January 15, 2026 16:12

baude added the bloat_approved Approve a PR in which binary file size grows by over 50k label Jan 15, 2026

mtrmac reviewed Jan 15, 2026

View reviewed changes

pkg/machine/os/bootc.go Outdated Show resolved Hide resolved

pkg/machine/os/bootc.go Outdated Show resolved Hide resolved

cmd/podman/machine/os/upgrade.go Outdated Show resolved Hide resolved

mtrmac reviewed Jan 16, 2026

View reviewed changes

baude force-pushed the machineosupgrade branch from ca512c6 to aba2df7 Compare January 16, 2026 20:14

baude removed the bloat_approved Approve a PR in which binary file size grows by over 50k label Jan 16, 2026

mheon enabled auto-merge January 16, 2026 20:28

Add podman machine os upgrade command #27886

Are you sure you want to change the base?

Add podman machine os upgrade command #27886

Uh oh!

Conversation

baude commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Does this PR introduce a user-facing change?

Uh oh!

baude commented Jan 9, 2026

Uh oh!

packit-as-a-service bot commented Jan 9, 2026

Uh oh!

ashley-cui left a comment • 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!

packit-as-a-service bot commented Jan 13, 2026

Uh oh!

ashley-cui commented Jan 14, 2026

Uh oh!

Uh oh!

TomSweeneyRedHat commented Jan 14, 2026

Uh oh!

l0rd left a comment

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!

mtrmac left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mtrmac left a comment

Choose a reason for hiding this comment

Uh oh!

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!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mheon commented Jan 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

baude commented Jan 9, 2026 •

edited

Loading

ashley-cui left a comment •

edited

Loading