YAML aloittelijoille: Konfiguraatiotiedostojen hallinta

Jos työskentelet Dockerin, Kubernetesin, GitHub Actionsin tai käytännössä minkä tahansa modernin DevOps-työkalun kanssa, käytät jo YAMLia, tiedostitpa sitä tai et. YAML (joka tarkoittaa "YAML Ain't Markup Language" — kyllä, se on rekursiivinen lyhenne) suunniteltiin olemaan mahdollisimman ihmisluettava dataformaatti.

Opitaan se yhdessä, yksi käsite kerrallaan.

Miksi YAML on olemassa

JSON on mahtava koneille, mutta oletko koskaan yrittänyt kirjoittaa 200-rivisen konfiguraatiotiedoston JSONilla? Ei kommentteja, pakolliset lainausmerkit kaikkialla, viisi tasoa sisäkkäisiä aaltosulkeita... se käy nopeasti tuskalliseksi. YAML luotiin ratkaisemaan tämä ongelma. Se käyttää sisennystä sulkeiden sijaan, mikä tekee konfiguraatioista siistejä ja helppolukuisia.

Tässä samat tiedot JSONissa ja YAMLissa. Näetkö eron?

JSON:

YAML:

Perusteet jotka sinun pitää tietää

Avain-arvo-parit ovat YAMLin peruskauraa. Käytä vain kaksoispistettä ja välilyöntiä: name: John Doe. Siinä se — lainausmerkkejä ei tarvita useimmille merkkijonoille.

Sisennys on kaikki kaikessa. YAML käyttää välilyöntejä (ei koskaan tabulaattoreita!) rakenteen näyttämiseen. Standardi on 2 välilyöntiä per taso. Tee tämä väärin ja tiedostosi hajoaa. Tosissaan — YAML-spesifikaatio on tästä tiukka.

Tässä esimerkki sisäkkäisestä datasta:

Listat käyttävät viivaa ja välilyöntiä. Tässä ostoslista YAMLilla:

Merkkijonot: hankalampia kuin luulisi

Useimmat merkkijonot eivät tarvitse lainausmerkkejä YAMLissa. Mutta niitä kannattaa käyttää, kun ne sisältävät kaksoispisteitä, risuaitoja tai ne voitaisiin tulkita väärin. Esimerkiksi country: NO tulkitaan YAML 1.1:ssä muotoon country: false, koska NO käsitellään totuusarvona. Tämä on kuuluisa "Norja-ongelma" ja se on aiheuttanut oikeita bugeja tuotannossa.

Epävarmoissa tilanteissa käytä lainausmerkkejä: country: "NO"

Moniriviset merkkijonot ovat mahtavia

Tässä YAML todella loistaa. Putki | säilyttää rivinvaihdot (loistava skripteille), kun taas > taittaa ne välilyönneiksi (loistava pitkille kuvauksille):

Ankkurit ja aliakset: DRY-konfiguraatiotiedostot

Yksi YAMLin hienoimmista ominaisuuksista. Määritä jotain kerran &:lla, viittaa siihen myöhemmin *:lla:

production-lohko perii retries: 3 oletuksista mutta ylikirjoittaa timeout-arvon. Tämä on uskomattoman hyödyllistä GitHub Actions -työnkuluissa ja Docker Compose -tiedostoissa, joissa muuten toistaisit samoja konfiguraatiolohkoja yhä uudelleen.

4 yleisintä YAML-virhettä

• Tabulaattorit välilyöntien sijaan — Editorisi saattaa lisätä tabulaattoreita oletuksena. Aseta se käyttämään välilyöntejä YAML-tiedostoissa. Tosissaan, tee se nyt.
• Totuusarvo-ansat — yes, no, on, off, true, false ovat KAIKKI totuusarvoja YAML 1.1:ssä. Käytä lainausmerkkejä, jos tarkoitat merkkijonoa.
• Kaksoispisteet arvoissa — message: Error: file not found hajoaa, koska YAML näkee toisen avain-arvo-erottimen. Käytä lainausmerkkejä: message: "Error: file not found"
• Loppuvälilyönnit — Näkymättömät välilyönnit rivien lopussa voivat aiheuttaa outoa jäsennöskäyttäytymistä. Käytä editoria, joka korostaa loppuvälilyöntejä.

Missä käytät YAMLia joka päivä

