Penyedia Otomatis Klaster Kubernetes (Kubernetes Cluster Auto-Provisioner)

Kubernetes Cluster Auto-Provisioner di Cockpit menyediakan mekanisme bawaan yang disederhanakan untuk menerapkan, menskalakan, dan memelihara klaster Kubernetes di atas sumber daya komputasi dan jaringan virtual. Dengan memanfaatkan arsitektur multi-VM, distribusi k3s yang ringan, serta orkestrasi otomatis, Cockpit mengabstraksikan kompleksitas pembuatan klaster (bootstrapping) sambil menawarkan penyesuaian kelas enterprise untuk jaringan, penyimpanan, dan penjadwalan.

---

1. Ikhtisar Arsitektur

Penyedia otomatis Cockpit mengorkestrasi VM pada hypervisor fisik menggunakan jalur latar belakang yang terstruktur. Sistem menyebarkan node control plane dan pekerja menggunakan templat citra emas OS (golden image) yang dikonfigurasi sebelumnya, disesuaikan saat boot melalui cloud-init dan dikelola setelah boot menggunakan QEMU Guest Agent.

flowchart TD
    subgraph Cockpit Management Plane
        UI[Dashboard UI Cockpit] -->|REST API / WebSockets| API[Mesin API Cockpit]
        API -->|Task Runner| Tasks[Tugas Penyediaan Latar Belakang]
        DB[(DB PostgreSQL - GORM)] <-->|Status Klaster & Node| API
    end

    subgraph Datastores & Penyimpanan
        DS_Shared[Datastore Bersama - NFS] -->|Kloning VM Segera| Hypervisors
        DS_Local[Datastore Lokal] -->|Caching Templat Fallback| Hypervisors
    end

    subgraph Hypervisors & VM
        Hypervisors -->|Kloning & Terapkan| VM_CP[VM Control Plane]
        Hypervisors -->|Kloning & Terapkan| VM_W1[VM Node Pekerja 1]
        Hypervisors -->|Kloning & Terapkan| VM_W2[VM Node Pekerja 2]
    end

    subgraph Klaster Kubernetes
        VM_CP -->|Bootstrap Server k3s| K8S_CP[Node Control Plane]
        VM_W1 -->|Gabung Klaster via Token| K8S_CP
        VM_W2 -->|Gabung Klaster via Token| K8S_CP
    end

Backend Cockpit mengelola semua interaksi dengan hypervisor, memantau status VM, membaca status konfigurasi dari VM melalui QEMU Guest Agent, dan menjalankan proses pembuatan klaster.

---

2. Prasyarat Infrastruktur

Sebelum menggunakan penyedia otomatis, administrator harus memastikan bahwa lingkungan virtual dan templat dasar memenuhi persyaratan yang diuraikan di bawah ini.

2.1 Templat Citra Emas OS (Golden OS Image Template)

Untuk mendukung kloning VM yang cepat, diperlukan "Citra Emas" terstandarisasi.

• Sistem Operasi Dasar: Ubuntu 24.04 LTS (format qcow2).
• QEMU Guest Agent: Harus sudah diinstal sebelumnya (apt-get install -y qemu-guest-agent) dan diaktifkan saat boot. Agen tamu memungkinkan Cockpit untuk:
  • Menemukan alamat IP VM yang dialokasikan via DHCP secara dinamis.
  • Mengambil token autentikasi (seperti token gabung k3s) secara aman.
  • Mengambil file kubeconfig yang dihasilkan tanpa mengekspos kunci SSH atau membuat terowongan jaringan.
• Cloud-Init: Harus diaktifkan dan dikonfigurasi untuk membaca metadata yang diteruskan oleh hypervisor libvirt.
• Partisi Root Otomatis Tumbuh: Partisi root harus dikonfigurasi untuk secara otomatis mengubah ukuran dan tumbuh agar sesuai dengan ukuran disk yang dialokasikan pada boot pertama (memanfaatkan utilitas cloud-init growpart atau yang serupa).

