YAML-määritystiedostojen muokkaaminen yq:lla

yq on siirrettävä komentorivin YAML-prosessori, samalla tavoin kuin jq käsittelee JSONia. Sen avulla voit lukea, suodattaa ja muokata YAML-tiedostoja kirjoittamatta skriptiä Pythonilla tai Rubylla.

Nimellä yq tunnetaan kaksi suosittua työkalua:

• mikefarah/yq (Go) — aktiivisesti ylläpidetty, tukee YAML-, JSON-, XML- ja TOML-muotoja. Tässä oppitunnissa käytetään tätä versiota.
• kislyuk/yq (Python) — YAML:lle tarkoitettu jq-kääre, jonka syntaksi poikkeaa toisesta versiosta.

Asenna Go-versio:

• brew install yq macOS:ssä
• snap install yq Linuxissa
• tai lataa binääritiedosto: wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq && chmod +x /usr/local/bin/yq

Vahvista asennus: yq --version tulostaa arvon v4.x.x. Versio 4 käyttää eri lausekesyntaksia kuin versio 3, joten versiolla on merkitystä.

Ennen kuin muokkaat mitään, opettele lukemaan YAML-kenttiä. Kubernetes Deployment -määrityksestä voit poimia minkä tahansa sisäkkäisen arvon piste-erotteisella polulla.

Esimerkkitiedosto 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

Tärkeimmät lukukomennot:

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

Tuloste on oletuksena pelkkää tekstiä (ilman lainausmerkkejä). Lisää -r-valitsin tai käytä muotoa | yq -r, jos tarvitset raakamerkkijonoja skripteissä.

Arkikäytön tärkein valitsin on -i (in-place eli paikallaan muokkaaminen). Ilman sitä yq tulostaa tulokset vakiotulosteeseen ja jättää tiedoston muuttamatta.

Syntaksi:

• Vain luku (vakiotuloste): yq '.spec.replicas' file.yaml
• Muokkaaminen paikallaan: yq -i '.spec.replicas = 5' file.yaml

Sijoitusoperaattori = asettaa arvon. Lauseke on täydellinen yq-suodatin, joten voit yhdistää lukemisen ja kirjoittamisen yhdeksi käsittelykerraksi.

Tärkeää: yq -i kirjoittaa tiedoston kokonaan uudelleen. Kentän kanssa samalla rivillä olevat kommentit yleensä säilyvät, mutta erilliset kommenttilohkot voivat siirtyä. Vie YAML aina versionhallintaan ennen laajojen paikallaan tehtävien muokkausten suorittamista.

Testaa ensin ilman -i-valitsinta ja lisää se vasta, kun olet tyytyväinen tulosteeseen.

Hyvin yleinen CI-tehtävä on Docker-säilökuvan tunnisteen päivittäminen Kubernetes-manifestissa uuden kuvan rakentamisen jälkeen. yq:lla tämä onnistuu yhdellä komennolla.

Malli on seuraava:

• Kohdista säilö sen nimen perusteella käyttämällä select()-funktiota, jotta et sido käsittelyä taulukkoindeksiin 0.
• Aseta uusi arvo käyttämällä |=-päivitysoperaattoria tai =-operaattoria.

Taulukkoindeksin käyttäminen (hauras, jos säilöluettelo muuttuu):

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

select()-funktion käyttäminen (luotettava):

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

CI-putkessa tunniste välitettäisiin shell-muuttujana:

Olemassa olevien kenttien päivittämisen lisäksi yq voi lisätä uusia avaimia tai poistaa olemassa olevia.

Kentän lisääminen:

• Sijoita arvo polkuun, jota ei vielä ole: yq -i '.metadata.labels.version = "v2"' file.yaml
• Jos ylempi avain (labels) puuttuu, yq luo sen automaattisesti.

Kentän poistaminen:

• Käytä del()-funktiota: yq -i 'del(.metadata.annotations)' file.yaml
• Poista taulukon alkio indeksin perusteella: yq -i 'del(.spec.template.spec.containers[1])' file.yaml

Alkion lisääminen taulukkoon:

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

