mirror of
https://github.com/siderolabs/talos.git
synced 2025-10-28 15:01:13 +01:00
c08d797326
Update building-images.md. Signed-off-by: dhaines-quera <139260712+dhaines-quera@users.noreply.github.com> Signed-off-by: Andrey Smirnov <andrey.smirnov@siderolabs.com>
120 lines
4.1 KiB
Markdown
120 lines
4.1 KiB
Markdown
---
|
|
title: "Building Custom Talos Images"
|
|
description: "How to build a custom Talos image from source."
|
|
---
|
|
|
|
There might be several reasons to build Talos images from source:
|
|
|
|
* verifying the [image integrity]({{< relref "verifying-images" >}})
|
|
* building an image with custom configuration
|
|
|
|
## Checkout Talos Source
|
|
|
|
```bash
|
|
git clone https://github.com/siderolabs/talos.git
|
|
```
|
|
|
|
If building for a specific release, checkout the corresponding tag:
|
|
|
|
```bash
|
|
git checkout {{< release >}}
|
|
```
|
|
|
|
## Set up the Build Environment
|
|
|
|
See [Developing Talos]({{< relref "developing-talos" >}}) for details on setting up the buildkit builder.
|
|
|
|
## Architectures
|
|
|
|
By default, Talos builds for `linux/amd64`, but you can customize that by passing `PLATFORM` variable to `make`:
|
|
|
|
```bash
|
|
make <target> PLATFORM=linux/arm64 # build for arm64 only
|
|
make <target> PLATFORM=linux/arm64,linux/amd64 # build for arm64 and amd64, container images will be multi-arch
|
|
```
|
|
|
|
## Custom `PKGS`
|
|
|
|
When [customizing Linux kernel]({{< relref "customizing-the-kernel" >}}), the source for the [`siderolabs/pkgs`](https://github.com/siderolabs/pkgs) repository can
|
|
be overridden with:
|
|
|
|
* if you built and pushed only a custom `kernel` package, the reference can be overridden with `PKG_KERNEL` variable: `make <target> PKG_KERNEL=<registry>/<username>/kernel:<tag>`
|
|
* if any other single package was customized, the reference can be overridden with `PKG_<pkg>` (e.g. `PKG_IPTABLES`) variable: `make <target> PKG_<pkg>=<registry>/<username>/<pkg>:<tag>`
|
|
* if the full `pkgs` repository was built and pushed, the references can be overridden with `PKGS_PREFIX` and `PKGS` variables: `make <target> PKGS_PREFIX=<registry>/<username> PKGS=<tag>`
|
|
|
|
## Customizations
|
|
|
|
Some of the build parameters can be customized by passing environment variables to `make`, e.g. `GOAMD64=v1` can be used to build
|
|
Talos images compatible with old AMD64 CPUs:
|
|
|
|
```bash
|
|
make <target> GOAMD64=v1
|
|
```
|
|
|
|
## Building Kernel and Initramfs
|
|
|
|
The most basic boot assets can be built with:
|
|
|
|
```bash
|
|
make kernel initramfs
|
|
```
|
|
|
|
Build result will be stored as `_out/vmlinuz-<arch>` and `_out/initramfs-<arch>.xz`.
|
|
|
|
## Building Container Images
|
|
|
|
Talos container images should be pushed to the registry as the result of the build process.
|
|
|
|
The default settings are:
|
|
|
|
* `IMAGE_REGISTRY` is set to `ghcr.io`
|
|
* `USERNAME` is set to the `siderolabs` (or value of environment variable `USERNAME` if it is set)
|
|
|
|
The image can be pushed to any registry you have access to, but the access credentials should be stored in `~/.docker/config.json` file (e.g. with `docker login`).
|
|
|
|
Building and pushing the image can be done with:
|
|
|
|
```bash
|
|
make installer PUSH=true IMAGE_REGISTRY=docker.io USERNAME=<username> # ghcr.io/siderolabs/installer
|
|
make imager PUSH=true IMAGE_REGISTRY=docker.io USERNAME=<username> # ghcr.io/siderolabs/imager
|
|
```
|
|
|
|
The [local registry]({{< relref "developing-talos" >}}) running on `127.0.0.1:5005` can be used as well to avoid pushing/pulling over the network:
|
|
|
|
```bash
|
|
make installer PUSH=true REGISTRY=127.0.0.1:5005
|
|
```
|
|
|
|
When building `imager` container, by default Talos will include the boot assets for both `amd64` and `arm64` architectures, if building only for single architecture, specify `INSTALLER_ARCH` variable:
|
|
|
|
```bash
|
|
make imager INSTALLER_ARCH=targetarch PLATFORM=linux/amd64
|
|
```
|
|
|
|
## Building ISO
|
|
|
|
The [ISO image]({{< relref "../talos-guides/install/boot-assets" >}}) is built with the help of `imager` container image, by default `ghcr.io/siderolabs/imager` will be used with the matching tag:
|
|
|
|
```bash
|
|
make iso
|
|
```
|
|
|
|
The ISO image will be stored as `_out/talos-<arch>.iso`.
|
|
|
|
If ISO image should be built with the custom `imager` image, it can be specified with `IMAGE_REGISTRY`/`USERNAME` variables:
|
|
|
|
```bash
|
|
make iso IMAGE_REGISTRY=docker.io USERNAME=<username>
|
|
```
|
|
|
|
## Building Disk Images
|
|
|
|
The disk image is built with the help of `imager` container image, by default `ghcr.io/siderolabs/imager` will be used with the matching tag:
|
|
|
|
```bash
|
|
make image-metal
|
|
```
|
|
|
|
Available disk images are encoded in the `image-%` target, e.g. `make image-aws`.
|
|
Same as with ISO image, the custom `imager` image can be specified with `IMAGE_REGISTRY`/`USERNAME` variables.
|