KAL
Menu

Anatomi Manifest

Struktur YAML manifest Kubernetes: apiVersion, kind, metadata, dan spec beserta aturan penulisannya.

Daftar isi

Manifest adalah berkas YAML yang mengirimkan deklarasi objek kepada API server, dan setiap manifest dibangun dari struktur yang sama. Topik ini membedah empat kunci tingkat atas beserta isinya, alasan apiVersion berbeda antarjenis objek, aturan penulisan metadata, serta disiplin penulisan YAML yang membuat manifest sah. Pembacaan struktur dilakukan secara terprogram, sehingga setiap kunci dapat diverifikasi dari keluaran parser.

Empat kunci tingkat atas#

Setiap manifest Kubernetes, tanpa memandang jenis objeknya, selalu dibangun dari empat kunci tingkat atas. Kunci apiVersion menyatakan versi skema API yang menangani objek, kind menyebut jenis objeknya, metadata mengidentifikasinya, dan spec mendeklarasikan keadaan yang diinginkan. Urutan penulisan keempat kunci tidak wajib, tetapi urutan apiVersion, kind, metadata, spec menjadi konvensi yang membuat manifest mudah dibaca.

KunciIsi
apiVersionVersi API yang menangani objek, misalnya v1 atau apps/v1
kindJenis objek yang dideklarasikan, misalnya Pod atau Deployment
metadataNama, namespace, label, dan anotasi objek
specKeadaan akhir yang diinginkan untuk objek tersebut

API server memvalidasi manifest terhadap skema yang ditunjuk oleh apiVersion dan kind. Field yang tidak dikenal membuat penerapan ditolak, sehingga kesalahan penulisan kunci terdeteksi sebelum objek dibuat. Selain keempat kunci tersebut, objek yang sudah berjalan juga memuat kunci status yang diisi oleh sistem, dan kunci itu tidak ditulis pada manifest yang dikirim. Apabila kunci status ikut ditulis, nilainya diabaikan kemudian ditimpa oleh sistem.

apiVersion dan hubungannya dengan kind#

Nilai apiVersion terdiri atas nama grup dan versi yang dipisahkan garis miring. Objek paling mendasar seperti Pod, Service, Namespace, dan ConfigMap berada pada grup inti yang ditulis v1 tanpa nama grup. Controller beban kerja seperti Deployment, ReplicaSet, StatefulSet, dan DaemonSet berada pada grup apps dengan versi v1, sehingga pasangan yang benar adalah apps/v1. Grup lain mengikuti pola yang sama, misalnya networking.k8s.io/v1 untuk Ingress.

Pemisahan grup memungkinkan skema satu keluarga objek berkembang tanpa mengganggu keluarga lain. Angka versinya bergerak dari alpha menuju beta dan stabil, sehingga perubahan besar selalu disertai kenaikan versi. Pasangan apiVersion dan kind wajib cocok dengan yang didukung kluster, karena API server menolak manifest yang pasangannya tidak dikenal dengan pesan error no matches for kind.

Perintah kubectl api-resources menampilkan seluruh pasangan apiVersion dan kind yang didukung kluster tempat perintah dijalankan. Daftarnya panjang, sehingga opsi –api-group digunakan untuk menyaring keluaran berdasarkan grup tertentu. Keluaran berikut memperlihatkan bagian yang relevan bagi topik ini.

bash 
# tidak-dijalankan
# menampilkan daftar jenis objek beserta grup API-nya
kubectl api-resources
text Contoh keluaran 
NAME                          SHORTNAMES   APIVERSION   NAMESPACED   KIND
configmaps                    cm           v1           true         ConfigMap
pods                          po           v1           true         Pod
services                      svc          v1           true         Service
deployments                   deploy       apps/v1      true         Deployment
replicasets                   rs           apps/v1      true         ReplicaSet

metadata: nama dan label#

Kunci metadata menampung data yang mengidentifikasi objek tanpa menyentuh perilakunya. Field utamanya adalah name, namespace, labels, dan annotations. Field name berlaku unik untuk satu jenis objek di dalam satu namespace, sehingga dua Pod bernama sama tidak dapat hidup berdampingan, sedangkan dua Pod bernama sama pada namespace yang berbeda tidak bertentangan.

Penamaan mengikuti format DNS. Karakter yang diizinkan adalah huruf kecil, angka, tanda hubung, dan titik, dengan batas panjang umum 253 karakter dan sebagian jenis objek menggunakan batas 63 karakter. Field name wajib diisi, kecuali generateName yang meminta API server menambahkan akhiran acak secara otomatis. Field namespace bersifat opsional, dan bila dikosongkan objek ditempatkan pada namespace default.