2.2 Storage Pool Datastore

Templat harus disimpan di salah satu datastore berikut:

1. Storage Pool Bersama (Direkomendasikan): Menyimpan templat citra emas pada datastore bersama (misalnya, NFS atau OCFS2 terklaster) memungkinkan semua hypervisor fisik dalam klaster Cockpit untuk mengkloning dan mem-boot VM control plane/pekerja dengan segera.
2. Storage Pool Lokal (Fallback Caching): Jika node disediakan pada storage pool hypervisor lokal, backend Cockpit memeriksa apakah file citra emas ada secara lokal di storage pool host target. Jika hilang, Cockpit secara otomatis menyalin (caching) file templat dari penyimpanan utama Cockpit ke storage pool lokal host tersebut sebelum memulai operasi kloning VM.

---

3. Panduan Langkah demi Langkah Wizard Penyediaan

Administrator dapat meluncurkan alur penyediaan langsung dari UI Cockpit:

1. Klik kanan node Cluster di pohon inventaris sebelah kiri.
2. Pilih Kubernetes -> New Cluster di menu konteks.
3. Kubernetes Provisioning Wizard akan terbuka, memandu Anda melalui lima langkah berikut.

Langkah	Nama Bagian	Kolom Konfigurasi	Aturan / Tindakan Arsitektural Utama
1	Identitas & Versi	• Nama Klaster • Deskripsi • Jaringan Target • Versi K3s (misalnya, v1.29.2+k3s1) • Plugin Jaringan CNI	• Opsi CNI mencakup Flannel (Default), Calico, dan Cilium eBPF. • Jaringan Target menetapkan VM ke jembatan jaringan virtual.
2	Konfigurasi Control Plane	• vCores CPU • Memori (GB) • Storage Pool • Ukuran Disk (GB) • Jumlah Node (1 vs 3) • Strategi Penempatan	• Pilihan Jumlah Node: Single Control Plane (1 Node) atau High Availability (3 Node). • Opsi Penempatan:   1. Distribusi Otomatis (Auto-Distribute): Menerapkan aturan anti-affinity menggunakan mesin DRS Cockpit, memastikan 3 VM Master HA dijadwalkan pada tiga host fisik terpisah.   2. Override Manual: Menu dropdown muncul untuk menentukan host hypervisor secara eksplisit untuk setiap node.
3	Pool Node Pekerja	• Jumlah Pekerja (default: 3) • vCores CPU per pekerja • Memori (GB) per pekerja • Storage Pool • Ukuran Disk (GB) • Strategi Penempatan	• Opsi Penempatan:   1. Distribusi Otomatis: Menyebarkan VM pekerja secara otomatis di seluruh host fisik untuk menyeimbangkan penggunaan CPU/Memori.   2. Override Manual: Menentukan VM pekerja secara eksplisit ke host tertentu (berguna untuk perangkat keras khusus host seperti GPU).
4	Kredensial & Kategori CSI	• Kunci Publik SSH (Textarea) • Pilihan Kategori Penyimpanan CSI	• Kunci SSH: Mengotorisasi akses root/admin ke node VM untuk pemecahan masalah. • CSI Storage Tiers (Opsi pilihan ganda dijelaskan di Bagian 5):   - Kategori 1: Jalur Host (local-path-provisioner) [Aktif secara default].   - Kategori 2: Penyimpanan Bersama NFS [Nonaktif secara default].   - Kategori 3: Penyimpanan Blok Terreplikasi (Longhorn) [Nonaktif secara default].
5	Tinjau & Sediakan	• Dashboard Ringkasan	• Menampilkan konfigurasi, jejak sumber daya, dan pemetaan host fisik. • Mengklik Provision mendaftarkan Tugas latar belakang yang berjalan lama di Cockpit dan menutup wizard.

---

