************************************
Building and Using a Container Image
************************************

Building a container image based on CoreOS is really easy. You have to set
the machine to either of the following value in the `local.conf` file:

- container-x64
- container-arm64
- container-arm32

.. hint::

    The machine can also be overwriting from the shell using
    `MACHINE=<machine> bitbake`

Then you can generate any image by running:

.. code-block:: sh

    $ bitbake <image>

As an example, you can build the `coreos-image-minimal` as an OCI container
for AMD64 machine with the following command:

.. code-block:: sh

    $ MACHINE=container-x64 bitbake coreos-image-minimal


This will generate a container tarball in the tar.gz format.

If you are using `podman`, you can import the container with:

.. code-block:: sh

    $ cd $BUILDDIR/tmp/deploy/images/container-x64
    $ podman import coreos-image-container-container-x64.tar.bz2
    Getting image source signatures
    Copying blob 46c0b1c53d42 [--------------------------------------] 0.0b / 0.0b
    Copying config 051856498a done  
    Writing manifest to image destination
    Storing signatures
    051856498a59e0ae6349492539efaf915a33dd73e7a54ce9683b0414d1481fae

Then you can use start any program included in the image with:

.. code-block:: sh

    $ podman run <PODMAN_ARGS> <IMAGE_ID> <COMMAND> <COMMAND_ARGS>

To run an interactive shell, you can use:

.. code-block:: sh

    $ podman run -i <IMAGE_ID> ash --i
    / # 

The `<IMAGE_ID>` should be copied from the output of `podman import`. In this
example, it was
`051856498a59e0ae6349492539efaf915a33dd73e7a54ce9683b0414d1481fae`.

You are now inside the container, try the following command:

.. code-block:: sh

    / # cat /etc/os-release
    ID=belden-coreos
    NAME="Belden CoreOS"
    VERSION="0.0.1-feat/oci-image+75cf54e4b54b713d8ebeafddd122aeb615715ef9 (kirkstone)"
    VERSION_ID=0.0.1-feat/oci-image-75cf54e4b54b713d8ebeafddd122aeb615715ef9
    PRETTY_NAME="Belden CoreOS 0.0.1-feat/oci-image+75cf54e4b54b713d8ebeafddd122aeb615715ef9 (kirkstone)"
    DISTRO_CODENAME="kirkstone"

.. note::

    Image generated using any container machines doesn't include the Linux
    kernel neither many system component that are usually not used on a container
    like SystemD or udev. This is done inside the machine configuration by
    settings all the `VIRTUAL_RUNTIME_<component>` to an empty string.

    Any of these system component can be added to the image if needed, by adding
    them by their real name (instead of using any `VIRTUAL_RUNTIME_` variables)
    in the `IMAGE_INSTALL` variables.
