Mengedit Fail Konfigurasi YAML dengan yq

yq ialah pemproses YAML baris perintah mudah alih, sama seperti cara jq mengendalikan JSON. Dengannya, anda boleh membaca, menapis dan menyunting fail YAML tanpa menulis skrip dalam Python atau Ruby.

Terdapat dua alat popular yang bernama yq:

• mikefarah/yq (Go) — diselenggara secara aktif serta menyokong YAML, JSON, XML dan TOML. Pelajaran ini menggunakan versi ini.
• kislyuk/yq (Python) — pembungkus jq untuk YAML; sintaksnya berbeza.

Pasang versi Go:

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

Sahkan: yq --version sepatutnya mencetak v4.x.x. Versi 4 menggunakan sintaks ungkapan yang berbeza daripada v3, jadi versi adalah penting.

Sebelum menyunting apa-apa, pelajari cara membaca medan YAML. Diberi Deployment Kubernetes, anda boleh mengekstrak sebarang nilai bersarang menggunakan laluan 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 pembacaan utama:

• 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

Output ialah teks biasa secara lalai (tanpa petikan). Tambahkan bendera -r atau gunakan | yq -r jika anda memerlukan rentetan mentah dalam skrip.

Bendera paling penting untuk penggunaan sebenar ialah -i (di tempat). Tanpanya, yq mencetak hasil ke stdout dan membiarkan fail tanpa perubahan.

Sintaks:

• Baca sahaja (stdout): yq '.spec.replicas' file.yaml
• Sunting di tempat: yq -i '.spec.replicas = 5' file.yaml

Operator penetapan = menetapkan nilai. Ungkapan tersebut ialah penapis yq penuh, jadi anda boleh menggabungkan pembacaan dan penulisan dalam satu laluan.

Penting: yq -i menulis semula keseluruhan fail. Komen yang diletakkan pada baris yang sama dengan medan biasanya dikekalkan, tetapi blok komen kendiri mungkin berubah kedudukan. Sentiasa lakukan commit YAML anda ke kawalan versi sebelum menjalankan suntingan di tempat secara pukal.

Uji dahulu tanpa -i, kemudian tambahkannya setelah anda berpuas hati dengan output.

Tugas CI yang sangat biasa ialah menaik taraf tag imej Docker dalam manifes Kubernetes selepas imej baharu dibina. Dengan yq, tugas ini menjadi satu baris perintah.

Coraknya ialah:

• Sasarkan kontena mengikut nama menggunakan select() untuk mengelakkan pengekodan indeks tatasusunan 0 secara terus.
• Gunakan |= (operator kemas kini) atau = untuk menetapkan nilai baharu.

Menggunakan indeks tatasusunan (rapuh jika senarai kontena berubah):

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

Menggunakan select() (kukuh):

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

Dalam pipeline CI, anda akan menghantar tag sebagai pemboleh ubah shell:

Selain mengemas kini medan sedia ada, yq boleh menambah kunci baharu atau memadam kunci sedia ada.

Menambah medan:

• Berikan nilai kepada laluan yang belum wujud: yq -i '.metadata.labels.version = "v2"' file.yaml
• Jika kunci induk (labels) tiada, yq akan menciptanya secara automatik.

Memadam medan:

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

Menambah elemen pada tatasusunan:

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

Manifes Kubernetes sering menghimpunkan berbilang sumber dalam satu fail yang dipisahkan oleh ---. Secara lalai, yq memproses semua dokumen dalam fail tersebut.

Teknik utama:

• Senaraikan semua jenis dokumen: yq '.[].kind' multi.yaml — perhatikan .[] pada permulaan untuk mengulangi dokumen.
• Sasarkan dokumen tertentu mengikut jenis: yq 'select(.kind == "Service")' multi.yaml
• Sunting hanya dokumen yang sepadan di tempat:

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

Dokumen yang tidak sepadan dengan predikat select() diteruskan tanpa perubahan, jadi Service, ConfigMap dan sumber lain anda kekal utuh.

Untuk memecahkan fail berbilang dokumen kepada fail individu, anda boleh mengulang output yq atau menggunakan:

• yq -s '.kind' multi.yaml — menulis satu fail bagi setiap dokumen, dinamakan berdasarkan nilai .kind.

