# Image Builder: one disk image recipe, many Kubernetes infrastructure providers

> Image Builder is a Kubernetes SIG Cluster Lifecycle tool that builds virtual machine images across twenty infrastructure providers from a single set of templates, with the resulting images intended for Cluster API and other Kubeadm-based setups. It organises the build into defined phases so a user can select which ones to run, and it explicitly leaves upgrade semantics and hardware architecture out of scope.

**kubernetes-sigs/image-builder** — Tools for building Kubernetes disk images

- Repository: https://github.com/kubernetes-sigs/image-builder
- Website: https://image-builder.sigs.k8s.io/
- Stars: 551 · Forks: 507
- Language: Go Template
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/kubernetes-sigs-image-builder

## One image definition, twenty providers, and a matrix that tells you where the gaps are

Image Builder is a tool for building Kubernetes virtual machine images across multiple infrastructure providers. The resulting VM images are specifically intended to be used with Cluster API but should be suitable for other setups that rely on Kubeadm.

That last clause is the one to hold onto. Image Builder is not a Cluster API component in the sense of being part of its control plane. It is an image factory whose output Cluster API happens to consume, and the same image can be booted by anything that uses Kubeadm.

The provider list is long: ami, azure, digitalocean, gce, hcloud, huaweicloud, maas, nutanix, oci, openstack, outscale, ova, oxide, powervs, proxmox, qemu, raw, scaleway and vultr. That is nineteen providers plus the generic formats, and each one is a different way of turning a disk image into a bootable instance.

The OS coverage is the more interesting table, and the README is careful about what it claims. The table shows the currently provided operating systems for each provider built in to image builder, and it carries a note that this does not mean it is an exhaustive list of the operating systems each provider can support, only which are currently available within image-builder by default.

That caveat is the important sentence. A missing entry means the combination is not built in today, not that the provider cannot run that operating system. If your target combination shows nothing, that is a gap to raise with the maintainers rather than a dead end.

The three states in the table are worth distinguishing. An image marked as available and covered by CI tests is one the project tests automatically. An image marked as available for the provider is built but not covered by CI. And an image marked as not available is simply not provided for that provider.

So the CI-covered set is smaller than the available set, and that difference is the honest measure of how well tested any given combination is. The topic tag is k8s-sig-cluster-lifecycle, the primary language is recorded as Go Template, and the homepage is image-builder.sigs.k8s.io. The last push was on 2026-10-20 with v0.1.55 tagged on 2026-07-13.

## Phases are the unit of control, and that is the design decision

The goals section states three aims, and the third one is the one that shapes how the tool works.

The first goal is to build images for Kubernetes-conformant clusters in a consistent way across infrastructures, providers and business needs. That means installing all the software, containers and configuration needed by downstream tools such as Cluster API providers, so that they can pass conformance tests, and supporting the end user requirements to customize images for their business needs.

The second goal is to provide assurances in the binaries and configuration in images for the purposes of security auditing and operational stability. Two things follow from that: allowing introspection of artifacts, software versions and configurations in a given image, and supporting repeatable build processes where the same inputs of requested install versions result in the same installed binaries.

The third goal is to ensure that the creation of images is performed via well defined phases, where users could choose specific phases that they needed.

That last clause is the design in one sentence. Instead of a single monolithic image build, the work is broken into defined phases, and the user selects which ones to run. That is what makes the tool composable across nineteen providers: the phases are the shared part, and the provider-specific rendering sits underneath.

It also explains the customisation story. A business that needs a particular package, a particular kernel or a particular cloud-init configuration does not need a fork of the template set; it needs a phase that inserts that, and the phase model is how you ask for it.

The phase concept is where the deeper documentation lives. The README points at the project Book for in-depth documentation and links a Quick Start for Cluster API Image Builder, and the Makefile at the repository root shows that the book itself is a build artefact.

```bash
build-book: ## Build the image-builder book
	docs/book/build.sh
```

There is also a serve target that builds and serves the book with live reloading enabled, so the documentation is developed alongside the tool rather than written after it.

