Mengedit File Konfigurasi YAML dengan yq

yq adalah pemroses YAML portabel berbasis baris perintah, mirip dengan cara jq menangani JSON. Anda dapat membaca, memfilter, dan mengedit file YAML tanpa menulis skrip dalam Python atau Ruby.

Ada dua alat populer bernama yq:

• mikefarah/yq (Go) — dipelihara secara aktif, mendukung YAML, JSON, XML, TOML. Pelajaran ini menggunakan versi ini.
• kislyuk/yq (Python) — pembungkus jq untuk YAML; sintaksnya berbeda.

Instal versi Go:

• brew install yq di macOS
• snap install yq di Linux
• Atau unduh biner: wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq && chmod +x /usr/local/bin/yq

Verifikasi: yq --version seharusnya mencetak v4.x.x. Versi 4 menggunakan sintaks ekspresi yang berbeda dari v3, jadi versinya penting.

Sebelum mengedit apa pun, pelajari cara membaca bidang YAML. Dengan Deployment Kubernetes, Anda dapat mengekstrak nilai bertingkat apa pun menggunakan jalur notasi titik.

Contoh deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: production
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: app
          image: my-app:1.0.0

Perintah utama untuk membaca:

• yq '.metadata.name' deployment.yaml — mencetak my-app
• yq '.spec.replicas' deployment.yaml — mencetak 3
• yq '.spec.template.spec.containers[0].image' deployment.yaml — mencetak my-app:1.0.0

Keluaran secara default berupa teks biasa (tanpa tanda kutip). Tambahkan tanda -r atau gunakan | yq -r jika Anda memerlukan string mentah dalam skrip.

Tanda yang paling penting untuk penggunaan di dunia nyata adalah -i (di tempat). Tanpa tanda ini, yq mencetak hasil ke stdout dan membiarkan file tidak berubah.

Sintaks:

• Hanya membaca (stdout): yq '.spec.replicas' file.yaml
• Edit di tempat: yq -i '.spec.replicas = 5' file.yaml

Operator penugasan = menetapkan sebuah nilai. Ekspresi tersebut merupakan filter yq lengkap, jadi Anda dapat menggabungkan pembacaan dan penulisan dalam satu proses.

Penting: yq -i menulis ulang file sepenuhnya. Komentar yang ditempatkan pada baris yang sama dengan suatu bidang umumnya dipertahankan, tetapi blok komentar yang berdiri sendiri dapat berpindah. Selalu lakukan commit terhadap YAML Anda ke kontrol versi sebelum menjalankan pengeditan di tempat secara massal.

Uji terlebih dahulu tanpa -i, lalu tambahkan tanda tersebut setelah Anda puas dengan hasilnya.

Tugas CI yang sangat umum adalah menaikkan tag image Docker dalam manifes Kubernetes setelah image baru dibuat. Dengan yq, hal ini menjadi perintah satu baris.

Polanya adalah:

• Tentukan target container berdasarkan nama menggunakan select() agar tidak mengandalkan indeks array 0.
• Gunakan |= (operator pembaruan) atau = untuk menetapkan nilai baru.

Menggunakan indeks array (rentan jika daftar container berubah):

• yq -i '.spec.template.spec.containers[0].image = "my-app:2.1.0"' deployment.yaml

Menggunakan select() (andal):

• yq -i '(.spec.template.spec.containers[] | select(.name == "app")).image = "my-app:2.1.0"' deployment.yaml

Dalam pipeline CI, Anda akan meneruskan tag sebagai variabel shell:

Selain memperbarui bidang yang sudah ada, yq dapat menambahkan kunci baru atau menghapus kunci yang sudah ada.

Menambahkan bidang:

• Cukup tetapkan nilai ke jalur yang belum ada: yq -i '.metadata.labels.version = "v2"' file.yaml
• Jika kunci induk (labels) tidak ada, yq akan membuatnya secara otomatis.