4. Konfigurasi Container Network Interface (CNI)

Pilihan CNI menentukan rute jaringan pod, kebijakan keamanan, dan karakteristik kinerja.

Plugin CNI	Opsi Default	Teknologi Rute	Kebijakan Keamanan / Jaringan	Kasus Penggunaan Utama
Flannel	Ya	Enkapsulasi VXLAN / Host-gw	Tidak Ada	Pengembangan lokal yang ringan, lingkungan node tunggal atau overhead rendah.
Calico	No	Rute IP-in-IP / BGP	NetworkPolicies Kubernetes Penuh	Lingkungan multi-tenant yang memerlukan kebijakan isolasi yang aman.
Cilium	No	eBPF Linux (rute langsung)	Penegakan kebijakan L3-L7 tingkat lanjut & telemetri Hubble	Lingkungan produksi berkinerja tinggi dengan throughput tinggi.

Proses Bootstrapping CNI

1. Flannel (Default): Cockpit mengonfigurasi VM control plane dengan flag instalasi k3s standar:

   curl -sfL https://get.k3s.io | sh -s - server --disable traefik --write-kubeconfig-mode 644

2. Calico & Cilium (CNI Kustom):
   • Untuk mencegah konflik aturan perutean, Cockpit mem-boot VM control plane dengan menonaktifkan komponen Flannel dan kebijakan jaringan bawaan:

     curl -sfL https://get.k3s.io | sh -s - server --disable traefik --flannel-backend=none --disable-network-policy --write-kubeconfig-mode 644

   • Klaster awalnya melakukan booting dalam status "Jaringan Tidak Tersedia". Setelah API server dapat dihubungi, backend Cockpit menerapkan manifes Calico atau Cilium kustom (penerapan chart Helm atau sumber daya YAML) secara langsung untuk membangun jaringan pod sebelum VM pekerja mencoba bergabung.

---

5. Opsi Container Storage Interface (CSI)

Cockpit mengimplementasikan antarmuka pemilihan kategori CSI multi-tier yang memungkinkan volume persisten (PV) dipetakan kembali ke storage pool hypervisor fisik atau infrastruktur bersama.

                  ┌────────────────────────────────────────┐
                  │           Opsi Penyimpanan CSI         │
                  └───────────────────┬────────────────────┘
                                      │
         ┌────────────────────────────┼────────────────────────────┐
         ▼                            ▼                            ▼
  [Kategori 1: Jalur Host]     [Kategori 2: NFS Bersama]    [Kategori 3: Blok Longhorn]
   • local-path bawaan        • Driver CSI NFS             • Longhorn mengagregasi
   • Data pod disimpan ke      • Menghubungkan ke DS NFS      disk VM lokal
     disk root VM             • Mendukung ReadWriteMany    • Replikasi, ketersediaan tinggi

5.1 Kategori 1: Jalur Host (Aktif secara Default)

• Mesin Utama: Menggunakan local-path-provisioner bawaan k3s.
• Aliran Data: Data PV ditulis ke jalur lokal yang ditentukan pada disk root VM pekerja (/opt/local-path-provisioner). Karena disk VM (file .qcow2) berada di storage pool host fisik Cockpit, penyimpanan tersebut pada akhirnya didukung oleh disk fisik host.
• Kelebihan/Kekurangan: Kinerja tinggi, tanpa pengaturan tambahan. Namun, volume tidak dapat dipindahkan. Jika Pod dijadwalkan ulang ke VM pekerja yang berbeda, Pod tersebut tidak dapat mengakses data sebelumnya.

5.2 Kategori 2: Penyimpanan Bersama NFS (Opsional)

• Mesin Utama: Menerapkan Driver CSI NFS Kubernetes.
• Opsi Konfigurasi:
  • Gunakan Datastore NFS yang Ada: Pilih dari NFS storage pool yang sudah dikonfigurasi di Cockpit. Alamat IP Server dan detail jalur ekspor diambil secara otomatis dari database Cockpit.
  • Gunakan Server NFS Eksternal: Tentukan secara manual IP/hostname server NFS, jalur pemasangan (mount path), dan kredensial.
