From f4138d3599bce78631eed79d0944bc47ccde3244 Mon Sep 17 00:00:00 2001 From: Brent Baude Date: Fri, 30 Jan 2026 13:09:40 -0600 Subject: [PATCH] add bootc transports to os-apply now that we use `bootc switch` for changing out-of-band updates, we can consider also using some of their supported transports. * containers-storage * oci * oci-archive * registry RUN-3963 Signed-off-by: Brent Baude --- cmd/podman/machine/os/apply.go | 10 +- .../markdown/podman-machine-os-apply.1.md | 45 +++++- pkg/machine/os/ostree.go | 87 +++++++++- pkg/machine/os/ostree_test.go | 148 ++++++++++++++++++ 4 files changed, 279 insertions(+), 11 deletions(-) diff --git a/cmd/podman/machine/os/apply.go b/cmd/podman/machine/os/apply.go index da011c29a1..45ccdfe540 100644 --- a/cmd/podman/machine/os/apply.go +++ b/cmd/podman/machine/os/apply.go @@ -12,14 +12,18 @@ import ( ) var applyCmd = &cobra.Command{ - Use: "apply [options] IMAGE [NAME]", + Use: "apply [options] URI [NAME]", Short: "Apply an OCI image to a Podman Machine's OS", Long: "Apply custom layers from a containerized Fedora CoreOS OCI image on top of an existing VM", PersistentPreRunE: validate.NoOp, Args: cobra.RangeArgs(1, 2), RunE: apply, - ValidArgsFunction: common.AutocompleteImages, - Example: `podman machine os apply myimage`, + ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]cobra.Completion, cobra.ShellCompDirective) { + images, _ := common.AutocompleteImages(cmd, args, toComplete) + // We also accept an URI so ignore ShellCompDirectiveNoFileComp and use the default one instead to get file paths completed by the shell. + return images, cobra.ShellCompDirectiveDefault + }, + Example: `podman machine os apply myimage`, } var restart bool diff --git a/docs/source/markdown/podman-machine-os-apply.1.md b/docs/source/markdown/podman-machine-os-apply.1.md index 35a5536b68..0179bcef69 100644 --- a/docs/source/markdown/podman-machine-os-apply.1.md +++ b/docs/source/markdown/podman-machine-os-apply.1.md @@ -4,7 +4,7 @@ podman\-machine\-os\-apply - Apply an OCI image to a Podman Machine's OS ## SYNOPSIS -**podman machine os apply** [*options*] *image* [vm] +**podman machine os apply** [*options*] *uri* [vm] ## DESCRIPTION @@ -19,7 +19,16 @@ customized distribution and cannot be updated with this command. Note: WSL-based machines are upgradable by using the `podman machine ssh ` command followed by `sudo dnf update`. This can, however, result in unexpected results in Podman client and server version differences. -The applying of the OCI image is done by a command called `bootc`. +The applying of the OCI image is done by a command called `bootc` and specifically `bootc switch`. By default, this command +takes an OCI registry image reference like `quay.io/custom/machine-os:latest`. However, `bootc` also +understands references with different transports. At present, Podman will support the following transports: + +* containers-storage +* oci +* oci-archive +* registry + +Examples for these transports in URI form are provided below. Podman machine images are stored as OCI images at `quay.io/podman/machine-os`. When applying an image using this command, the fully qualified OCI reference name must be used including tag where the tag is the @@ -47,15 +56,37 @@ bootable OCI image. Note: This may result in having a newer Podman version inside the machine than the client. Unexpected results may occur. -Update the default Podman machine to the most recent Podman 6.1 bootable -OCI image. +Apply a new custom operating system from an OCI bootable image on quay. ``` -$ podman machine os apply quay.io/podman/machine-os:6.1 +$ podman machine os apply quay.io/custom/machine-os:latest ``` -Update the specified Podman machine to latest Podman 6.1 bootable OCI image. +Apply a new custom operating system to a specific machine from an OCI bootable image on quay. ``` -$ podman machine os apply quay.io/podman/machine-os:6.1 mymachine +$ podman machine os apply quay.io/custom/machine-os:latest mymachine +``` + +Apply a new custom operating system that was pulled or built on your existing machine by the unprivileged user. +Note the use of brackets around the path because this command is run by the root user. +``` +$ podman machine os apply containers-storage:[/home/core/.local/share/containers/storage]localhost/mycustomimage:latest +``` + +Apply a new custom operating system that was pulled or built on your existing machine by the privileged user. Note that +because a privileged user built or pulled the image, `bootc` will resolve that users storage and the path +is not needed. +``` +$ podman machine os apply containers-storage:localhost/mycustomimage:latest +``` + +Apply a new custom operating system from an OCI archive in tar form. +``` +$ podman machine os apply oci-archive:/tmp/oci-image.tar +``` + +Apply a new custom operating system from an OCI formatted directory. +``` +$ podman machine os apply oci:/tmp/oci-image/ ``` ## SEE ALSO diff --git a/pkg/machine/os/ostree.go b/pkg/machine/os/ostree.go index 37d33f50a2..176a19d8a3 100644 --- a/pkg/machine/os/ostree.go +++ b/pkg/machine/os/ostree.go @@ -8,6 +8,7 @@ import ( "fmt" "os" "os/exec" + "strings" "github.com/blang/semver/v4" "github.com/opencontainers/go-digest" @@ -16,6 +17,7 @@ import ( "go.podman.io/image/v5/docker/reference" "go.podman.io/image/v5/image" "go.podman.io/image/v5/manifest" + "go.podman.io/image/v5/transports/alltransports" "go.podman.io/image/v5/types" ) @@ -27,7 +29,17 @@ type OSTree struct{} // is pulled from an OCI registry. We simply pass the user // input to bootc without any manipulation. func (dist *OSTree) Apply(image string, _ ApplyOptions) error { - cli := []string{"bootc", "switch", image} + t, pathOrImageRef, err := parseApplyInput(image) + if err != nil { + return err + } + cli := []string{"bootc", "switch"} + // registry is the default transport and therefore not + // necessary + if t != "registry" { + cli = append(cli, "--transport", t) + } + cli = append(cli, pathOrImageRef) cmd := exec.Command("sudo", cli...) cmd.Stdout = os.Stdout cmd.Stderr = os.Stderr @@ -185,3 +197,76 @@ func printJSON(out UpgradeOutput) error { fmt.Println(string(b)) return nil } + +// parseApplyInput takes well known OCI references and splits them up. this +// function should only be used to deal with bootc transports. podman takes +// the entire reference as an oci reference but bootc requires we use +// --transport if the default transport is not used. also, bootc's default +// transport is "registry" which mimics docker in the way it is handled. +func parseApplyInput(arg string) (string, string, error) { + var ( + containersStorageTransport = "containers-storage" + dockerTransport = "docker" + ociArchiveTransport = "oci-archive" + ociTransport = "oci" + registryTransport = "registry" + ) + + imgRef, err := alltransports.ParseImageName(arg) + if err == nil { + transportName := imgRef.Transport().Name() + if imgRef.DockerReference() != nil { + // bootc docs do not show the docker transport, but the + // code apparently does handle it and because docker is + // a well-known transport, we do as well, but we change + // it to registry for convenience. + if transportName == dockerTransport { + transportName = registryTransport + } + // docker://quay.io/fedora/fedora-bootc:40 + return transportName, imgRef.DockerReference().String(), nil + } + + imagePath := imgRef.StringWithinTransport() + if transportName == ociTransport { //nolint:staticcheck + // oci:/tmp/oci-image + imagePath, _, _ = strings.Cut(imagePath, ":") + } else if transportName == ociArchiveTransport { + // oci-archive:/tmp/myimage.tar + imagePath = strings.TrimSuffix(imagePath, ":") + } + return transportName, imagePath, nil + } + + // quay.io/fedora/fedora-bootc:40 + if _, err := reference.ParseNamed(arg); err == nil { + return registryTransport, arg, nil + } + + // registry://quay.io/fedora/fedora-bootc:40 + afterReg, hasRegistry := strings.CutPrefix(arg, registryTransport+"://") + if hasRegistry { + return registryTransport, afterReg, nil + } + + // oci-archive:/var/tmp/fedora-bootc.tar + // oci-archive:/mnt/usb/images/myapp.tar + afterOCIArchive, hasOCIArchive := strings.CutPrefix(arg, ociArchiveTransport+":") + if hasOCIArchive { + return ociArchiveTransport, afterOCIArchive, nil + } + + // oci:/tmp/oci-image + // oci:/var/mnt/usb/bootc-image + afterOCI, hasOCI := strings.CutPrefix(arg, ociTransport+":") + if hasOCI { + return ociTransport, afterOCI, nil + } + // containers-storage:/home/user:localhost/fedora-bootc:latest + afterCS, hasCS := strings.CutPrefix(arg, containersStorageTransport+":") + if hasCS { + return containersStorageTransport, afterCS, nil + } + + return "", "", fmt.Errorf("unknown transport %q given", arg) +} diff --git a/pkg/machine/os/ostree_test.go b/pkg/machine/os/ostree_test.go index cb9b948fe2..61c842b4f0 100644 --- a/pkg/machine/os/ostree_test.go +++ b/pkg/machine/os/ostree_test.go @@ -89,3 +89,151 @@ func Test_compareMajorMinor(t *testing.T) { }) } } + +func Test_parseApplyInput(t *testing.T) { + type args struct { + arg string + } + tests := []struct { + name string + args args + want string + want1 string + wantErr bool + }{ + { + name: "bare registry reference with tag", + args: args{arg: "quay.io/fedora/fedora-bootc:40"}, + want: "registry", + want1: "quay.io/fedora/fedora-bootc:40", + wantErr: false, + }, + { + name: "docker transport with tag", + args: args{arg: "docker://quay.io/fedora/fedora-bootc:40"}, + want: "registry", + want1: "quay.io/fedora/fedora-bootc:40", + wantErr: false, + }, + { + name: "docker transport with digest", + args: args{arg: "docker://quay.io/podman/stable@sha256:9cca0703342e24806a9f64e08c053dca7f2cd90f10529af8ea872afb0a0c77d4"}, + want: "registry", + want1: "quay.io/podman/stable@sha256:9cca0703342e24806a9f64e08c053dca7f2cd90f10529af8ea872afb0a0c77d4", + wantErr: false, + }, + { + name: "registry transport with tag", + args: args{arg: "registry://quay.io/fedora/fedora-bootc:40"}, + want: "registry", + want1: "quay.io/fedora/fedora-bootc:40", + wantErr: false, + }, + { + name: "registry transport with digest", + args: args{arg: "registry://quay.io/podman/stable@sha256:9cca0703342e24806a9f64e08c053dca7f2cd90f10529af8ea872afb0a0c77d4"}, + want: "registry", + want1: "quay.io/podman/stable@sha256:9cca0703342e24806a9f64e08c053dca7f2cd90f10529af8ea872afb0a0c77d4", + wantErr: false, + }, + { + name: "registry transport with port", + args: args{arg: "registry://localhost:5000/myapp:latest"}, + want: "registry", + want1: "localhost:5000/myapp:latest", + wantErr: false, + }, + { + name: "oci transport var path", + args: args{arg: "oci:/var/mnt/usb/bootc-image"}, + want: "oci", + want1: "/var/mnt/usb/bootc-image", + wantErr: false, + }, + { + name: "oci transport opt path", + args: args{arg: "oci:/opt/images/mylayout"}, + want: "oci", + want1: "/opt/images/mylayout", + wantErr: false, + }, + { + name: "oci transport tmp path", + args: args{arg: "oci:/tmp/oci-image"}, + want: "oci", + want1: "/tmp/oci-image", + wantErr: false, + }, + { + name: "oci transport with reference", + args: args{arg: "oci:/path/to/oci-dir:myref"}, + want: "oci", + want1: "/path/to/oci-dir:myref", + wantErr: false, + }, + { + name: "oci-archive transport tmp tar", + args: args{arg: "oci-archive:/tmp/myimage.tar"}, + want: "oci-archive", + want1: "/tmp/myimage.tar", + wantErr: false, + }, + { + name: "oci-archive transport mnt path", + args: args{arg: "oci-archive:/mnt/usb/images/myapp.tar"}, + want: "oci-archive", + want1: "/mnt/usb/images/myapp.tar", + wantErr: false, + }, + { + name: "oci-archive transport with reference", + args: args{arg: "oci-archive:/home/user/archives/image.tar:myref"}, + want: "oci-archive", + want1: "/home/user/archives/image.tar:myref", + wantErr: false, + }, + { + name: "containers-storage transport with tag", + args: args{arg: "containers-storage:quay.io/podman/machine-os:6.0"}, + want: "containers-storage", + want1: "quay.io/podman/machine-os:6.0", + wantErr: false, + }, + { + name: "containers-storage transport with graph root", + args: args{arg: "containers-storage:[/home/core/.local/share/containers/storage]quay.io/podman/machine-os:6.0"}, + want: "containers-storage", + want1: "[/home/core/.local/share/containers/storage]quay.io/podman/machine-os:6.0", + wantErr: false, + }, + { + name: "good reference bad transport", + args: args{"foobar://quay.io/podman/machine-os:6.0"}, + want: "", + want1: "", + wantErr: true, + }, + { + name: "similar name but incorrect transport", + args: args{"oci-dir:/foo/bar/bar.tar"}, + want: "", + want1: "", + wantErr: true, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got, got1, err := parseApplyInput(tt.args.arg) + if (err != nil) != tt.wantErr { + t.Errorf("parseApplyInput() error = %v, wantErr %v", err, tt.wantErr) + return + } + if got != tt.want { + t.Errorf("parseApplyInput() got = '%v', want %v", got, tt.want) + } + if got1 != tt.want1 { + t.Errorf("parseApplyInput() got1 = '%v', want %v", got1, tt.want1) + } + }) + } +}