Menghapus bidang:

• Gunakan fungsi del(): yq -i 'del(.metadata.annotations)' file.yaml
• Hapus elemen array berdasarkan indeks: yq -i 'del(.spec.template.spec.containers[1])' file.yaml

Menambahkan elemen ke array:

• yq -i '.spec.template.spec.containers += [{"name": "sidecar", "image": "envoy:latest"}]' file.yaml

Manifes Kubernetes sering menggabungkan beberapa sumber daya dalam satu file yang dipisahkan oleh ---. Secara default, yq memproses semua dokumen dalam file tersebut.

Teknik utama:

• Daftarkan semua jenis dokumen: yq '.[].kind' multi.yaml — perhatikan .[] di awal untuk mengiterasi dokumen.
• Tentukan dokumen tertentu berdasarkan jenisnya: yq 'select(.kind == "Service")' multi.yaml
• Edit hanya dokumen yang cocok di tempat:

yq -i 'select(.kind == "Deployment").spec.replicas = 2' multi.yaml

Dokumen yang tidak cocok dengan predikat select() diteruskan tanpa perubahan, sehingga Service, ConfigMap, dan sumber daya Anda lainnya tetap utuh.

Untuk memisahkan file multi-dokumen menjadi file individual, Anda dapat melakukan perulangan pada keluaran yq atau menggunakan:

• yq -s '.kind' multi.yaml — menulis satu file untuk setiap dokumen dengan nama berdasarkan nilai .kind-nya.