## The non-goals are explicit, and one of them rules out a common need

Most projects list goals and leave the boundaries implied. This one lists non-goals, and they are worth quoting in full because one of them excludes something people routinely expect an image tool to do.

The non-goals are: to provide upgrade or downgrade semantics, to provide guarantees that the software installed provides a fully functional system, and to prescribe the hardware architecture of the build system.

The first is the significant one. There is no upgrade or downgrade semantics. Image Builder builds images; it does not take an existing image and move it to a new set of package versions. If your requirement is a patched image for an existing fleet of nodes, that is outside what this tool does, and you would need a different approach such as rebuilding from the same inputs with updated versions and re-imaging, which is a different operational model.

The second non-goal is about guarantees and is worth reading carefully. The tool does not promise that the software it installs provides a fully functional system. In practice that means the image is a starting point that Cluster API then configures, and the image builder is not claiming that a booted node is a working cluster on its own.

The third is about the build machine. The tool does not prescribe the hardware architecture of the build system, which is a non-prescription rather than a prohibition. It means you can run the builder on whatever machine you have, including something that is not the same architecture as the image being produced, which matters when you are cross-building.

The toolchain in the repository reinforces that the project is template driven. The primary language is recorded as Go Template, and the images/ directory is where the per-provider and per-OS templates live, with the Makefile at the root delegating most targets to images/capi/Makefile.

The default goal of the root Makefile is help, and it prints its own list of targets plus the ones handled by the sub-Makefile, with a guard that rejects an invalid target name rather than passing something unexpected through to the image build.

## The build lives in images/capi and the root Makefile is a thin dispatcher

The Makefile is small enough to read in full, and the structure it reveals is the clearest description of how the project is organised.

The root Makefile has a default goal of help, and the help target prints the root targets and then delegates to the sub-Makefile.

```bash
	@echo Targets handled by images/capi/Makefile:
	@$(MAKE) -C images/capi help
```

Beyond help, the root file has four targets of its own. build-book runs docs/book/build.sh, serve-book runs the serve target in the book directory, update-release-docs runs images/capi/scripts/release-update-docs.sh to update the docs with a reference to the latest release version, and then there is a catch-all.

```bash
.DEFAULT:
	@$(if $(or $(findstring ',$@),$(findstring \,$@)),$(error Invalid target name: $@))
	@case '$@' in *[!a-zA-Z0-9_./-]*) echo 'Invalid target name' >&2; exit 1 ;; esac
	@$(MAKE) -C images/capi '$@'
```

Two things are happening in that catch-all. The first is validation: an invalid target name is an error rather than a silent pass-through, and the allowed character set excludes anything outside letters, digits, a low line, dot, slash and hyphen. The second is delegation: anything valid is forwarded to images/capi with the same target name.

So the root Makefile is a dispatcher and a guard, and the real build logic lives in images/capi/Makefile. The images/capi path is also what the top-level directory listing shows, alongside images/ for the rest of the image content, docs/ for the book, and the project governance files.

The presence of update-release-docs as a first-class target is worth noticing in a project with a long list of 0.1.x releases. The documentation carries release references, and there is an automated path to update them, which is the mechanism that keeps the book pointing at the right version rather than drifting.

There is also a RELEASE.md at the root, a cloudbuild.yaml for Google Cloud Build, and a netlify.toml for publishing the book as a site.

## Where Image Builder is the wrong tool

The first wrong-tool case is a fleet that needs in-place patching. Because upgrade and downgrade semantics are an explicit non-goal, Image Builder is not the tool for taking a running node image and moving it forward. Teams that need to ship a kernel fix or a package security update across existing nodes have to rebuild and re-image, or use a different mechanism entirely.

The second case is an operating system and provider combination that is not in the table. If your target does not appear, you are looking at writing the templates yourself, and the README's own caveat applies: the table lists what is built in by default, so an absent combination is a gap rather than a prohibition, but it is still a gap you are filling alone.