Kubernetes-manifestit sisältävät usein useita resursseja samassa tiedostossa ----erottimilla eroteltuina. Oletusarvoisesti yq käsittelee kaikki tällaisen tiedoston dokumentit.

Tärkeimmät tekniikat:

• Luettele kaikkien dokumenttien tyypit: yq '.[].kind' multi.yaml — huomaa alussa oleva .[], jolla dokumentit käydään läpi.
• Kohdista tiettyyn dokumenttiin tyypin perusteella: yq 'select(.kind == "Service")' multi.yaml
• Muokkaa paikallaan vain ehtoa vastaavia dokumentteja:

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

Dokumentit, jotka eivät vastaa select()-ehtoa, välitetään muuttamattomina eteenpäin, joten Service-, ConfigMap- ja muut resurssisi säilyvät ennallaan.

Voit jakaa monen dokumentin tiedoston yksittäisiksi tiedostoiksi käymällä yq:n tulosteen läpi silmukassa tai käyttämällä seuraavaa komentoa:

• yq -s '.kind' multi.yaml — kirjoittaa jokaisesta dokumentista erillisen tiedoston, joka nimetään sen .kind-arvon mukaan.

CI-määritystiedostot (.github/workflows/*.yml, .gitlab-ci.yml) ovat myös YAML-tiedostoja. Samat yq-komennot toimivat niissäkin, vaikka polut voivat olla syvästi sisäkkäisiä.

Yleisiä CI-paikkaustehtäviä:

• Kiinnitä suorittajan versio: päivitä runs-on kaikissa töissä.
• Päivitä actionin versio: etsi tiettyä actionia käyttävät vaiheet ja päivitä niiden uses-kenttä.
• Vaihda valitsimen tila: ota työnkulun tason asetus käyttöön tai poista se käytöstä.

Esimerkki: päivitä kaikki actions/checkout-actionia käyttävät vaiheet versioon v4:

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

Tämä idiomi — käy läpi []-operaattorilla, rajaa select()-funktiolla ja sijoita =-operaattorilla — on kaikkien rakenteisten YAML-muokkausten perusmalli.

Arvojen kirjoittaminen suoraan yq-lausekkeisiin tekee skripteistä hauraita. yq tukee shell-muuttujien lisäämistä käyttämällä env()-funktiota tai strenv()-lyhennettä.

• env(VAR_NAME) — lukee ympäristömuuttujan ja muuntaa sen sopivaksi YAML-tyypiksi (luku säilyy lukuna ja merkkijono merkkijonona).
• strenv(VAR_NAME) — palauttaa aina merkkijonon, mikä on hyödyllistä kuvatunnisteille.

Näin vältetään muuttujien interpolointiin liittyvä lainausmerkkikaaos, kun muuttujia sijoitetaan YAML-polkuja sisältäviin kaksinkertaisilla lainausmerkeillä rajattuihin shell-merkkijonoihin.

Malli:

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

Käytä env()-funktiota numeeristen kenttien, kuten replicas-kentän, asettamiseen, jotta YAML-tyyppi säilyy kokonaislukuna eikä muutu lainausmerkeillä ympäröidyksi merkkijonoksi.

Joskus paikkotiedosto (pieni YAML-ohitustiedosto) on yhdistettävä perusasetuksiin — esimerkiksi ympäristökohtaisten ohitusten toteuttamiseksi Kustomize-tyylisissä työnkuluissa.

yq voi yhdistää kaksi tiedostoa *-yhdistämisoperaattorilla:

• yq '. *= load("patch.yaml")' base.yaml — yhdistää paikkotiedoston syvällisesti perusasetuksiin ja kirjoittaa tuloksen vakiotulosteeseen.
• Lisää -i, jos haluat päivittää perusasetukset suoraan tiedostoon: yq -i '. *= load("patch.yaml")' base.yaml

Yhdistämisen toiminta:

• Paikkotiedoston skalaariarvot korvaavat perusasetusten arvot.
• Avain–arvo-kartat yhdistetään syvällisesti (paikkotiedostossa määrittelemättömät avaimet säilyvät).
• Sekvenssit (taulukot) korvataan oletusarvoisesti, eikä niiden perään lisätä arvoja. Käytä sen sijaan *+-operaattoria, jos haluat lisätä arvot perään.

Tämä toimintamalli korvaa hauraat sed-komentosarjat, jotka rikkoutuvat välilyöntien muuttuessa.

Ennen kuin paikatun YAML-tiedoston muutokset otetaan käyttöön klusterissa, tiedosto kannattaa validoida ja muuntaa tarvittaessa JSON-muotoon muita työkaluja varten.

Syntaksin validointi:

• yq '.' file.yaml && echo "Valid" — jäsennysvirheen yhteydessä yq palauttaa paluuarvon 1, joten tämä sopii CI-tarkistuksiin.

YAML:n muuntaminen JSON-muotoon:

• yq -o=json '.' file.yaml — tulostaa muotoillun JSON-tulosteen.
• Välitä tulos jq:lle JSON-käsittelyä varten: yq -o=json '.' file.yaml | jq '.metadata.name'

JSON:n muuntaminen YAML-muotoon:

• yq -P '.' file.json — -P-lippu pakottaa YAML-muotoisen (prettyprint) tulosteen, kun syöte on JSON-muodossa.

Näiden muunnosten ansiosta yq toimii siltana YAML-pohjaisten työkalujen (Helm, kubectl) ja JSON-pohjaisten työkalujen (Terraform, AWS CLI, jq) välillä.

Yhdistetään kaikki tekniikat: tosielämän CI-ohjelma, joka muokkaa Kubernetes Deployment -manifestia osana GitOps-putkea.

Ohjelma:

1. Validoi syötteenä olevan YAML-tiedoston ennen sen käsittelyä.
2. Käyttää env()- ja strenv()-funktioita kaikissa muuttujien korvauksissa.
3. Päivittää kontin image-tagin nimipohjaisella select()-valinnalla.
4. Kasvattaa replikoiden määrää.
5. Lisää deploy-time-annotaatioon nykyisen aikaleiman.
6. Validoi tuloksen uudelleen ennen muutosten commitoimista.

Tämä toimintamalli varmistaa, että vaikka putki suoritettaisiin samanaikaisesti, jokainen vaihe on atominen ja tarkastettavissa.

Olet suorittanut oppitunnin, jossa käsiteltiin YAML-asetustiedostojen muokkaamista yq:lla. Tässä on tiivis yhteenveto kaikesta käsitellystä:

• Asennus: Käytä mikefarah/yq:n Go-binääriä (v4). Tarkista asennus komennolla yq --version.
• Lukeminen: Piste-merkintää käyttävät polut, kuten .spec.replicas; taulukoiden käsittely [0]-indeksillä tai []-iteraatiolla.
• Muokkaaminen suoraan tiedostoon: -i-lippu kirjoittaa tiedoston uudelleen. Esikatsele tulos aina ensin ilman -i-lippua.
• Luotettava kohdistaminen: Suosi select(.name == "app")-valintaa kovakoodattujen taulukkoindeksien sijaan.
• Lisääminen ja poistaminen: Määritä arvo uuteen polkuun luodaksesi sen; poista kenttiä del()-funktiolla.
• Usean dokumentin tiedostot: Kohdista yhteen resurssiin käyttämällä select(.kind == "...")-valintaa ja jätä muut resurssit koskemattomiksi.
• CI-muuttujat: Käytä merkkijonoille strenv(VAR)-funktiota ja tyypitetyille arvoille env(VAR)-funktiota — näin vältät komentotulkin lainausmerkkien käsittelyyn liittyvät virheet.
• Yhdistäminen: . *= load("patch.yaml") yhdistää ohitustiedoston syvällisesti menettämättä paikkotiedostossa määrittelemättömiä avaimia.
• Validointi ja muuntaminen: Käytä yq '.'-komentoa lint-tarkistuksena sekä -o=json- ja -P-valitsimia muodon muuntamiseen.

CI-ympäristön YAML-paikkauksen perusmalli on: validoi → valitse → määritä → validoi. Kun yhdistät tähän strenv()- ja select()-funktiot, sinun ei enää tarvitse turvautua hauraisiin sed-yhden rivin komentoihin.