Belajar Firecracker - API Management: Boot & Machine Config

#Pendahuluan

Di episode 3 kita menjalankan firecracker --api-sock dan melihat API merespons — tapi microVM belum boot. Episode 4 adalah saat semuanya menyatu: kita mengirim konfigurasi ke API Firecracker secara lengkap — kernel, machine config, drive, lalu InstanceStart — dan menyaksikan microVM pertama kalian hidup lewat serial console.

Mengapa episode ini penting? Karena API adalah satu-satunya control plane Firecracker. Semua yang akan kalian pelajari sepanjang series — networking, storage, snapshot, MMDS — pada akhirnya adalah variasi dari pola yang sama: curl --unix-socket dengan payload JSON. Menguasai episode ini berarti menguasai bahasa utama Firecracker.

#Arsitektur API Firecracker

Firecracker mengekspos API REST di atas Unix socket — bukan TCP. Ini pilihan keamanan yang disengaja: socket hanya bisa diakses oleh proses yang punya hak akses ke file socket di host, bukan dari jaringan mana pun. Pola dasarnya:

curl --unix-socket /tmp/firecracker.sock -i \
  -X PUT http://localhost/<endpoint> \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

Titik http://localhost/ tidak pernah benar-benar diakses lewat jaringan — hostnya diabaikan, yang penting adalah socket. Seluruh interaksi dengan microVM mengalir lewat pola ini, dan setelah InstanceStart, beberapa endpoint akan terkunci.

#PUT /boot-source: Memberi Kernel

Langkah pertama adalah memberi tahu Firecracker kernel mana yang akan dimuat. Kernel harus uncompressed (vmlinux.bin), dan path-nya adalah path di host:

{
  "kernel_image_path": "/home/user/fc-demo/vmlinux.bin",
  "boot_args": "console=ttyS0 reboot=k panic=1 pci=off"
}

Kirim lewat curl:

curl --unix-socket /tmp/firecracker.sock -i \
  -X PUT http://localhost/boot-source \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  -d '{
    "kernel_image_path": "/home/user/fc-demo/vmlinux.bin",
    "boot_args": "console=ttyS0 reboot=k panic=1 pci=off"
  }'

Setiap field punya arti:

• kernel_image_path — path absolut ke kernel di host.
• boot_args — parameter kernel. console=ttyS0 mengarahkan output ke serial (agar bisa dibaca lewat screen), panic=1 meminta guest reboot setelah panic, pci=off mematikan bus PCI untuk mempercepat boot.

Perhatikan juga field initrd_path (jika butuh initramfs) dan boot_args opsional lainnya. Tanpa console=ttyS0, output boot guest tidak akan terlihat di serial console.

#PUT /machine-config: vCPU, Memori, dan CPU Template

Sebelum boot, tentukan ukuran VM. PUT /machine-config mengatur vCPU, memori, dan fitur CPU:

curl --unix-socket /tmp/firecracker.sock -i \
  -X PUT http://localhost/machine-config \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  -d '{
    "vcpu_count": 2,
    "mem_size_mib": 1024,
    "ht_enabled": false,
    "cpu_template": "T2"
  }'

Field pentingnya:

• vcpu_count — jumlah vCPU (maksimal sesuai ukuran mesin host dan kernel Firecracker).
• mem_size_mib — memori guest dalam MiB.
• ht_enabled — aktifkan hyperthreading bagi guest. Umumnya false untuk workload serverless agar perilaku CPU deterministik.
• cpu_template — menyembunyikan perbedaan mikroarsitektur antar host fisik, sehingga migrasi snapshot (episode 9) antar host tetap valid. Nilai seperti T2, T2S, T3 meniru model CPU tertentu.

Kapan machine-config wajib dikirim? Sebenarnya tidak wajib — Firecracker punya default (1 vCPU, 128 MiB memori). Tapi untuk produksi, selalu set eksplisit. Konfigurasi ini hanya bisa diubah sebelum boot; setelah InstanceStart, nilai terkunci.

#PUT /drives: Block Device

MicroVM butuh filesystem. PUT /drives menempelkan block device — dalam contoh kita, rootfs:

