Images#

Prebuilt Disk Images with Bootc OCI Containers#

This section will rely on Eclipse SDV AutoSD’s integration project: https://github.com/eclipse-autosd/eclipse-autosd.

Eclipse S-CORE module owners and developers do not need to build an image from scratch to test their applications, nor do they need to download exotic tooling to do so as well.

The building framework and workflow will rely on using OCI container images, built from Bazel, and Bootc (Bootcable Containers). The later , which is used in AutoSD, allows users to manage OS / Host modification from an OCI container image (as long as it is built from an base bootc AutoSD image).

The basic workflow/setup is:

Build your target(s) - binaries, libraries, scripts, etc
Create a syroot tarball with the previous artifacts
Pull a base AutoSD bootc image for a given platform (QEMU, RPI4, etc)
Build a new OCI image adding the generated tarball as an OCI layer on top of the base AutoSD one
Download an existing disk image (.qcow2, .img)
Apply the new deployment using the bootc CLI and the new OCI image
Reboot and test changes

Step 1: Bootc Image Definition#

The first step is to setup Bazel (MODULE.bazel) to fetch a prexisting Bootc container image:

module(name = "esdv_autosd_sample", version = "0.0.1")

bazel_dep(name = "rules_pkg", version = "1.0.1")

bazel_dep(name = "rules_oci", version = "2.3.1")
git_override(
    module_name = "rules_oci",
    remote = "https://github.com/bazel-contrib/rules_oci.git",
    tag = "v2.3.1",
)

oci = use_extension("@rules_oci//oci:extensions.bzl", "oci")
oci.pull(
    name = "eclipse_autosd_qemu",
    image = "ghcr.io/eclipse-autosd/eclipse-autosd-bootc-qemu",
    tag = "latest",
    platforms = ["linux/amd64"],
)
use_repo(
    oci,
    "eclipse_autosd_qemu",
)

Step 2: Tarball + Bootc Image#

The next step is to build Bazel targets and archive the generated artifacts/files into a tarball. This tarball can be used to created a new OCI image, using the previous step’s image as the parent one:

load("@rules_pkg//pkg:pkg.bzl", "pkg_tar")
load("@rules_oci//oci:defs.bzl", "oci_load", "oci_image")

filegroup(
    name = "sample_systemd_service",
    srcs = ["files/sample.service"],
)

pkg_tar(
    name = "sample_systemd_service_tar",
    srcs = [
        ":sample_systemd_service",
    ],
    symlinks = {
        "/etc/systemd/system/default.target.wants/sample.service": "/etc/systemd/system/sample.service",
    },
    package_dir = "/etc/systemd/system",
)

pkg_tar(
    name = "sample_tar",
    srcs = [
        "//src:sample",
    ],
    package_dir = "/usr/bin",
)

oci_image(
    name = "sample_image",
    base = "@eclipse_autosd_qemu",
    tars = [
      ":sample_tar",
      ":sample_systemd_service_tar",
    ],
)

You can then generated an oci archive (.oci file) or push it to a OCI regisry, such as Docker Hub or Quay.io.

Step 3: Deploying Changes with Bootc Switch#

The last step is to import and apply changes from the new container image into an exiting AutoSD one.

You can either build your own AutoSD image or using an existing one from here: https://download.eclipse.org/autosd/disk-images/.

The rest of this section will assume the usage the QEMU image.

Once downloaded, you can run the AutoSD QEMU image, then you will need to apply the changes from the new bootc image over ssh.

If you pushed your image to a container register run the following command over ssh:

$ bootc switch $my_image_url
$ systemctl reboot

If you generated a, oci archive, you need to upload that file with scp and run:

$ bootc switch --transport oci-archive $path_to_file
$ system reboot

Bootc will apply all the missing/new layers into the host machine from the specified OCI Bootc image: which includes all the artifacts generated by Bazel. A reboot is needed in order for the new file system changes to take place.

Building Disk Images with Bazel#

It’s possible to build AutoSD disk images (QCOW2, VHD, and raw) using Bazel. The os_autosd module needs to be used as a Bazel direct dependency to do so.

The Bazel rule uses automotive-image-builder(AIB), a tool provided by the CentOS Automotive SIG to build AutoSD images.

NOTE: AIB does not support cross-compilation.

NOTE: The list of available distros to use is available at: https://gitlab.com/CentOS/automotive/src/automotive-image-builder/-/tree/main/distro?ref_type=heads

Bazel Rules#

aib_script#

aib_script(
  name = "aib_build_script_gen",
  oci_image = "quay.io/centos-sig-automotive/automotive-image-builder:latest",
  oci_runtime = "podman"
)

aib_script(
  name = "aib_build_script_static",
  script_path = ":my_aib_sh"
)

This rule will generate or use an existing shell script to invoke Automotive Image Builder, the rule itself runs an OCI container using this image: :code: quay.io/centos-sig-automotive/automotive-image-builder:latest.

field	Required	Default Value	Description
script_path	false	null	An optional label to point to an existing aib script (it will generate a new one if omitted)
oci_image	false	quay.io/centos-sig-automotive/automotive-image-builder:latest	OCI image to use in order to generate a new script
oci_runtime	false	podman	oci runtime (podman, docker, etc) in order to run the container that generates a new aib script