• Pemeriksaan Awal Backend: Sebelum penyediaan dimulai, Cockpit task runner mencoba melakukan koneksi TCP pada port 2049 (port NFS) ke IP server NFS yang ditentukan melalui jembatan jaringan virtual yang dipilih. Jika tidak dapat dihubungi, tugas dihentikan dan memperingatkan administrator.
• Kelebihan/Kekurangan: Mendukung PV ReadWriteMany (RWX). Pod dapat bermigrasi secara dinamis di seluruh node pekerja dan hypervisor fisik sambil tetap mempertahankan akses ke volume yang sama.

5.3 Kategori 3: Penyimpanan Terreplikasi - Longhorn (Opsional)

• Mesin Utama: Menyebarkan operator penyimpanan blok terdistribusi Longhorn di dalam klaster.
• Konfigurasi: Administrator memilih datastore host Cockpit target (misalnya, fast-ssd-pool) untuk menyimpan file disk VM pekerja.
• Aliran Data: Longhorn mengagregasikan ruang disk lokal dari semua VM pekerja (yang berada secara fisik pada datastore host berkecepatan tinggi yang dipilih) dan menyediakan penyimpanan blok tereplikasi.
• Kelebihan/Kekurangan: Redundansi penuh, penyimpanan ketersediaan tinggi (ReadWriteOnce). Ideal untuk aplikasi stateful kritis (database). Jika host fisik atau VM pekerja mati, volume tetap dapat diakses di node lain.

---

6. Mengakses Klaster: Pengaturan Kubeconfig

Setelah status klaster berubah menjadi active, kubeconfig administratif menjadi tersedia untuk diunduh.

6.1 Penulisan Ulang Endpoint Dinamis

Ketika pengguna meminta kubeconfig melalui GET /api/v1/kubernetes/clusters/:id/kubeconfig, backend Cockpit mengeksekusi jalur pasca-pemrosesan berikut:

1. Membaca file mentah yang dihasilkan dari /etc/rancher/k3s/k3s.yaml pada VM Control Plane menggunakan QEMU Guest Agent.
2. File default menunjuk ke alamat loopback lokal: server: https://127.0.0.1:6443.
3. Cockpit secara dinamis menulis ulang 127.0.0.1 (atau localhost) dengan alamat IP DHCP fisik eksternal dari VM control plane (misalnya, server: https://192.168.122.155:6443).
4. Menyajikan muatan sebagai lampiran yang dapat diunduh:
   • Content-Type: application/x-yaml
   • Filename: kubeconfig-{nama_klaster}.yaml

6.2 Instruksi Koneksi Langkah demi Langkah

Untuk terhubung ke klaster baru Anda menggunakan CLI kubectl dari sistem lokal Anda:

1. Unduh Kubeconfig: Klik Download Kubeconfig dari halaman detail klaster di UI Cockpit.

2. Pindahkan dan Batasi Izin Akses: Pindahkan file yang diunduh ke folder konfigurasi mesin lokal Anda dan batasi izin akses (diperlukan oleh kubectl):

   mkdir -p ~/.kube
   mv ~/Downloads/kubeconfig-k8s-prod.yaml ~/.kube/config-k8s-prod
   chmod 600 ~/.kube/config-k8s-prod

3. Atur Variabel Lingkungan KUBECONFIG: Arahkan terminal aktif Anda ke konfigurasi yang baru diunduh:

   export KUBECONFIG=~/.kube/config-k8s-prod

   TIP

   Untuk membuat konfigurasi ini persisten, tambahkan perintah ekspor tersebut ke file profil shell Anda (misalnya, ~/.bashrc atau ~/.zshrc).

4. Verifikasi Konektivitas: Uji koneksi dengan meminta informasi API server dan memeriksa ketersediaan node:

   kubectl cluster-info
   kubectl get nodes -o wide

---

7. Menskalakan dan Mengubah Pool Node Pekerja

Cockpit memungkinkan pengguna untuk menskalakan pool node pekerja ke atas (scale up) atau ke bawah (scale down) secara dinamis tanpa membangun kembali klaster atau control plane.

                       Permintaan Skala Pool Diterima
                                      │
                                      ▼
                           Hitung Selisih Node
                                      │
                   ┌──────────────────┴──────────────────┐
                   ▼ (Selisih > 0)                       ▼ (Selisih < 0)
             [Skala Naik]                          [Skala Turun]
                   │                                     │
         Ambil Token Gabung dari VM CP                   │
         via QEMU Guest Agent                            │
                   │                                     │
         Kloning VM Pekerja Baru dari                    │
         Citra Emas OS                                   │
                   │                                     │
         Injeksi Perintah Gabung Cloud-Init              │
         menggunakan IP CP dan Token                     │
                   │                                     │
         Boot VM & Tunggu Penemuan IP                  Kuras Node Perlahan
         via DHCP                                      (kubectl drain)
                   │                                     │
         Tunggu Status Node K8s                        Hapus VM Pekerja
         menunjukkan "Ready"                             │
                   │                                     │
         Simpan Node ke DB GORM                        Perbarui Catatan DB
                   │                                     │
                   └──────────────────┬──────────────────┘
                                      ▼
                               Tugas Selesai

7.1 Skala Naik (Scale Up)

1. Perhitungan Selisih (Delta): Backend membandingkan jumlah yang diminta dengan desired_count saat ini yang dikonfigurasi dalam database K8sNodePool.
2. Pengambilan Token: Cockpit mengambil rahasia penggabungan klaster saat ini dengan membaca /var/lib/rancher/k3s/server/node-token dari VM Control Plane menggunakan QEMU Guest Agent.
3. Koning VM: Pelaksana tugas mengkloning instans VM pekerja tambahan dari templat OS.
4. Pengaturan Cloud-Init: Data pengguna VM baru diisi dengan konfigurasi penggabungan:

   #cloud-config
   runcmd:
     - systemctl enable --now qemu-guest-agent
     - curl -sfL https://get.k3s.io | K3S_URL=https://<IP_CONTROL_PLANE>:6443 K3S_TOKEN=<TOKEN_GABUNG> sh -

5. Boot & Registrasi: Setelah melakukan booting, VM mendapatkan IP DHCP yang ditemukan via QEMU Guest Agent. Cockpit memantau API klaster Kubernetes hingga node baru muncul dan melaporkan status Ready.

7.2 Skala Turun (Scale Down)

1. Pemilihan Node: Cockpit memilih VM pekerja yang berlebih (memilih node dengan waktu aktif terendah atau indeks tertinggi).
2. Pengurasan Node (Draining): Cockpit menjalankan perintah kuras klaster (setara dengan kubectl drain <nama-node> --delete-emptydir-data --ignore-daemonsets --force) melalui control plane untuk memindahkan beban kerja.
3. Penghancuran: Setelah dikuras, Cockpit menghentikan dan menghapus VM target, membebaskan sumber daya hypervisor, dan menghapus catatan mereka dari tabel database K8sNode.

---

8. Pilihan Versi Dinamis & Pembaruan

Cockpit menerapkan pembaruan tanpa downtime (zero-downtime upgrades) untuk klaster Kubernetes menggunakan operator System Upgrade Controller dari Rancher.

8.1 Pilihan Versi Dinamis

Alih-alih mengandalkan daftar versi yang dikodekan secara keras (hardcoded), UI Cockpit secara dinamis menanyakan backend melalui endpoint GET /api/v1/kubernetes/k3s-versions.

• Pengambilan Dinamis: Backend menanyakan API GitHub Releases untuk mengambil tag k3s stabil yang aktif.
• Daftar Fallback: Jika jaringan hypervisor terisolasi (air-gapped) atau API GitHub dibatasi, Cockpit kembali ke daftar rilis K3s bawaan yang dikurasi mulai dari v1.36.1+k3s1 hingga v1.31.0+k3s1.

8.2 Pengaturan System Upgrade Controller

Selama bootstrap klaster awal, Cockpit menginstal penyebaran system-upgrade-controller di dalam klaster. Pengontrol ini memantau sumber daya Plan kustom untuk mendorong pembaruan.

8.3 Jalur Pembaruan (Upgrade Pipeline)

Ketika administrator memilih versi k3s yang lebih baru di UI (misalnya meningkatkan dari v1.28.7+k3s1 ke v1.29.2+k3s1):

1. Memicu Pembaruan: Cockpit mengirimkan permintaan POST /api/v1/kubernetes/clusters/:id/upgrade.
2. Penerapan Rencana (Plan): Backend Cockpit menerapkan manifes Plan kustom ke klaster yang menargetkan versi baru.

   apiVersion: upgrade.cattle.io/v1
   kind: Plan
   metadata:
     name: k3s-server
     namespace: system-upgrade
   spec:
     concurrency: 1
     version: v1.29.2+k3s1
     nodeSelector:
       matchExpressions:
         - key: node-role.kubernetes.io/master
           operator: In
           values:
             - "true"
     serviceAccountName: system-upgrade
     upgrade:
       image: rancher/k3s-upgrade

3. Eksekusi Berurutan:
   • System Upgrade Controller memilih satu node pada satu waktu (dimulai dengan node control plane, kemudian node pekerja).
   • Pengontrol menguras (drain) beban kerja dari node target.
   • Pengontrol memperbarui biner k3s dan file konfigurasi di dalam VM.
   • Pengontrol memulai ulang layanan, memantau status pemeriksaan kesehatan, dan membuka kembali (uncordon) node.
   • Setelah node kembali ke status Ready, pengontrol melanjutkan ke node berikutnya dalam urutan.
4. Pemantauan: Backend Cockpit meminta status sumber daya kustom Plan dan menampilkan bilah kemajuan bergulir di panel Tugas.

---

9. Pemecahan Masalah & Masalah Umum

9.1 VM Terjebak dalam Status "Creating" atau "Booting"

• Kemungkinan Penyebab: Templat citra emas OS hilang dari datastore lokal host target, atau kecepatan penyalinan jaringan lambat.
• Solusi: Periksa log tugas Cockpit untuk mendeteksi kegagalan penyalinan citra. Jika penyalinan gagal, verifikasi bahwa izin replikasi host-ke-host dan jembatan jaringan aktif.

9.2 Node Melakukan Booting tetapi Tidak Dapat Bergabung dengan Klaster (CNI Tidak Tersedia)

• Kemungkinan Penyebab: Manifes instalasi CNI kustom (Calico/Cilium) gagal diterapkan pada control plane, mencegah inisialisasi jaringan.
• Solusi: Akses konsol atau terminal VM Control Plane dan verifikasi bahwa API server aktif. Pastikan VM memiliki akses internet untuk mengambil citra CNI kustom jika menggunakan registri eksternal.

9.3 QEMU Guest Agent Tidak Dapat Dihubungi

• Kemungkinan Penyebab: Citra emas tidak mengaktifkan daemon QEMU Guest Agent saat startup, atau daemon mengalami crash.
• Solusi: Buka Konsol VM melalui panel noVNC Cockpit, masuk, dan pastikan layanan agen aktif:

  systemctl status qemu-guest-agent

  Jika tidak diinstal, instal secara manual dan mulai ulang:

  sudo apt-get install -y qemu-guest-agent && sudo systemctl enable --now qemu-guest-agent