curl --unix-socket /tmp/firecracker.sock -i \
  -X PUT http://localhost/drives/rootfs \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  -d '{
    "drive_id": "rootfs",
    "path_on_host": "/home/user/fc-demo/rootfs.ext4",
    "is_root_device": true,
    "is_read_only": false
  }'

Field penting:

• drive_id — identitas unik drive (muncul juga di URL path).
• path_on_host — file image di host (ext4, raw; bukan qcow2).
• is_root_device — drive ini adalah root filesystem; hanya satu drive yang boleh punya nilai true.
• is_read_only — untuk rootfs multi-tenant biasanya true, memungkinkan sharing page cache (episode 19). Pada percobaan ini biarkan false agar guest bisa menulis.

Drive tambahan tinggal di-PUT dengan drive_id lain. Detail storage lebih dalam di episode 6.

#InstanceStart: Saatnya Boot

Semua konfigurasi sudah dikirim. Sekarang nyalakan mesin:

curl --unix-socket /tmp/firecracker.sock -i \
  -X PUT http://localhost/actions \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  -d '{ "action_type": "InstanceStart" }'

Jika berhasil, API merespons 204 No Content dan proses Firecracker mulai mengeksekusi. Dari sini konfigurasi terkunci: tidak bisa lagi menambah drive, network, atau mengubah machine config tanpa membuat VM baru atau memakai snapshot.

#Melihat Boot lewat Serial Console

Output guest dikirim ke serial port. Firecracker bisa mengeksposnya sebagai pty, atau kita baca langsung dari output proses. Cara paling sederhana: redirect output proses Firecracker ke pty dan baca dengan screen:

sudo socat -u pty,link=/dev/ttyFC0,open-slave,wait-slave - &
firecracker --api-sock /tmp/firecracker.sock < /dev/ttyFC0 > /dev/ttyFC0 2>&1 &

Kemudian baca serial console:

sudo screen /dev/ttyFC0 115200

#Machine Config: Patch dan Get

PATCH /machine-config bisa dipakai untuk mengubah konfigurasi sebelum boot — berguna saat kalian ingin mengubah nilai tertentu tanpa menulis ulang seluruh JSON:

curl --unix-socket /tmp/firecracker.sock -i \
  -X PATCH http://localhost/machine-config \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  -d '{ "mem_size_mib": 2048 }'

Untuk memeriksa konfigurasi aktif, GET /machine-config mengembalikan JSON lengkap — kebiasaan yang bagus untuk men-debug VM yang tidak boot sesuai harapan:

curl --unix-socket /tmp/firecracker.sock http://localhost/machine-config

#Common Pitfalls

• Path relatif di boot-source/drives: tanpa jailer, Firecracker me-resolve path dari working directory-nya. Gunakan path absolut.
• Mengubah konfigurasi setelah start: API menolak dengan error 409 Conflict — konfigurasi terkunci pasca InstanceStart.
• pci=off vs is_root_device: tanpa pci=off, kernel butuh waktu ekstra men-scan PCI; tanpa is_root_device=true, kernel tidak tahu mana root filesystem-nya.
• Mengirim JSON tidak valid: API merespons 400 Bad Request. Periksa kembali tanda kutip dan koma — kesalahan paling umum di sini.

#Penutup

Inti yang harus dibawa pulang:

• Seluruh kontrol Firecracker lewat curl --unix-socket, tidak ada jaringan TCP.
• Urutan boot: boot-source → machine-config → drives → InstanceStart.
• cpu_template menyembunyikan perbedaan hardware — kunci migrasi snapshot.
• Setelah start, konfigurasi terkunci; perubahan berarti VM baru atau snapshot.
• console=ttyS0 adalah cara membuka jendela ke dalam guest.
• PATCH /machine-config dan GET /machine-config untuk penyesuaian dan debug.

Di episode 5 selanjutnya kita akan membuat microVM kalian benar-benar berguna: Networking — Virtio-net & TAP — membuat TAP interface di host dengan ip tuntap add, menghubungkannya lewat PUT /network-interfaces, memberi IP di dalam guest, dan membungkusnya dengan rate limiter token bucket agar siap untuk skenario multi-tenant.