Membangun Image Fedora IoT Kustom dengan image-builder

image-builder adalah alat baris perintah untuk membangun image sistem operasi kustom untuk Fedora, CentOS, dan RHEL. Panduan ini menjelaskan cara menggunakan image-builder untuk membuat image Fedora IoT yang dikustomisasi dengan pilihan paket, konfigurasi pengguna, dan pengaturan Anda sendiri.

Untuk image Fedora IoT pra-bangun tanpa kustomisasi, lihat Mendapatkan Image.

Memasang image-builder

Untuk memasang image-builder di Fedora:

$ sudo dnf install image-builder ostree

Jenis Image Fedora IoT yang Tersedia

image-builder mendukung beberapa jenis image khusus IoT untuk arsitektur x86_64 dan aarch64:

  • iot-commit - tarball komit OSTree (fondasi untuk image kustom)

  • iot-installer - ISO pemasang Anaconda untuk instalasi interaktif

  • iot-simplified-installer - pemasang tanpa sentuhan menggunakan FDO atau Ignition

  • iot-raw-xz - image disk raw terkompresi untuk perangkat fisik (mis., Raspberry Pi)

  • iot-qcow2 - image disk QCOW2 untuk mesin virtual

  • iot-container - kontainer OCI dengan komit OSTree

  • iot-bootable-container - image kontainer yang dapat di-boot

Untuk menampilkan semua jenis image IoT yang tersedia:

$ image-builder list | grep iot

Membangun Image Fedora IoT Kustom

Alur kerja yang umum untuk membuat image Fedora IoT kustom adalah:

  1. Buat blueprint yang menjelaskan kustomisasi Anda

  2. Bangun komit OSTree kustom dengan perubahan Anda

  3. Sajikan komit OSTree secara lokal

  4. Bangun media instalasi atau image disk dari komit kustom Anda

Langkah 1: Membuat Blueprint

Blueprint adalah file TOML yang mendeskripsikan kustomisasi untuk image Anda. Blueprint memungkinkan Anda untuk:

  • Menambahkan atau menghapus paket

  • Mengonfigurasi pengguna dan grup

  • Menyiapkan kunci SSH

  • Mengonfigurasi pengaturan sistem

Buat file blueprint (contoh: iot-custom.toml):

name = "iot-custom"
description = "Custom Fedora IoT Image"
version = "0.0.1"

[[packages]]
name = "vim-enhanced"

[[packages]]
name = "htop"

[[packages]]
name = "tmux"

[[customizations.user]]
name = "admin"
description = "Admin User"
password = "$6$rounds=4096$saltsalt$encrypted_password_hash"
groups = ["wheel"]

[[customizations.sshkey]]
user = "admin"
key = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExample admin@workstation"
Hasilkan kata sandi terenkripsi dengan openssl passwd -6 (akan meminta kata sandi secara interaktif)

Langkah 2: Membangun Komit OSTree Kustom

Bangun tarball komit OSTree dengan kustomisasi Anda. Gunakan pola penamaan ref resmi (fedora/stable, fedora/devel, atau fedora/rawhide):

$ sudo image-builder build iot-commit \
  --distro fedora-43 \
  --blueprint iot-custom.toml \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./iot-commit-output

# Catatan Untuk aarch64 gunakan `fedora/stable/aarch64/iot`

Ini akan membuat tarball yang berisi komit OSTree yang sudah Anda kustomisasi.

Langkah 3: Menyiapkan Repositori OSTree Lokal

Ekstrak tarball komit dan sajikan repositori OSTree:

