| Message ID | 20251212-image-container-v1-2-fb6586d06813@bootlin.com |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Document the image-container class | expand |
Hi Antonin, On 12/12/25 11:22 AM, Antonin Godard via lists.yoctoproject.org wrote: > Add documentation for the image-container class, which is a simple class > to generate an image suitable for creating a container. > Wrong order of patches, patch 1 uses the reflink created in this patch. EDIT: and this patch depends on patch 1 as well, so just merge both of them into one patch, they are related anyway. > This answers in part to questions asked in [YOCTO #14368]. > > Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> > --- > documentation/ref-manual/classes.rst | 51 ++++++++++++++++++++++++++++++++++++ > 1 file changed, 51 insertions(+) > > diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst > index a56a2f719..0097b7c46 100644 > --- a/documentation/ref-manual/classes.rst > +++ b/documentation/ref-manual/classes.rst > @@ -1258,6 +1258,57 @@ The :ref:`ref-classes-image_types` class also handles conversion and compression > :term:`IMAGE_FSTYPES`. This would also be similar for Virtual Box Virtual Disk > Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images. > > +.. _ref-classes-image-container: > + > +``image-container`` > +=================== > + > +The :ref:`ref-classes-image-container` class is meant to be inherited in > +:doc:`image </ref-manual/images>` recipes. It provides relevant settings to > +generate an image ready for use with an :wikipedia:`OCI > +<Open_Container_Initiative>`-compliant container management tool. such as....? podman and docker I assume, probably others. > + > +.. note:: > + > + This class does not build and install container management tools on the s/does not build and install/neither builds nor installs/ > + target. Support for this is available in the :yocto_git:`meta-virtualization s/Support for this is/Those tools are/? > + </meta-virtualization>` layer. > + > +An image recipe inheriting this class should also add the ``container`` image > +type to the :term:`IMAGE_FSTYPES` variable:: > + > + IMAGE_FSTYPES += "container" > + Isn't that done by image.bbclass already anyway? This class is automatically inherited when IMAGE_FSTYPES contains "container". c.f. https://git.openembedded.org/openembedded-core/tree/meta/classes-recipe/image.bbclass#n20 and https://git.openembedded.org/openembedded-core/tree/meta/classes-recipe/image.bbclass#n25 ? > +This image type does not deploy anything specific in :term:`DEPLOY_DIR_IMAGE`, > +but will simply add ``tar.bz2`` to the image types. > + > +You must also set the :term:`PREFERRED_PROVIDER` for the Linux kernel to No. You *can* (and you typically want). > +``linux-dummy`` in a :term:`configuration file`:: > + > + PREFERRED_PROVIDER_virtual/kernel = "linux-dummy" > +> +The ``linux-dummy`` recipes acts as a Linux kernel recipe but builds nothing. It > +is relevant in this case as a container image does not need to include a Linux > +kernel. Selecting it as the preferred provider for the kernel will also decrease > +build time. > + > +If desired, the :term:`IMAGE_CONTAINER_NO_DUMMY` variable can be set to "1" to > +skip the ``PREFERRED_PROVIDER_virtual/kernel`` check. > + Ah scratch that review on patch 1, linux-dummy isn't the default. > +After the image is built, the generated ``tar.bz2`` archive can be used in a > +container generation file. For example, to be used with :wikipedia:`Podman Being curious, where did you see "container generation file" being used? First time I see Containerfile/Dockerfile named this way. You could keep it but maybe specify that it's typically named Containerfile or Dockerfile so people know what we're talking about? Cheers, Quentin
Hi, On Fri Dec 12, 2025 at 1:07 PM CET, Quentin Schulz wrote: > Hi Antonin, > > On 12/12/25 11:22 AM, Antonin Godard via lists.yoctoproject.org wrote: >> Add documentation for the image-container class, which is a simple class >> to generate an image suitable for creating a container. >> > > Wrong order of patches, patch 1 uses the reflink created in this patch. > > EDIT: and this patch depends on patch 1 as well, so just merge both of > them into one patch, they are related anyway. Yeah, I thought I was being smart by making sure the order was right, turns out they should be merged together! >> This answers in part to questions asked in [YOCTO #14368]. >> >> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> >> --- >> documentation/ref-manual/classes.rst | 51 ++++++++++++++++++++++++++++++++++++ >> 1 file changed, 51 insertions(+) >> >> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst >> index a56a2f719..0097b7c46 100644 >> --- a/documentation/ref-manual/classes.rst >> +++ b/documentation/ref-manual/classes.rst >> @@ -1258,6 +1258,57 @@ The :ref:`ref-classes-image_types` class also handles conversion and compression >> :term:`IMAGE_FSTYPES`. This would also be similar for Virtual Box Virtual Disk >> Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images. >> >> +.. _ref-classes-image-container: >> + >> +``image-container`` >> +=================== >> + >> +The :ref:`ref-classes-image-container` class is meant to be inherited in >> +:doc:`image </ref-manual/images>` recipes. It provides relevant settings to >> +generate an image ready for use with an :wikipedia:`OCI >> +<Open_Container_Initiative>`-compliant container management tool. > > such as....? podman and docker I assume, probably others. > >> + >> +.. note:: >> + >> + This class does not build and install container management tools on the > > s/does not build and install/neither builds nor installs/ > >> + target. Support for this is available in the :yocto_git:`meta-virtualization > > s/Support for this is/Those tools are/? > >> + </meta-virtualization>` layer. >> + >> +An image recipe inheriting this class should also add the ``container`` image >> +type to the :term:`IMAGE_FSTYPES` variable:: >> + >> + IMAGE_FSTYPES += "container" >> + > > Isn't that done by image.bbclass already anyway? This class is > automatically inherited when IMAGE_FSTYPES contains "container". > > c.f. > https://git.openembedded.org/openembedded-core/tree/meta/classes-recipe/image.bbclass#n20 > and > https://git.openembedded.org/openembedded-core/tree/meta/classes-recipe/image.bbclass#n25 > ? > >> +This image type does not deploy anything specific in :term:`DEPLOY_DIR_IMAGE`, >> +but will simply add ``tar.bz2`` to the image types. >> + >> +You must also set the :term:`PREFERRED_PROVIDER` for the Linux kernel to > > No. You *can* (and you typically want). > >> +``linux-dummy`` in a :term:`configuration file`:: >> + >> + PREFERRED_PROVIDER_virtual/kernel = "linux-dummy" >> +> +The ``linux-dummy`` recipes acts as a Linux kernel recipe but builds > nothing. It >> +is relevant in this case as a container image does not need to include a Linux >> +kernel. Selecting it as the preferred provider for the kernel will also decrease >> +build time. >> + >> +If desired, the :term:`IMAGE_CONTAINER_NO_DUMMY` variable can be set to "1" to >> +skip the ``PREFERRED_PROVIDER_virtual/kernel`` check. >> + > > Ah scratch that review on patch 1, linux-dummy isn't the default. I haven't seen your review on patch 1 (locally or on lore.kernel.org), did you forget to send it? >> +After the image is built, the generated ``tar.bz2`` archive can be used in a >> +container generation file. For example, to be used with :wikipedia:`Podman > > Being curious, where did you see "container generation file" being used? Nowhere else, I made that up I guess. I'll reword this and mention Containerfile/Dockerfile. > First time I see Containerfile/Dockerfile named this way. You could keep > it but maybe specify that it's typically named Containerfile or > Dockerfile so people know what we're talking about? Thanks! Antonin
Hi, On Fri Dec 12, 2025 at 1:07 PM CET, Quentin Schulz wrote: > Hi Antonin, > > On 12/12/25 11:22 AM, Antonin Godard via lists.yoctoproject.org wrote: >> Add documentation for the image-container class, which is a simple class >> to generate an image suitable for creating a container. >> > > Wrong order of patches, patch 1 uses the reflink created in this patch. > > EDIT: and this patch depends on patch 1 as well, so just merge both of > them into one patch, they are related anyway. > >> This answers in part to questions asked in [YOCTO #14368]. >> >> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> >> --- >> documentation/ref-manual/classes.rst | 51 ++++++++++++++++++++++++++++++++++++ >> 1 file changed, 51 insertions(+) >> >> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst >> index a56a2f719..0097b7c46 100644 >> --- a/documentation/ref-manual/classes.rst >> +++ b/documentation/ref-manual/classes.rst >> @@ -1258,6 +1258,57 @@ The :ref:`ref-classes-image_types` class also handles conversion and compression >> :term:`IMAGE_FSTYPES`. This would also be similar for Virtual Box Virtual Disk >> Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images. >> >> +.. _ref-classes-image-container: >> + >> +``image-container`` >> +=================== >> + >> +The :ref:`ref-classes-image-container` class is meant to be inherited in >> +:doc:`image </ref-manual/images>` recipes. It provides relevant settings to >> +generate an image ready for use with an :wikipedia:`OCI >> +<Open_Container_Initiative>`-compliant container management tool. > > such as....? podman and docker I assume, probably others. > >> + >> +.. note:: >> + >> + This class does not build and install container management tools on the > > s/does not build and install/neither builds nor installs/ > >> + target. Support for this is available in the :yocto_git:`meta-virtualization > > s/Support for this is/Those tools are/? > >> + </meta-virtualization>` layer. >> + >> +An image recipe inheriting this class should also add the ``container`` image >> +type to the :term:`IMAGE_FSTYPES` variable:: >> + >> + IMAGE_FSTYPES += "container" >> + > > Isn't that done by image.bbclass already anyway? This class is > automatically inherited when IMAGE_FSTYPES contains "container". > > c.f. > https://git.openembedded.org/openembedded-core/tree/meta/classes-recipe/image.bbclass#n20 > and > https://git.openembedded.org/openembedded-core/tree/meta/classes-recipe/image.bbclass#n25 > ? Ah, so actually you're supposed to just add "container" to IMAGE_FSTYPES rather than inheriting the class. I wonder why this was designed like this rather than just a class inherit, it's not obvious/usual. I will instruct to only set IMAGE_FSTYPES then. Thanks, Antonin
diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index a56a2f719..0097b7c46 100644 --- a/documentation/ref-manual/classes.rst +++ b/documentation/ref-manual/classes.rst @@ -1258,6 +1258,57 @@ The :ref:`ref-classes-image_types` class also handles conversion and compression :term:`IMAGE_FSTYPES`. This would also be similar for Virtual Box Virtual Disk Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images. +.. _ref-classes-image-container: + +``image-container`` +=================== + +The :ref:`ref-classes-image-container` class is meant to be inherited in +:doc:`image </ref-manual/images>` recipes. It provides relevant settings to +generate an image ready for use with an :wikipedia:`OCI +<Open_Container_Initiative>`-compliant container management tool. + +.. note:: + + This class does not build and install container management tools on the + target. Support for this is available in the :yocto_git:`meta-virtualization + </meta-virtualization>` layer. + +An image recipe inheriting this class should also add the ``container`` image +type to the :term:`IMAGE_FSTYPES` variable:: + + IMAGE_FSTYPES += "container" + +This image type does not deploy anything specific in :term:`DEPLOY_DIR_IMAGE`, +but will simply add ``tar.bz2`` to the image types. + +You must also set the :term:`PREFERRED_PROVIDER` for the Linux kernel to +``linux-dummy`` in a :term:`configuration file`:: + + PREFERRED_PROVIDER_virtual/kernel = "linux-dummy" + +The ``linux-dummy`` recipes acts as a Linux kernel recipe but builds nothing. It +is relevant in this case as a container image does not need to include a Linux +kernel. Selecting it as the preferred provider for the kernel will also decrease +build time. + +If desired, the :term:`IMAGE_CONTAINER_NO_DUMMY` variable can be set to "1" to +skip the ``PREFERRED_PROVIDER_virtual/kernel`` check. + +After the image is built, the generated ``tar.bz2`` archive can be used in a +container generation file. For example, to be used with :wikipedia:`Podman +<Podman>` or :wikipedia:`Docker <Docker_(software)>`, a `container file +<https://docs.docker.com/reference/dockerfile/>`__ could contain the following +instructions: + +.. code-block:: dockerfile + + FROM scratch + ADD ./image-container-qemux86-64.rootfs.tar.bz2 / + ENTRYPOINT /bin/sh + +This is suitable to build a container using our generated root filesystem image. + .. _ref-classes-image-live: ``image-live``
Add documentation for the image-container class, which is a simple class to generate an image suitable for creating a container. This answers in part to questions asked in [YOCTO #14368]. Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> --- documentation/ref-manual/classes.rst | 51 ++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+)