YAML on konfiguraatiokieli Docker Composelle, Kubernetes-manifesteille, GitHub Actionsille, GitLab CI:lle, Ansible-playbookeille ja kymmenille muille. Jos teet mitään DevOpsissa tai pilvessä, YAML-osaaminen on välttämätöntä.

Onko sinulla YAML-tiedosto, joka käyttäytyy oudosti? Liitä se YAML Validator -työkaluumme löytääksesi ongelman välittömästi.

Käytännön YAML: Docker Compose -esimerkki

Katsotaan realistista Docker Compose -tiedostoa — sellaista, jonka todella kirjoittaisit verkkosovellukselle:

Huomaa muutama asia: ympäristömuuttujat voidaan kirjoittaa listana (- KEY=value) tai mappingina (KEY: value). Molemmat toimivat Docker Composessa — mutta valitse yksi tyyli ja pidä siitä kiinni johdonmukaisuuden vuoksi.

Käytännön YAML: GitHub Actions CI-putki

Tässä GitHub Actions -työnkulku, joka ajaa testit jokaisella pushilla:

Tämä on siistiä, luettavaa ja itsestään selvää. Kuvittele saman työnkulun kirjoittaminen JSONilla — se olisi kaksi kertaa pidempi ja visuaalisesti paljon vaikeampi hahmottaa.

YAML vs JSON vs TOML: Pikavertailu

YAML ei ole ainoa vaihtoehto JSONille konfiguraatiotiedostoissa. TOML on toinen suosittu vaihtoehto (jota käytetään Rustin Cargo.toml-tiedostossa ja Pythonin pyproject.toml-tiedostossa). Näin ne vertautuvat:

Edistynyt YAML: Useita dokumentteja yhdessä tiedostossa

YAML tukee useita dokumentteja yhdessä tiedostossa, erotettuna ----merkinnällä. Tätä käytetään yleisesti Kubernetesissa useiden resurssien käyttöönottamiseen kerralla:

----erotin kertoo YAML-jäsentimelle "tämä on uusi dokumentti." Voit suorittaa kubectl apply -f tällaiselle tiedostolle ja Kubernetes luo molemmat resurssit.

YAML-turvallisuus: Billion Laughs -hyökkäys

Tässä jotain, mitä useimmat aloittelijat eivät tiedä: YAML voi olla turvallisuusriski, jos et ole varovainen. "Billion Laughs" -hyökkäys käyttää ankkureita ja aliaksia luodakseen eksponentiaalisen datan laajenemisen:

Tämä pieni tiedosto voi laajeta gigatavuiksi muistissa ja kaataa sovelluksesi. Opetus? Älä koskaan jäsennä epäluotettavaa YAML-syötettä. Käytä turvallisia latausfunktioita kuten yaml.safe_load() Pythonissa yaml.load()-funktion sijaan, ja aseta muistirajoituksia YAML-jäsentimellesi.

Muuntaminen YAMLin ja JSONin välillä

Koska YAML on JSONin ylijoukko (kyllä, kelvollinen JSON on myös kelvollista YAMLia!), muuntaminen näiden välillä on suoraviivaista. Tämä on hyödyllistä, kun haluat käyttää YAMLin luettavuutta konfiguraatioiden kirjoittamiseen, mutta tarvitset JSONia API:lle tai työkalulle, joka vaatii sitä.

YAML-JSON-muuntimemme hoitaa tämän hetkessä — liitä vain YAMLisi ja saat siistin JSON-tulosteen. Toiseen suuntaan? Mikä tahansa JSON sinulla on, on jo kelvollista YAMLia.

Kokeile itse

Debuggaatpa rikkinäistä Kubernetes-manifestia tai pystytät uutta CI-putkea, nämä työkalut säästävät aikaasi:

• YAML Formatter — Korjaa sisennys ja tee YAML-tiedostoistasi siistejä ja johdonmukaisia.
• YAML Validator — Havaitse syntaksivirheet ennen kuin ne rikkovat käyttöönoton.
• YAML-JSON-muunnin — Muunna formaattien välillä, kun sinun täytyy toimia JSON-only-työkalujen kanssa.

YAMLilla on omat oikkuunsa, mutta kun totut sisennyspohjaiseen syntaksiin, arvostat kuinka paljon siistimmiltä konfiguraatiotiedostosi näyttävät verrattuna JSON-vaihtoehtoon.