YAML dla początkujących: Opanowanie plików konfiguracyjnych

Jeśli pracujesz z Dockerem, Kubernetes, GitHub Actions lub praktycznie dowolnym nowoczesnym narzędziem DevOps, już używasz YAML, czy zdajesz sobie z tego sprawę, czy nie. YAML (co oznacza „YAML Ain't Markup Language" — tak, to rekurencyjny akronim) został zaprojektowany jako najbardziej czytelny dla człowieka format danych.

Nauczmy się go razem, krok po kroku.

Dlaczego YAML istnieje

JSON jest świetny dla maszyn, ale czy kiedykolwiek próbowałeś napisać 200-liniowy plik konfiguracyjny w JSON? Brak komentarzy, wszędzie obowiązkowe podwójne cudzysłowy, pięć poziomów zagnieżdżonych nawiasów klamrowych... szybko robi się męcząco. YAML został stworzony, żeby to rozwiązać. Używa wcięć zamiast nawiasów, co sprawia, że konfiguracje wyglądają czysto i przejrzyście.

Oto te same dane w JSON i YAML. Widzisz różnicę?

JSON:

YAML:

Podstawy, które musisz znać

Pary klucz-wartość to chleb powszedni YAML. Po prostu użyj dwukropka i spacji: name: John Doe. To wszystko — cudzysłowy nie są potrzebne dla większości stringów.

Wcięcia to wszystko. YAML używa spacji (nigdy tabulatorów!) do pokazywania struktury. Standard to 2 spacje na poziom. Pomyl się i twój plik się zepsuje. Serio — specyfikacja YAML jest w tej kwestii rygorystyczna.

Oto przykład zagnieżdżonych danych:

Listy używają myślnika i spacji. Oto lista zakupów w YAML:

Stringi: trudniejsze niż myślisz

Większość stringów nie potrzebuje cudzysłowów w YAML. Ale powinieneś ich używać, gdy zawierają dwukropki, hashe lub mogą zostać źle zinterpretowane. Na przykład country: NO jest interpretowane jako country: false w YAML 1.1, ponieważ NO jest traktowane jako boolean. To słynny „problem Norwegii", który spowodował prawdziwe błędy w produkcji.

W razie wątpliwości użyj cudzysłowów: country: "NO"

Wieloliniowe stringi są niesamowite

To jest miejsce, gdzie YAML naprawdę błyszczy. Pipe | zachowuje znaki nowej linii (idealne dla skryptów), a > zamienia je na spacje (idealne dla długich opisów):

Kotwice i aliasy: pliki konfiguracyjne DRY

Jedna z najfajniejszych funkcji YAML. Zdefiniuj coś raz za pomocą &, odwołaj się później za pomocą *:

Blok production dziedziczy retries: 3 z defaults, ale nadpisuje timeout. To jest niezwykle przydatne w workflowach GitHub Actions i plikach Docker Compose, gdzie w przeciwnym razie powtarzałbyś te same bloki konfiguracyjne w kółko.

4 najczęstsze błędy YAML

• Tabulatory zamiast spacji — Twój edytor może domyślnie wstawiać tabulatory. Skonfiguruj go, aby używał spacji w plikach YAML. Serio, zrób to teraz.
• Pułapki boolean — yes, no, on, off, true, false to WSZYSTKO booleany w YAML 1.1. Użyj cudzysłowów, jeśli masz na myśli string.
• Dwukropki w wartościach — message: Error: file not found się zepsuje, ponieważ YAML widzi drugi separator klucz-wartość. Użyj cudzysłowów: message: "Error: file not found"
• Końcowe białe znaki — Niewidoczne spacje na końcu linii mogą powodować dziwne zachowanie parsera. Używaj edytora, który podświetla końcowe białe znaki.

Gdzie będziesz używać YAML codziennie

YAML to język konfiguracji dla Docker Compose, manifestów Kubernetes, GitHub Actions, GitLab CI, playbooków Ansible i dziesiątek innych narzędzi. Jeśli robisz cokolwiek w DevOps lub chmurze, biegłość w YAML jest niezbędna.

Masz plik YAML, który dziwnie się zachowuje? Wklej go do naszego YAML Validator, aby natychmiast znaleźć problem.

Przykład z życia: Docker Compose

Spójrzmy na realistyczny plik Docker Compose — taki, jaki faktycznie napisałbyś dla aplikacji webowej:

Zwróć uwagę na kilka rzeczy: zmienne środowiskowe można zapisywać jako listę (- KEY=value) lub jako mapowanie (KEY: value). Oba sposoby działają w Docker Compose — ale wybierz jeden styl i trzymaj się go dla spójności.

Przykład z życia: Pipeline CI w GitHub Actions

Oto workflow GitHub Actions, który uruchamia testy przy każdym pushu:

To jest czyste, czytelne i samo się wyjaśnia. Wyobraź sobie pisanie tego samego workflow w JSON — byłby dwa razy dłuższy i znacznie trudniejszy do ogarnięcia wzrokiem.

YAML vs JSON vs TOML: Szybkie porównanie

YAML nie jest jedyną alternatywą dla JSON do plików konfiguracyjnych. TOML to kolejny popularny wybór (używany przez Cargo.toml w Rust i pyproject.toml w Pythonie). Oto jak się ze sobą porównują:

Zaawansowany YAML: Wiele dokumentów w jednym pliku

YAML obsługuje wiele dokumentów w jednym pliku, rozdzielonych przez ---. Jest to powszechnie używane w Kubernetes do wdrażania wielu zasobów na raz:

Separator --- mówi parserowi YAML „to jest nowy dokument". Możesz wykonać kubectl apply -f na takim pliku, a Kubernetes utworzy oba zasoby.

Bezpieczeństwo YAML: Atak Billion Laughs

Oto coś, czego większość początkujących nie wie: YAML może stanowić zagrożenie bezpieczeństwa, jeśli nie będziesz ostrożny. Atak „Billion Laughs" wykorzystuje kotwice i aliasy do tworzenia wykładniczej ekspansji danych:

Ten maleńki plik może rozrosnąć się w pamięci do gigabajtów i zawiesić twoją aplikację. Lekcja? Nigdy nie parsuj niezaufanego wejścia YAML. Używaj bezpiecznych funkcji ładowania, takich jak yaml.safe_load() w Pythonie zamiast yaml.load(), i ustaw limity pamięci na swoim parserze YAML.

Konwersja między YAML i JSON

Ponieważ YAML jest nadzbiorem JSON (tak, poprawny JSON jest również poprawnym YAML!), konwersja między nimi jest prosta. To przydatne, gdy chcesz korzystać z czytelności YAML do pisania konfiguracji, ale potrzebujesz JSON dla API lub narzędzia, które go wymaga.

Nasz konwerter YAML do JSON obsługuje to natychmiastowo — po prostu wklej swój YAML i otrzymaj czysty wynik JSON. W drugą stronę? Każdy JSON, który masz, jest już poprawnym YAML.

Wypróbuj sam

Niezależnie od tego, czy debugujesz uszkodzony manifest Kubernetes, czy konfigurujesz nowy potok CI, te narzędzia zaoszczędzą ci czasu:

• YAML Formatter — Napraw wcięcia i spraw, by twoje pliki YAML były czyste i spójne.
• YAML Validator — Wyłap błędy składni, zanim zepsują twoje wdrożenie.
• Konwerter YAML do JSON — Konwertuj między formatami, gdy musisz współpracować z narzędziami obsługującymi tylko JSON.

YAML ma swoje dziwactwa, ale gdy przywykniesz do składni opartej na wcięciach, docenisz, o ile czyściej wyglądają twoje pliki konfiguracyjne w porównaniu z alternatywą JSON.