$ tar -xf ./iot-commit-output/*.tar
$ mv repo ostree-repo
$ cd ostree-repo
$ python3 -m http.server 8000

Tarball tersebut berisi sebuah direktori repo/ dengan repositori OSTree lengkap. Untuk menjalankan server HTTP di latar belakang, tambahkan & di akhir:

$ python3 -m http.server 8000 &

Repositori OSTree kustom Anda sekarang tersedia di http://localhost:8000

Untuk memverifikasi bahwa repositori sudah disiapkan dengan benar:

$ ostree --repo=./ostree-repo refs
$ curl http://localhost:8000/refs/heads/fedora/stable/x86_64/iot

Membangun Image dari OSTree Kustom Anda

Dengan komit OSTree kustom Anda yang disajikan secara lokal, Anda kini dapat membangun berbagai jenis image.

Membangun ISO Installer

Buat ISO installer Anaconda yang akan memasang Fedora IoT yang telah Anda kustomisasi:

$ sudo image-builder build iot-installer \
  --distro fedora-43 \
 --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./images

Membangun Installer yang Disederhanakan

Installer yang disederhanakan menyediakan penyediaan tanpa sentuhan menggunakan FDO atau Ignition:

$ sudo image-builder build iot-simplified-installer \
  --distro fedora-43 \
  --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./images

Lihat Mem-boot Simplified Provisioner untuk detail lebih lanjut.

Membangun Image Disk Raw

Untuk komputer papan tunggal seperti Raspberry Pi, buat image disk raw terkompresi:

$ sudo image-builder build iot-raw-xz \
  --distro fedora-43 \
  --arch aarch64 \
  --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/aarch64/iot \
  --output-dir ./images

Image ini dapat ditulis langsung ke kartu SD atau media penyimpanan lainnya.

Membangun Image QCOW2 untuk VM

Untuk pengujian di mesin virtual:

$ sudo image-builder build iot-qcow2 \
  --distro fedora-43 \
  --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./images

Membangun Image Kontainer

Buat kontainer OCI dengan komit OSTree Anda:

$ sudo image-builder build iot-container \
  --distro fedora-43 \
 --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./images

Buat image kontainer yang dapat di-boot untuk alur kerja modern yang native-kontainer:

$ sudo image-builder build iot-bootable-container \
  --distro fedora-43 \
  --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./images

Lihat Fedora IoT Bootc untuk informasi lebih lanjut tentang kontainer yang dapat di-boot.

Menyajikan Repositori OSTree Anda ke Mesin Lain

Untuk membuat repositori OSTree kustom Anda tersedia bagi mesin lain di jaringan Anda:

$ cd ostree-repo
$ python3 -m http.server 8000 --bind 0.0.0.0 &
& menjalankan server di latar belakang. Untuk menghentikannya nanti, gunakan pkill -f "http.server 8000"

Lalu gunakan alamat IP mesin Anda ketika membangun image di sistem lain:

$ sudo image-builder build iot-installer \
  --distro fedora-43 \
 --ostree-url [http://192.168.1.100:8000](http://192.168.1.100:8000) \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-dir ./images

Opsi Lanjutan

Menambahkan Repositori Tambahan

Tambahkan repositori paket tambahan selama pembangunan komit OSTree (tidak disertakan dalam image akhir):

$ sudo image-builder build iot-commit \
  --distro fedora-43 \
  --blueprint iot-custom.toml \
  --ostree-ref fedora/stable/x86_64/iot \
  --extra-repo "https://example.com/repo/fedora/43/x86_64" \
  --output-dir ./iot-commit-output
Repositori tambahan tidak diperiksa GPG dan hanya digunakan selama pembangunan komit.

Mengustomisasi Nama Output

Kustomisasi nama file output untuk image Anda:

$ sudo image-builder build iot-installer \
  --distro fedora-43 \
 --ostree-url http://localhost:8000 \
  --ostree-ref fedora/stable/x86_64/iot \
  --output-name my-custom-installer \
  --output-dir ./images

Output Verbose untuk Debugging

Aktifkan mode verbose untuk melihat informasi build yang terperinci:

$ sudo image-builder build iot-commit \
  --distro fedora-43 \
  --blueprint iot-custom.toml \
  --ostree-ref fedora/stable/x86_64/iot \
  --verbose \
  --output-dir ./iot-commit-output

Mengekspor Artefak Build

Ekspor manifest OSBuild dan log build untuk pemecahan masalah:

$ sudo image-builder build iot-commit \
  --distro fedora-43 \
  --blueprint iot-custom.toml \
  --ostree-ref fedora/stable/x86_64/iot \
  --with-manifest \
  --with-buildlog \
  --output-dir ./iot-commit-output

Mendeskripsikan Jenis Image

Untuk melihat informasi terperinci tentang jenis image IoT apa pun:

$ image-builder describe iot-installer --distro fedora-43
$ image-builder describe iot-qcow2 --distro fedora-43 --arch aarch64
$ image-builder describe iot-simplified-installer --distro fedora-43

Ini menampilkan paket, pipeline, dan opsi konfigurasi untuk setiap jenis image.

Praktik Terbaik

  1. Uji dengan QCOW2 Terlebih Dahulu - Bangun dan uji image iot-qcow2 di VM sebelum membuat media instalasi

  2. Gunakan Kontrol Versi untuk Blueprint - Simpan file blueprint di git untuk melacak kustomisasi

  3. Minimalkan Penambahan Paket - Hanya tambahkan paket esensial; gunakan kontainer untuk aplikasi

  4. Gunakan Kata Sandi Terenkripsi - Jangan pernah menggunakan kata sandi teks biasa dalam blueprint

  5. Aktifkan Mode Verbose untuk Pemecahan Masalah - Gunakan --verbose saat men-debug masalah build

Pemecahan Masalah

Build Gagal dengan Kesalahan OSTree

Verifikasi bahwa repositori OSTree lokal Anda sudah disiapkan dengan benar dan ref tersebut ada:

$ ostree --repo=./ostree-repo refs
$ ostree --repo=./ostree-repo show fedora/stable/x86_64/iot

Pastikan server HTTP Anda berjalan dan dapat diakses:

$ curl http://localhost:8000/config
$ curl http://localhost:8000/refs/heads/fedora/stable/x86_64/iot

Kesalahan Izin Ditolak

Sebagian besar operasi image-builder memerlukan hak akses root:

$ sudo image-builder build iot-installer ...

Ruang Disk Tidak Cukup

Membangun image memerlukan ruang disk yang signifikan. Pastikan setidaknya 10GB kosong di:

  • /var/cache/image-builder/ (cache build)

  • Direktori output

Bersihkan cache jika diperlukan:

$ sudo rm -rf /var/cache/image-builder/store/*

Sumber Daya Tambahan

Want to help? Learn how to contribute to Fedora Docs ›