edge-image-builder

Edge Image Builder (EIB)

Usage

EIB runs as a container. Some form of container runtime is needed, such as Podman.

The latest version of EIB (1.3.0) can be downloaded from the official OCI registry using the following command:

podman pull registry.suse.com/edge/3.4/edge-image-builder:1.3.0

Alternatively, EIB can be built from this repository. See the Building from Source section below.

Image Definition

For details on how to create the artifacts needed to build an image, see the Building Images guide.

Running EIB

The image configuration directory must be attached to the container at runtime. This serves as both the mechanism to introduce image definition files and provide a way to get the built image out of the container and onto the host machine.

Validating an image definition

The following example command attaches the image configuration directory and validates a definition:

podman run --rm -it -v $IMAGE_DIR:/eib \
$EIB_IMAGE \
validate --definition-file $DEFINITION_FILE

• -v - Used to mount a local directory (in this example, the value of $IMAGE_DIR) into the EIB container at /eib.
• --definition-file - Specifies which image definition file to build. The path to this file will be relative to the image configuration directory. If the definition file is in the root of the configuration directory, simply specify the name of the configuration file.
• --config-dir - (Optional) Specifies the image configuration directory. This path is relative to the running container, so its value must match the mounted volume. It defaults to /eib which matches the mounted volume $IMAGE_DIR:/eib in the example above.

Building an image

The following example command attaches the image configuration directory and builds an image:

podman run --rm -it -v $IMAGE_DIR:/eib \
$EIB_IMAGE \
build --definition-file $DEFINITION_FILE

NOTE: Image builds which involve package resolution must include the --privileged flag. Package resolution will be automatically performed when requesting package installation or configuring components which require it (e.g. Elemental, Kubernetes SELinux, etc.).

• -v - Used to mount a local directory (in this example, the value of $IMAGE_DIR) into the EIB container at /eib.
• --definition-file - Specifies which image definition file to build. The path to this file will be relative to the image configuration directory. If the definition file is in the root of the configuration directory, simply specify the name of the configuration file.
• --config-dir - (Optional) Specifies the image configuration directory. This path is relative to the running container, so its value must match the mounted volume. It defaults to /eib which matches the mounted volume $IMAGE_DIR:/eib in the example above.
• --build-dir - (Optional) If unspecified, EIB will create a _build directory under the image configuration directory for assembling/generating the components used in the build which will persist after EIB finishes. This may also be specified to another location within a mounted volume. The directory will contain subdirectories storing the respective artifacts of the different builds as well as cached copies of certain downloaded files.

Testing Images

For details on how to test the built images, see the Testing Guide.

Generating a Combustion Drive

The following example command attaches the configuration directory and generates a combustion drive:

podman run --rm -it --privileged -v $CONFIGURATION_DIR:/eib \
$EIB_IMAGE  \
generate \
--definition-file $DEFINITION_FILE  \
--arch $ARCH \
--output-type $OUTPUT_TYPE \
--output $OUTPUT_NAME

• -v - Used to mount a local directory (in this example, the value of $CONFIGURATION_DIR) into the EIB container at /eib.
• --definition-file - Specifies which definition file to generate. The path to this file will be relative to the configuration directory. If the definition file is in the root of the configuration directory, simply specify the name of the configuration file.
• --config-dir - (Optional) Specifies the configuration directory. This path is relative to the running container, so its value must match the mounted volume. It defaults to /eib which matches the mounted volume $CONFIGURATION_DIR:/eib in the example above.
• --arch - Must be x86_64 or aarch64.
• --output-type - Must be either iso or tar. Determines the type of file to be generated by EIB.
• --output - Indicates the name of the file that EIB will generate. This may only be a filename; the combustion drive will be written to the root of the configuration directory.

For details on generating the combustion configuration without needing a base image, see the Generating Combustion Drive guide.

Building from Source

Build the container (from the root of this project). The image tag eib:dev will be used in the Podman command examples above for the $EIB_IMAGE variable.

podman build -t eib:dev .