aib_build_builder#

aib_build_builder(
  name = "builder",
  arch = "x86_64",
  distro = "autosd10",
  aib_script = ":aib_build_script"
)

This rule will create an OCI archive (container image) that is used to generate a disk image (.qcow2, .img, etc).

field	Required	Default Value	Description
distro	false	autosd10	Target distro to use
arch	true	N/A	Target image architecture (x86_64, aarch64)
aib_script	true	N/A	The generated AIB script to use (usually from aib_script rule)

The archive name will use the following name format: score-autosd-$label_name-builder-$distro-$arch.oci.

aib_build_image#

 aib_build_image(
   name = "example",
   distro = "autosd10",
   target = "qemu",
   arch = "x86_64",
   aib_script = ":aib_build_script_gen",
   aib_define_files = [
       "//common_files:vars.yml",
       "//common_files:vars-devel.yml",
   ],
   aib_include_dirs = [
       ":image_files",
   ],
   aib_manifest = ":image.aib.yml",
   oci_runtime = "podman"
)

This rule will create an AutoSD bootc image (OCI archive as well), which contains all the packages and files of a disk image. This OCI archive will be used later to genereate a disk image file.

field	Required	Default Value	Description
distro	false	autosd10	Target distro to use
target	true	N/A	Target platform to build to (QEMU, specific HW, etc)
arch	true	N/A	Target image architecture (x86_64, aarch64)
aib_script	true	N/A	The generated AIB script to use (usually from aib_script rule)
aib_manifest	true	N/A	The AIB manifest file to use to generate an image
aib_define_files	false	[]	The list of variable files (YAML format) to be used by AIB
aib_include_dirs	false	[]	The list of directories to be includes when building an image, this is required to copy files to an AutoSD image
oci_runtime	false	podman	oci runtime (podman, docker, etc) in order to run the container that builds the OCI archive

The archive name will use the following name format: score-autosd-$label_name-bootc-$distro-$arch.oci

aib_build_disk#

 aib_build_disk(
   name = "mydisk",
   distro = "autosd10",
   target = "qemu",
   arch = "x86_64",
   aib_builder_image = ":builder",
   aib_bootc_image = ":example",
   aib_script = ":aib_build_script_gen",
   oci_runtime = "podman"
)

This rule will create a disk file (qcow2, img, etc) that can be fleshed into a platform, be it physical or virtual.

It requires the resulting artfiacts of the previous build rules: aib_build_builder and aib_build_image.

field	Required	Default Value	Description
distro	false	autosd10	Target distro to use
target	true	N/A	Target platform to build to (QEMU, specific HW, etc)
arch	true	N/A	Target image architecture (x86_64, aarch64)
aib_builder_image	true	N/A	Label used to create a builder image with aib_build_builder
aib_bootc_image	true	N/A	Label used to create a bootc image with aib_build_image
aib_script	true	N/A	The generates AIB script to use (usually from aib_script rule)
oci_runtime	false	podman	OCI runtime (podman, docker, etc) in order to run the container that builds the disk image

The disk image filename will use the following format: score-autosd-$label_name-$distro-$target-$arch.$ext. The file extension will be determined based on the target.

Full Example#

A full working example can be found at: https://github.com/eclipse-score/os_autosd/tree/main/examples/aib.

MODULE.bazel#

module(name="os_autosd_aib_example")

bazel_dep(name = "os_autosd", version = "0.0.0")
git_override(
  module_name = "os_autosd",
  remote = "https://github.com/eclipse-score/os_autosd.git",
  branch = "main",
)

BUILD.bazel#

load("@os_autosd//toolchain/aib:defs.bzl", "aib_script", "aib_build_builder", "aib_build_image", "aib_build_disk")

aib_script(
  name = "aib_build_script",
)

aib_build_builder(
  name = "builder",
  aib_script = ":aib_build_script",
  arch = "x86_64",
  distro = "autosd10",
)

filegroup(
  name = "image_files",
  srcs = glob(["image_files/**"]),
)

aib_build_image(
  name = "container-bootc",
  aib_define_files = [
      "//common_files:vars.yml",
      "//common_files:vars-devel.yml",
  ],
  aib_include_dirs = [
      ":image_files",
  ],
  aib_manifest = ":image.aib.yml",
  aib_script = "//images:aib_build_script",
  arch = "x86_64",
  distro = "autosd10",
  target = "qemu",
)

aib_build_disk(
  name = "container-disk",
  aib_bootc_image = ":container-bootc",
  aib_builder_image = "//images:builder",
  aib_script = "//images:aib_build_script",
  arch = "x86_64",
  distro = "autosd10",
  target = "qemu",
)

Building#

The following command will generate a disk file that can be used with QEMU:

$ bazel build //:container-disk

Known Limitations#

There are a few limitations when building AutoSD images from scratch using Bazel:

Podman/Docker usage is not isolated in Bazel’s sysroot, it uses the user’s container storage;
No cross architecture support: The generated image needs to match the architecture of the system that is running Bazel;
SELinux Rules generation: Bazel needs to be executed as root if an image is generating SELinux rules; pending patch to fix: https://github.com/osbuild/osbuild/pull/2552.