The third case is a project that wants the image to be a complete working system. The tool does not guarantee that the installed software provides a fully functional system, so if you are expecting the builder to produce a node you can boot and use, that expectation exceeds what the tool claims.

The fourth case is a cloud that is not on the list. Nineteen providers is a lot, but the list is fixed, and adding one means writing the provider-specific rendering that the phase model sits on top of.

On the CI coverage point, it is worth planning around rather than discovering. The matrix distinguishes images that are available from images that are available and covered by CI tests, and the CI-covered set is noticeably smaller. If your production runs on a combination that is only in the available column, you are relying on a combination the project builds but does not test automatically, which means you should be testing it yourself in your own pipeline.

On support, the project is organised in the usual Kubernetes SIG way. There are office hours on Mondays at 08:30 PT, biweekly, with meeting notes whose access is restricted to members of the sig-cluster-lifecycle mailing list and recordings published on YouTube. There is a Slack channel and a mailing list, participation is governed by the Kubernetes Code of Conduct, and the README points at the main Kubernetes community page for how to engage with the wider community. The repository also carries SECURITY_CONTACTS, a CONTRIBUTING.md and an OWNERS file with OWNERS_ALIASES.

On licence, Apache-2.0 with a LICENSE file at the root, which is the standard Kubernetes grant and imposes no copyleft obligation on a user. The one thing to note is that the images the tool produces carry their own licensing story, since they assemble third party operating system packages, and the goal of allowing introspection of artifacts, software versions and configurations in a given image exists precisely so that an auditor can answer that question.

## Conclusion

Image Builder suits a team running Cluster API across more than one cloud, because the point of the project is that a Kubernetes node image is defined once and rendered per provider, and the per-provider and per-OS support matrix tells you exactly which combinations exist today. It does not suit a team that needs in-place upgrades of existing images, since providing upgrade or downgrade semantics is an explicit non-goal. Before adopting, read the provider and OS matrix rather than assuming your operating system is covered, because the matrix states that the list is what is currently available by default and is not exhaustive of what each provider could support, and check the phase model in the book, since you choose which phases run.

## FAQ

### What is Kubernetes Image Builder?

Image Builder is a tool for building Kubernetes virtual machine images across multiple infrastructure providers. The resulting VM images are specifically intended to be used with Cluster API but are suitable for other setups that rely on Kubeadm.

### Which cloud providers does Image Builder support?

The provider and OS matrix in the README covers ami, azure, digitalocean, gce, hcloud, huaweicloud, maas, nutanix, oci, openstack, outscale, ova, oxide, powervs, proxmox, qemu, raw, scaleway and vultr. The table notes it shows what is currently available by default rather than an exhaustive list of what each provider could support.

### How does the phased build model work in Image Builder?

The creation of images is performed via well defined phases, and users can choose the specific phases they need. That is how the project supports one image definition rendered across nineteen providers while still letting a user customise what goes into the image.

### Does Image Builder support upgrading an existing VM image?

No, and that is listed as an explicit non-goal along with guaranteeing that the installed software provides a fully functional system and prescribing the hardware architecture of the build system. The project states that there are no upgrade or downgrade semantics.

### How do I build the Image Builder documentation?

Run make build-book at the repository root, which invokes docs/book/build.sh, or make serve-book to build and serve the book with live reloading. The root Makefile also delegates most other targets to images/capi/Makefile.

### What license is Image Builder released under?

Image Builder is released under the Apache 2.0 license, with the LICENSE file at the root of the repository. It is a project of the Kubernetes SIG Cluster Lifecycle group, with support through office hours, a Slack channel and a mailing list.

## Sources

- [kubernetes-sigs/image-builder on GitHub](https://github.com/kubernetes-sigs/image-builder)
- [License: Apache-2.0](https://github.com/kubernetes-sigs/image-builder/blob/main/LICENSE)
- [Project website](https://image-builder.sigs.k8s.io/)
- [README](https://github.com/kubernetes-sigs/image-builder/blob/main/README.md)
- [Releases](https://github.com/kubernetes-sigs/image-builder/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kubernetes-sigs-image-builder