File konfigurasi CI (.github/workflows/*.yml, .gitlab-ci.yml) juga merupakan YAML. Perintah yq yang sama dapat digunakan, meskipun jalurnya mungkin sangat bertingkat.

Tugas penambalan CI yang umum:

• Menetapkan versi runner: perbarui runs-on di seluruh pekerjaan.
• Memperbarui versi action: temukan langkah yang menggunakan action tertentu dan naikkan bidang uses-nya.
• Mengubah tanda: aktifkan atau nonaktifkan pengaturan tingkat alur kerja.

Contoh: perbarui semua langkah yang menggunakan actions/checkout ke v4:

yq -i '(.jobs[].steps[] | select(.uses == "actions/checkout@v3")).uses = "actions/checkout@v4"' .github/workflows/ci.yml

Idiom ini — iterasikan dengan [], persempit dengan select(), tetapkan dengan = — merupakan pola inti untuk setiap pengeditan YAML terstruktur.

Menuliskan nilai secara langsung dalam ekspresi yq membuat skrip rentan. yq mendukung penyisipan variabel shell menggunakan fungsi env() atau singkatan strenv().

• env(VAR_NAME) — membaca variabel lingkungan dan mengonversinya ke tipe YAML yang sesuai (angka tetap menjadi angka, string tetap menjadi string).
• strenv(VAR_NAME) — selalu mengembalikan string, berguna untuk tag image.

Ini menghindari kerumitan pengutipan saat menginterpolasi variabel di dalam string shell yang diapit tanda kutip ganda dan berisi jalur YAML.

Pola:

export IMAGE_TAG="my-app:3.0.0"
yq -i '.spec.template.spec.containers[0].image = strenv(IMAGE_TAG)' deployment.yaml

Gunakan env() saat menetapkan bidang numerik seperti replicas agar tipe YAML tetap dipertahankan (bilangan bulat, bukan string yang diapit tanda kutip).

Terkadang Anda perlu menerapkan berkas patch (YAML penimpaan kecil) ke konfigurasi dasar—misalnya, penimpaan khusus lingkungan dalam alur kerja bergaya Kustomize.

yq dapat menggabungkan dua berkas menggunakan * operator penggabungan:

• yq '. *= load("patch.yaml")' base.yaml — menggabungkan patch secara mendalam ke konfigurasi dasar dan menulis hasilnya ke stdout.
• Tambahkan -i untuk memperbarui konfigurasi dasar di tempat: yq -i '. *= load("patch.yaml")' base.yaml

Perilaku penggabungan:

• Nilai skalar dalam patch menimpa konfigurasi dasar.
• Pemetaan digabungkan secara mendalam (kunci yang tidak ada dalam patch tetap dipertahankan).
• Urutan (array) secara bawaan diganti, bukan ditambahkan. Gunakan *+ untuk menambahkan.

Pola ini menggantikan skrip sed yang rapuh dan rusak saat terjadi perubahan spasi.

Sebelum menerapkan YAML yang telah di-patch ke klaster, sebaiknya Anda memvalidasinya dan, jika diperlukan, mengonversinya ke JSON untuk alat lain.

Validasi sintaks:

• yq '.' file.yaml && echo "Valid" — yq keluar dengan kode 1 jika terjadi kesalahan penguraian, sehingga perintah ini dapat digunakan dalam pemeriksaan CI.

Mengonversi YAML ke JSON:

• yq -o=json '.' file.yaml — menghasilkan JSON berformat rapi.
• Salurkan ke jq untuk pemrosesan JSON lebih lanjut: yq -o=json '.' file.yaml | jq '.metadata.name'

Mengonversi JSON ke YAML:

• yq -P '.' file.json — tanda -P memaksa keluaran YAML (berformat rapi) saat masukannya berupa JSON.

Konversi ini menjadikan yq sebagai jembatan antara alat berbasis YAML (Helm, kubectl) dan alat berbasis JSON (Terraform, AWS CLI, jq).

Menggabungkan semua teknik: skrip CI nyata yang melakukan patch pada manifes Deployment Kubernetes sebagai bagian dari alur GitOps.

Skrip ini:

1. Memvalidasi YAML masukan sebelum memprosesnya.
2. Menggunakan env() / strenv() untuk semua penggantian variabel.
3. Memperbarui tag image kontainer menggunakan select() berbasis nama.
4. Menaikkan jumlah replika.
5. Menambahkan anotasi deploy-time dengan stempel waktu saat ini.
6. Memvalidasi keluaran sekali lagi sebelum melakukan commit.

Pola ini memastikan bahwa meskipun alur berjalan secara bersamaan, setiap langkah berlangsung secara atomis dan dapat diaudit.

Anda telah menyelesaikan pelajaran tentang menyunting berkas konfigurasi YAML dengan yq. Berikut ringkasan singkat semua materi yang dibahas:

• Instalasi: Gunakan biner Go mikefarah/yq (v4). Verifikasi dengan yq --version.
• Membaca: Jalur notasi titik seperti .spec.replicas; akses array dengan iterasi [0] atau [].
• Penyuntingan di tempat: Tanda -i menulis ulang berkas. Selalu tampilkan pratinjau tanpa -i terlebih dahulu.
• Penargetan yang tangguh: Utamakan select(.name == "app") daripada indeks array yang ditulis secara permanen.
• Menambahkan / menghapus: Tetapkan nilai ke jalur baru untuk membuatnya; gunakan del() untuk menghapus bidang.
• Berkas banyak dokumen: Gunakan select(.kind == "...") untuk menargetkan satu sumber daya dan membiarkan yang lain tanpa perubahan.
• Variabel CI: Gunakan strenv(VAR) untuk string dan env(VAR) untuk nilai bertipe—cara ini menghindari masalah pengutipan shell.
• Penggabungan: . *= load("patch.yaml") menggabungkan berkas penimpaan secara mendalam tanpa kehilangan kunci yang tidak diubah oleh patch.
• Validasi & konversi: Gunakan yq '.' sebagai pemeriksaan lint; -o=json dan -P untuk konversi format.

Pola inti untuk patch YAML apa pun dalam CI adalah: validasi → pilih → tetapkan → validasi. Gabungkan pola ini dengan strenv() dan select(), dan Anda tidak perlu lagi menggunakan perintah satu baris sed yang rapuh.