Fail konfigurasi CI (.github/workflows/*.yml, .gitlab-ci.yml) juga ialah YAML. Perintah yq yang sama boleh digunakan, walaupun laluannya mungkin sangat bersarang.

Tugas penampalan CI yang biasa:

• Menetapkan versi pelaksana: kemas kini runs-on merentas semua kerja.
• Mengemas kini versi tindakan: cari langkah yang menggunakan tindakan tertentu dan naik taraf medan usesnya.
• Menogol bendera: hidupkan atau matikan tetapan pada peringkat aliran kerja.

Contoh: kemas kini semua langkah yang menggunakan actions/checkout kepada v4:

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

Idiom ini — ulang dengan [], kecilkan skop dengan select(), tetapkan dengan = — ialah corak teras untuk sebarang suntingan YAML berstruktur.

Menetapkan nilai secara terus dalam ungkapan yq menjadikan skrip rapuh. yq menyokong penyuntikan pemboleh ubah shell menggunakan env() atau singkatan strenv().

• env(VAR_NAME) — membaca pemboleh ubah persekitaran dan menukarkannya kepada jenis YAML yang sesuai (nombor kekal nombor, rentetan kekal rentetan).
• strenv(VAR_NAME) — sentiasa mengembalikan rentetan, berguna untuk tag imej.

Ini mengelakkan masalah petikan yang rumit apabila pemboleh ubah diinterpolasi dalam rentetan shell yang menggunakan petikan berganda serta mengandungi laluan YAML.

Corak:

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

Gunakan env() apabila menetapkan medan berangka seperti replicas supaya jenis YAML dikekalkan (integer, bukan rentetan berpetik).

Kadangkala anda perlu menggunakan fail tampalan (YAML penggantian kecil) pada konfigurasi asas — contohnya, penggantian khusus persekitaran dalam aliran kerja gaya Kustomize.

yq boleh menggabungkan dua fail menggunakan operator gabungan *:

• yq '. *= load("patch.yaml")' base.yaml — menggabungkan tampalan secara mendalam ke dalam asas dan menulis hasil ke output piawai.
• Tambahkan -i untuk mengemas kini asas di tempatnya: yq -i '. *= load("patch.yaml")' base.yaml

Kelakuan penggabungan:

• Nilai skalar dalam tampalan menggantikan nilai dalam asas.
• Pemetaan digabungkan secara mendalam (kunci yang tiada dalam tampalan dikekalkan).
• Jujukan (tatasusunan) digantikan secara lalai, bukannya ditambahkan. Gunakan *+ untuk menambahkannya.

Pola ini menggantikan skrip sed yang rapuh dan rosak apabila terdapat perubahan ruang kosong.

Sebelum menggunakan YAML yang ditampal pada kluster, amalan yang baik ialah mengesahkannya dan, secara pilihan, menukarnya kepada JSON untuk alat lain.

Sahkan sintaks:

• yq '.' file.yaml && echo "Valid" — yq keluar dengan kod 1 apabila berlaku ralat penghuraian, jadi arahan ini berfungsi dalam pintu kawalan CI.

Tukar YAML kepada JSON:

• yq -o=json '.' file.yaml — menghasilkan JSON berformat kemas.
• Salurkan kepada jq untuk pemprosesan JSON selanjutnya: yq -o=json '.' file.yaml | jq '.metadata.name'

Tukar JSON kepada YAML:

• yq -P '.' file.json — bendera -P memaksa output YAML (berformat kemas) apabila inputnya ialah JSON.

Penukaran ini menjadikan yq sebagai jambatan antara alat asli YAML (Helm, kubectl) dengan alat asli JSON (Terraform, AWS CLI, jq).

Menggabungkan semua teknik: satu skrip CI sebenar yang menampal manifes Deployment Kubernetes sebagai sebahagian daripada aliran GitOps.

Skrip ini:

1. Mengesahkan YAML input sebelum mengubahnya.
2. Menggunakan env() / strenv() untuk semua penggantian pemboleh ubah.
3. Mengemas kini teg imej bekas menggunakan select() berasaskan nama.
4. Menaikkan bilangan replika.
5. Menetapkan anotasi deploy-time dengan cap masa semasa.
6. Mengesahkan output sekali lagi sebelum melakukan serahan.

Pola ini memastikan setiap langkah kekal atomik dan boleh diaudit walaupun aliran berjalan serentak.

Anda telah melengkapkan pelajaran tentang menyunting fail konfigurasi YAML dengan yq. Berikut ialah ringkasan ringkas tentang semua perkara yang dibincangkan:

• Pemasangan: Gunakan perduaan Go mikefarah/yq (v4). Sahkan dengan yq --version.
• Membaca: Laluan notasi titik seperti .spec.replicas; akses tatasusunan dengan [0] atau lelaran [].
• Penyuntingan di tempatnya: Bendera -i menulis semula fail. Sentiasa pratonton dahulu tanpa -i.
• Penyasaran kukuh: Utamakan select(.name == "app") berbanding indeks tatasusunan yang dikodkan secara keras.
• Menambah / memadam: Berikan nilai kepada laluan baharu untuk menciptanya; gunakan del() untuk membuang medan.
• Fail berbilang dokumen: Gunakan select(.kind == "...") untuk menyasarkan satu sumber dan membiarkan sumber lain tanpa perubahan.
• Pemboleh ubah CI: Gunakan strenv(VAR) untuk rentetan dan env(VAR) untuk nilai bert jenis — ini mengelakkan pepijat petikan shell.
• Penggabungan: . *= load("patch.yaml") menggabungkan fail penggantian secara mendalam tanpa kehilangan kunci yang tidak ditampal.
• Pengesahan & penukaran: yq '.' sebagai pintu kawalan pemeriksaan; -o=json dan -P untuk penukaran format.

Pola teras bagi sebarang tampalan YAML dalam CI ialah: sahkan → pilih → berikan → sahkan. Gabungkan ini dengan strenv() dan select(), dan anda tidak lagi perlu menggunakan satu baris sed yang rapuh.