[pve-devel] [PATCH container v5 06/17] add support for OCI images as container templates

[Thomas Lamprecht]

Am 08.10.25 um 19:11 schrieb Filip Schauer:
> This aims to add basic support for the Open Container Initiative image
> format according to the specification. [0]
> 

This commit would do well with including some rationale and describing
trade offs and limitations, as do most others for that matter.

> [0] https://github.com/opencontainers/image-spec/blob/main/spec.md
> 
> Signed-off-by: Filip Schauer <f.schauer at proxmox.com>
> ---
> This patch depends on changes made to proxmox-perl-rs in patch 04/17.
> Meaning that proxmox-perl-rs needs to be bumped and a dependency & build
> dependency to libpve-rs-perl needs to be added to debian/control.
> 
> Changed since v3:
> * correctly handle case where $archive is '-'
> * replace unnecessary regex comparisons with `eq`
> * pass environment variables to container via `lxc.container.runtime`
> 
> Changed since v2:
> * rebase onto newest master (5a8b3f962f16) and re-format with
>   proxmox-perltidy
> * check whether archive is an OCI image before trying to parse it as one
> 
> Changed since v1:
> * fix entrypoint command missing Cmd
> * set lxc.signal.halt according to StopSignal (Fixes container shutdown)
> 
>  src/PVE/API2/LXC.pm | 94 ++++++++++++++++++++++++++++++++++++++++-----
>  1 file changed, 84 insertions(+), 10 deletions(-)
> 
> diff --git a/src/PVE/API2/LXC.pm b/src/PVE/API2/LXC.pm
> index e53b388..7a44547 100644
> --- a/src/PVE/API2/LXC.pm
> +++ b/src/PVE/API2/LXC.pm
> @@ -19,9 +19,11 @@ use PVE::Storage;
>  use PVE::RESTHandler;
>  use PVE::RPCEnvironment;
>  use PVE::ReplicationConfig;
> +use PVE::RS::OCI;
>  use PVE::LXC;
>  use PVE::LXC::Create;
>  use PVE::LXC::Migrate;
> +use PVE::LXC::Namespaces;
>  use PVE::GuestHelpers;
>  use PVE::VZDump::Plugin;
>  use PVE::API2::LXC::Config;
> @@ -536,19 +538,91 @@ __PACKAGE__->register_method({
>  
>                  eval {
>                      my $rootdir = PVE::LXC::mount_all($vmid, $storage_cfg, $conf, 1);
> +                    my $archivepath = '-';
> +                    $archivepath = PVE::Storage::abs_filesystem_path($storage_cfg, $archive)
> +                        if ($archive ne '-');
>                      $bwlimit = PVE::Storage::get_bandwidth_limit(
>                          'restore', [keys %used_storages], $bwlimit,
>                      );
> -                    print "restoring '$archive' now..\n"
> -                        if $restore && $archive ne '-';
> -                    PVE::LXC::Create::restore_archive(
> -                        $storage_cfg,
> -                        $archive,
> -                        $rootdir,
> -                        $conf,
> -                        $ignore_unpack_errors,
> -                        $bwlimit,
> -                    );
> +                    my $is_oci = 0;
> +
> +                    if ($restore && $archive ne '-') {
> +                        print "restoring '$archive' now..\n";
> +                    } elsif ($archivepath =~ /\.tar$/) {

Is there a reason that this got all "shoved" into the API method directly?
IMO it would be much nicer to have a method that takes care of this.

Btw. did you explore creating a PVE::LXC::Setup::OCI module where most of this
is handled, or at least encapsulated?

That way the OCI CTs could have a "real" ostype that makes it easy to detect
what's going on and allow implied special casing (like if network needs to be
set up by the host). It could also base of the "unmanaged" setup module, if
there's really nothing else to setup by default.

If there's a reason for why that is not a good solution it really needs to be
stated so in the commit message, as for me that'd be the obvious first route
to explore such an integration.

> +                        # Check whether archive is an OCI image
> +                        my ($has_oci_layout, $has_index_json, $has_blobs) = (0, 0, 0);
> +                        PVE::Tools::run_command(
> +                            ['tar', '-tf', $archivepath],
> +                            outfunc => sub {
> +                                my $line = shift;
> +                                $has_oci_layout = 1 if $line eq 'oci-layout';
> +                                $has_index_json = 1 if $line eq 'index.json';
> +                                $has_blobs = 1 if $line =~ /^blobs\//m;
> +                            },
> +                        );
> +
> +                        $is_oci = 1 if $has_oci_layout && $has_index_json && $has_blobs;
> +                    }
> +
> +                    if ($is_oci) {
> +                        # Extract the OCI image
> +                        my ($id_map, undef, undef) = PVE::LXC::parse_id_maps($conf);
> +                        my $oci_config = PVE::LXC::Namespaces::run_in_userns(
> +                            sub {
> +                                PVE::RS::OCI::parse_and_extract_image($archivepath, $rootdir);
> +                            },
> +                            $id_map,
> +                        );
> +
> +                        # Set the entrypoint and arguments if specified by the OCI image
> +                        my @init_cmd = ();
> +                        push(@init_cmd, @{ $oci_config->{Entrypoint} })
> +                            if $oci_config->{Entrypoint};
> +                        push(@init_cmd, @{ $oci_config->{Cmd} }) if $oci_config->{Cmd};
> +                        if (@init_cmd) {
> +                            my $init_cmd_str = shift(@init_cmd);
> +                            if (@init_cmd) {


> +                                $init_cmd_str .= ' ';
> +                                $init_cmd_str .= join(
> +                                    ' ',
> +                                    map {
> +                                        my $s = $_;
> +                                        $s =~ s/"/\\"/g;
> +                                        qq{"$_"}
> +                                    } @init_cmd,

Don't we got a shell quote method in PVE::Tools?

And FWIW, $_ is the implied default for lots of perl stuff, so the
following (untested!) should do the same:

map { s/"/\\"/g; qq{"$_"} } @init_cmd,

> +                                );
> +                            }
> +                            if ($init_cmd_str ne '/sbin/init') {
> +                                push @{ $conf->{lxc} }, ['lxc.init.cmd', $init_cmd_str];
> +
> +                                # An entrypoint other than /sbin/init breaks the tty console mode.
> +                                # This is fixed by setting cmode: console
> +                                $conf->{cmode} = 'console';
> +                            }
> +                        }
> +
> +                        push @{ $conf->{lxc} }, ['lxc.init.cwd', $oci_config->{WorkingDir}]

above would be slightly easier to follow as:

push $conf->{lxc}->@*, ...

> +                            if ($oci_config->{WorkingDir});
> +
> +                        if (my $envs = $oci_config->{Env}) {
> +                            for my $env (@{$envs}) {

rather: for my $env ($envs->@*) {

> +                                push @{ $conf->{lxc} }, ['lxc.environment.runtime', $env];

same as above w.r.t. ->@*

> +                            }
> +                        }
> +
> +                        my $stop_signal = $oci_config->{StopSignal} // "SIGTERM";
> +                        push @{ $conf->{lxc} }, ['lxc.signal.halt', $stop_signal];

same as above w.r.t. ->@*

> +                    } else {
> +                        # Not an OCI image, so restore it as an LXC image instead
> +                        PVE::LXC::Create::restore_archive(
> +                            $storage_cfg,
> +                            $archive,
> +                            $rootdir,
> +                            $conf,
> +                            $ignore_unpack_errors,
> +                            $bwlimit,
> +                        );
> +                    }
>  
>                      if ($restore) {
>                          print "merging backed-up and given configuration..\n";