Labels dan annotations sama-sama menyimpan metadata bebas, tetapi tujuannya berbeda. Label dimaksudkan untuk dipilih oleh selector, sedangkan annotation menyimpan data non-identifikasi yang ukurannya dapat lebih besar, misalnya catatan pemilik atau rujukan alat lain. Pembagian peran ini menjaga label tetap ramping karena selector menyeleksi objek berdasarkan label, bukan berdasarkan annotation.

spec dan aturan penulisan YAML#

Kunci spec berisi keadaan akhir yang diinginkan. Isinya berbeda untuk setiap kind, misalnya spec Pod berisi daftar containers, sedangkan spec Deployment berisi replicas, selector, dan template Pod. Perbedaan itu menegaskan bahwa skema spec selalu mengikuti kind yang dideklarasikan. Manifest berikut memperlihatkan keempat kunci tingkat atas pada satu berkas Deployment yang lengkap.

yaml deployment.yaml 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-deployment
  labels:
    app: web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: nginx:1.27
          ports:
            - containerPort: 80

Skrip Python berikut mem-parse deployment.yaml menggunakan PyYAML, kemudian mencetak nilai dari keempat kunci tersebut untuk mengonfirmasi struktur berkasnya.

python baca-manifest.py 
"""Membaca deployment.yaml dan menampilkan empat kunci tingkat atas."""
import yaml

with open("deployment.yaml") as berkas:
    manifest = yaml.safe_load(berkas)

print(f"apiVersion : {manifest['apiVersion']}")
print(f"kind       : {manifest['kind']}")
print(f"nama       : {manifest['metadata']['name']}")
print(f"label      : {manifest['metadata']['labels']}")

print(f"replicas   : {manifest['spec']['replicas']}")
container = manifest["spec"]["template"]["spec"]["containers"][0]
print(f"container  : {container['name']} (image {container['image']})")
text Keluaran 
apiVersion : apps/v1
kind       : Deployment
nama       : web-deployment
label      : {'app': 'web'}
replicas   : 3
container  : web (image nginx:1.27)

Manifest Kubernetes ditulis dalam YAML, sehingga aturan indentasinya berlaku penuh. Dua spasi menjadi lebar indentasi yang lazim, elemen daftar ditandai tanda hubung, dan pasangan key dengan value dipisahkan titik dua. Perubahan indentasi mengubah makna struktur, dan pergeseran yang keliru dapat mengubah kunci anak menjadi kunci lain atau membuat YAML gagal di-parse. Manifest yang sudah ditulis sebaiknya diuji dengan parser YAML terlebih dahulu sebelum diterapkan ke kluster.

python Contoh: mendeteksi YAML dengan indentasi bergeser 
import yaml

# teks YAML dengan indentasi kunci labels yang bergeser lebih dalam
teks = """
apiVersion: v1
kind: Pod
metadata:
  name: web-statis
   labels:
    app: web
"""

try:
    yaml.safe_load(teks)
except yaml.YAMLError as error:
    print("YAML ditolak dengan pesan error:")
    print(error)
text Keluaran 
YAML ditolak dengan pesan error:
mapping values are not allowed here
  in "<unicode string>", line 6, column 10:
       labels:
             ^

Pesan error PyYAML menunjuk baris keenam dan kolom kunci labels yang bergeser lebih dalam dari kunci name di atasnya. Pergeseran satu spasi semacam ini sulit terlihat pada layar, tetapi parser menandainya sebagai struktur yang tidak sah. Apabila manifest seperti ini diterapkan tanpa pemeriksaan, API server menolaknya dengan error serupa, sehingga pemeriksaan lokal menghemat siklus uji coba sebelum menyentuh kluster.

Ringkasan#

  • Setiap manifest terdiri atas apiVersion, kind, metadata, dan spec, dengan kunci status dikelola sistem dan tidak ditulis pada manifest.
  • Nilai apiVersion menyatakan grup dan versi skema yang wajib cocok dengan kind, misalnya v1 untuk Pod dan apps/v1 untuk Deployment.
  • metadata.name harus unik untuk satu jenis objek di dalam satu namespace, sedangkan label pada metadata menyediakan metadata yang dipilih selector.
  • Struktur YAML manifest bergantung penuh pada indentasi, sehingga manifest diuji dengan parser sebelum diterapkan ke kluster.

Referensi#