image.md.tmpl

---
name: {{ .Name }}
description: {{ printf "%q" .Description }}
---

# Build and boot images

An image assembles built RPMs into a deliverable — a container or a bootable VM.
azldev drives the build from a kiwi-ng definition; the `.kiwi` file itself is
**upstream KIWI NG** ([docs](https://osinside.github.io/kiwi/)) and azldev does not
own its schema.

## Commands

Images are selected by their **name as a positional argument** (not `-p`).

| Task | Command |
| --- | --- |
| List images | `azldev image list` |
| Build an image (kiwi-ng) | `azldev image build <name>` |
| Boot an image in a QEMU VM | `azldev image boot <name>` |
| Run an image's tests | `azldev image test <name>` |
| Customize a pre-built image | `azldev image customize` |

`azldev image build` takes `--local-repo` / `--remote-repo` to add package sources and
`--arch` to target an architecture. When the selected distro version defines
`kiwi-config-override`, azldev passes it to KIWI with `--config`. These top-level
overrides have highest precedence. `azldev image boot` takes a built image name, or an
explicit `--image-path` / `--iso`. Confirm current flags with
`azldev image <command> --help` (there are more subcommands, e.g. `inject-files`).

## Registering an image

Images are declared under `[images.<name>]` (conventionally in an `images.toml`):

```toml
[images.container-base]
description = "Container base image"
definition = { type = "kiwi", path = "container-base/container-base.kiwi", profile = "core" }
architectures = ["x86_64", "aarch64"]

  [images.container-base.capabilities]
  container = true
  systemd = false

  [images.container-base.tests]
  test-suites = [{ name = "smoke" }]
```

- `definition.type` is `kiwi` (the only type today); `path` points at the `.kiwi` file;
  `profile` selects a kiwi profile (optional).
- `capabilities` are tri-state flags describing the image — `machine-bootable`,
  `container`, `systemd`, `runtime-package-management`. Set only the ones that apply.
- `architectures = ["x86_64", "aarch64"]` or one of the two is **required** on every
   image — there is no project-wide default to fall back to. It lists the architectures
   this image supports; `image build --arch` enforces it.
- `tests.test-suites` lists the test suites `azldev image test` runs.
- `publish.channels` lists the channels the image publishes to.

## The kiwi definition

The `.kiwi` file is upstream KIWI NG XML — azldev does not own its schema. It selects the
image type (container vs. VM), package lists, repositories, and boot configuration. See
the [KIWI NG documentation](https://osinside.github.io/kiwi/) for the format and elements.

Generated by `azldev docs agent`; do not hand-edit.