Co to jest YAML?

W dzisiejszym artykule omówimy podstawy oraz najczęściej używane funkcje YAML. Zarówno zasadę działania jak i sposób korzystania z wbudowanych typów danych czy struktury złożonych dokumentów. Przede wszystkim, odpowiemy na pytanie „Co to jest YAML?”

Spis Treści:

YAML
Przykład
Wcięcia
Komentarze
Typy Danych
Klucz i Wartość
Null
Logiczny typ danych
Tablice
Oznaczenie początku i zakończenia pliku YAML
Przykład
Listy
Inny przykład
Przykłady z życia wzięte
Ansible
Docker
Sprawdzanie składni
Multiline string
Edytory
Konwerter
Podsumowanie

YAML

Zacznijmy od tego co sami twórcy YAML mówią o własnym dziecku.

Jak możemy znaleźć na stronie yaml.org, Yaml to nie jest kolejny język znaczników. YAML to czytelny i przyjazny dla człowieka standard serializacji danych. Możesz go stosować we wszystkich językach programowania jak i używać do tworzenia plików konfiguracyjnych. Administratorzy mogą kojarzyć ten standard z tworzenia playbooków w popularnym Ansible czy konfiguracji kontenerów w Docker lub Kubernetes. Ewentualnie z systemów monitoringu, Zabbix i prometheus.

YAML obsługuje szeroką liczbę języków i łatwo odwzorowuje natywne struktury danych. Jest również łatwy do odczytania i zrozumienia. Dlatego też jest dobrym wyborem do tworzenia plików konfiguracji. Szczególnie dla administratorów, którzy nie mają dużego doświadczenia z kodowaniem.

Ciekawostka. Akronim YAML był skrótem od Yet Another Markup Language. Ale twórcy zmienili jego nazwę na YAML Ain’t Markup Language. Chcieli dać do zrozumienia, że kładą większy nacisk na jego funkcje zorientowane na dane.

Przykład

Mamy taki plik YAML:

---
 focus: "Samochód, model Forda "
 saturn: "Planeta w układzie słonecznym"
 powierzchnia: 510,22
 ocean: true
 Dni: 5
 Waluty:
   - dolar
   - złotówka
   - euro
   - funt
 wakacje:
   transport: samolot
   nocleg: hotel
   posiłki: "na miejscu"

Co to oznacza? Plik zaczyna się od trzech myślników. Te myślniki wskazują początek nowego dokumentu YAML. Oznacza start kodu. Można je pominąć. Trochę to taka zaszłość historyczna. Mimo wszystko, dobrze jest stosować w celu ułatwienia czytelności kodu w przyszłości.

Następnie widzimy typową konstrukcję języka YAML. Focus to klucz, który wskazuje na wartości ciągu.

Wymieniony wyżej plik rozpoczyna się od sześciu par klucz-wartość. Zawarte zostały w nich cztery różne typy danych:

Klucze:	Typ Danych
focus i saturn	Tekstowy (string)
powierzchnia	Zmiennoprzeciwnkowy (floating)
ocean	Logiczny (bolean)
dni	Liczba całkowita (integer)

Co to jest Yaml – Przykład

Stringi możesz umieszczać w pojedynczych lub podwójnych cudzysłowach lub… nie stosować ich wcale. YAML rozpoznaje liczby bez cudzysłowu jako liczby całkowite lub zmiennoprzecinkowe.

Linia siódma to tablica. Waluty zostały rozdzielone na cztery elementy. Każdy z nich oznaczony jest myślnikiem. Każdy z elementów zagnieżdżonych w Waluta został poprzedzony dwoma spacjami. Tego typu wcięcie oznacza zagnieżdżenie w YAMLu. Liczba spacji może się różnić w zależności od pliku. Jeżeli sam tworzysz plik YAML to sam możesz zdecydować o ich ilości. Przykładowo, ja tworząc playbooki w Ansible – stosuję tylko jedną. Musisz też pamiętać, że tabulatory nie są dozwolone. O wcięciach za chwilę opowiem więcej.

Następnie mamy sekcję „wakacje”. Sekcja ta posiada 5 elementów, a każda z nich ma wcięcie w stosunku do „wakacje”. W tym przypadku wakacje to lista słownikowa. Zawiera dwa ciągi znaków, dwie liczby całkowite i inny słownik. YAML obsługuje zagnieżdżanie par typu klucz-wartość oraz typy mieszane.

Wcięcia

Ważnym elementem formatowania kodu YAMl są wcięcia. Wykonujemy je za pomocą spacji i myślników. Za pomocą tych wcięć tworzysz strukturę dokumentu. Poziom wcięcia regulujesz za pomocą liczby spacji. Zabronione jest używanie tabulatora. Spójrz na kod poniżej. Kolejne poziomy oddzielone są dwoma spacjami. Wartości są oddzielone jedną spacją po dwukropku.

daniel:
  imie: Daniel
  praca: Admin
  wydział: IT

Poniżej przykład z użyciem myślników (omówimy to za chwilę):

zmienna:
  - planety:
      planeta1: merkury
      planeta2: wenus
      planeta3: ziemia

Komentarze

Komentarze wprowadzasz za pomocą standardowego, znaku hasha (#). Np. w taki sposób:

# Opis pracownika
daniel:
  imie: Daniel
  praca: Admin
  wydział: IT

Możesz też dodać komentarz wewnątrz linii kodu. Wszystko co znajdzie się po znaku # będzie traktowane jako komentarz.

daniel: #Opis Pracownika
  imie: Daniel
  praca: Admin
  wydział: IT

Oczywiście, to co znajduje się wewnątrz komentarza jest wyłączone z akcji. Nie jest to część kodu. Co oznacza, że system/aplikacja korzystająca z powyższego skryptu zignoruje #Opis Pracownika

Można uznać, że nie zauważy tego fragmentu. Służy to do opisu i łatwiejszego zrozumienia fragmentu kodu w przyszłości. Warto to stosować, by opisywać konkretne funkcje i tym samym, szybciej odnaleźć się przy ponownym korzystaniu ze skryptu.

Co to jest YAML – Typy Danych

Wartości w parach klucz-wartość YAML są skalarne. Działają jak typy skalarne w językach takich jak Perl, JavaScript i Python. Zwykle wystarczy ująć ciągi w cudzysłowy. Liczby można pozostawić liczby bez cudzysłowów i pozwolić parserowi to „rozgryźć”.

Yaml – Klucz i Wartość

Klucz:wartość i Słowniki

Para klucz-wartość to podstawowy element konstrukcyjny YAML. Każdy element w dokumencie YAML jest częścią co najmniej jednego słownika. Kluczem jest zawsze string. Wartość może być dowolnym typem danych. Może to być ciąg, liczba lub inny słownik.

Typy numeryczne

YAML rozpoznaje typy liczbowe. Przede wszystkim liczby zmiennoprzecinkowe i całkowite. Obsługuje również kilka innych typów numerycznych. Liczba całkowita może być dziesiętna, szesnastkowa lub ósemkowa.

Ciągi

Ciągi w YAML zapisywane są w formacie Unicode. W większości sytuacji nie musisz podawać ich w cudzysłowiu.
Przykład:

foo: przykład normalnej zmiennej

Natomiast, jeżeli w zmiennej chcesz zamieścić jakieś dodatkowe informacje czy funkcje to musisz użyć cudzysłowu. Przykład:

foo: ” To nie jest typowa zmienna \n”

Gdybyśmy nie użyli cudzysłowu to Yaml uznałby część \n jako osobną zmienną.

YAML nie zmieni ciągu znaków jeżeli użyjemy pojedynczych cudzysłowów.

Null

Aby zastosować null musisz wprowadzić ~ lub po prostu null. Przykladowo:

Wartość: ~ 
Wartość: null

Logiczny typ danych

YAML określa wartości logiczne za pomocą słów kluczowych True, On i Yes dla wartości prawdziwej (true). Fałsz jest wskazywany za pomocą False, Off lub No.

Przykład poniżej.

---
wlaczony: True
hdmi: False
HDR: Off
TV: On

Tablice

Tablica w programowaniu jest używana do umieszczania wielu zmiennych danego typu. Tablice lub listy możesz określić w jednym wierszu.

---
zmienna: [ 1, 2, 3, 4, 5 ]
nazwa: [ "jeden", "dwa", "trzy", "cztery" ]

Możesz też umieścić je w wielu wierszach.

---
zmienna:
  - 1
  - 2
  - 3
  - 4
  - 5
nazwa:
  - "jeden "
  - "dwa "
  - "trzy "
  - "cztery "

Opcja z wieloma wierszami jest dobrym wyborem w przypadku list zawierających złożone obiekty zamiast skalarnych.

---
zmienna:
  - planety:
      planeta1: merkury
      planeta2: wenus
      planeta3: ziemia
  - inne planety:
      klucz: wartość

Tablica może zawierać dowolną prawidłową wartość YAML. Wartości na liście nie muszą być tego samego typu.

Co to jest YAML – Część 2

Oznaczenie początku i zakończenia pliku YAML

Już wiesz, że dokument zaczyna się trzema myślnikami. Przyjętym standardem jest to, że kod YAML kończy się trzema kropkami. W rzeczywistości, rzadko kiedy się to stosuje.

Mało tego, w przypadku Ansible czy Dockera, nie stosuje tego prawie nikt. Mówię to w oparciu o realne case study i to jak większość pracowników IT wykorzystuje ten format.

Niektóre procesory YAML wymagają jednak wskazania początku i końca kodu dokumentu. Przykładowo, Java Jackson nie przetworzy dokumentu YAML bez oznaczenia startu, ale PyYAML Pythona już tak. Zwykle będziesz używać operatora dokumentu końcowego, gdy plik zawiera wiele dokumentów.

Warto wiedzieć, że stosując — możesz oznaczyć początek kolejnego dokumentu YAML w ramach tego samego pliku. Spójrz na kod poniżej Waluty i Wakacje to osobne dokumenty YAML.

---
Waluty:
   - dolar
   - złotówka
   - euro
   - funt
--- 
Wakacje:
   transport: samolot
   nocleg: hotel
   posiłki: "na miejscu"

Przykład

Aby lepiej zrozumieć YAML, wykorzystamy ten format do przedstawienia czegoś konkretnego. Weźmy dla przykładu Mieszkanie. Każde mieszkanie posiada listę opisujących je parametrów. Są to choćby:

- Wielkość w m2
- Lokalizacja
- Cena
- Piętro
- Liczba Pokoi

Mieszkanie o wielkości 36 m2 na 3 piętrze z 2 pokojami za 450 000 PLN w Warszawie w słowniku (DICTIONARY) miałoby następujące parametry:

Wielkość w m2: 36
Lokalizacja: Warszawa
Cena: PLN450000
Piętro: 3
Liczba Pokoi: 2

Jeżeli byśmy chcieli jeszcze rozbić lokalizację na bardziej szczegółowe elementy jak:

– Miasto

– Ulica

To moglibyśmy użyć tzw. LIST OF DICTIONARY. W tym wypadku wyglądałoby to następująco:

Wielkość w m2: 36
Lokalizacja:
   Miasto: Warszawa
   Ulica: Platynowa
Cena: PLN450000
Piętro: 3
Liczba Pokoi: 2

Pamiętaj tylko, że w Ansible niezwykle duże znaczenie mają spacje. Miasto i Ulica w tym przypadku musi być oddzielona dokładnie taką samą liczbą spacji!

Listy

Powyższy przykład warto wykorzystać do zaprezentowania list. Listy w YAML oznacza się za pomocą myślnika. Spójrz:

Wielkość w m2: 36
 - Lokalizacja:
     Miasto: Warszawa
     Ulica: Platynowa

W tym przypadku – Lokalizacja jest listą z parametrami Miasto i Ulica.

Możesz też użyć tzw. „Listę List”. Ich użycie wygląda następująco:

- aplikacja: wordpress
  wersje:
  - 5.5
  - 5.6

Inny przykład

YAML możesz potraktować też na zasadzie bazy danych. Przykładowo, taka tabela:

Komputer	RAM	CPU	Dysk
Laptop 1	4	3,0 Ghz	250
Laptop 2	8	2,7 Ghz	200

W formacie YAML zostanie przedstawiona następująco:

Przykłady YAML z życia wzięte

Poniżej zamieszczam dwa przykłady. Pierwszy z wykorzystaniem Ansible i drugi z Dockera

Ansible

Poniższy przykład pochodzi z mojego szkolenia Ansible.

#Playbook, który tworzy nową maszynę, a następnie ją uruchamia.
- hosts: proxmox
  vars_prompt:
    - name: klucz_api
      prompt: Podaj hasło API
  tasks:
  - name: Nowy kontener #Zadanie, które Tworzy nowy VM na Proxmoxie.
    community.general.proxmox:
      node: grupa
      api_user: root@pam
      api_password: "{{ klucz_api }}"
      api_host: 10.0.1.45
      password: tajnehaslo
      hostname: automatyczny2
      ostemplate: 'local:vztmpl/ubuntu-18.04-standard_18.04.1-1_amd64.tar.gz'
      storage: local-lvm
      netif: '{"net0":"name=eth0,gw=10.0.1.1,ip=10.0.1.111/24,bridge=vmbr0"}' #adresacja IP VM

Jest to Playbook wykorzystujący Yaml, który uruchamia kontener z systemem Ubuntu i wykonuje prostą konfigurację. mamy tu kilka statycznych wartości i wykorzystanie zmiennych. Swoją drogą, jeżeli chcesz się uczyć automatyzacji i tego typu zadań to zapraszam Cię do sprawdzenia agendy – Kurs Ansible.

Docker

Przykład wzięty ze strony https://docs.docker.com/samples/wordpress/ Mamy tu kod, który tworzy kontener zawierający WordPressa z bazą danych.

version: "3.9"
    
services:
  db:
    image: mysql:5.7
    volumes:
      - db_data:/var/lib/mysql
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: somewordpress
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: wordpress
    
  wordpress:
    depends_on:
      - db
    image: wordpress:latest
    volumes:
      - wordpress_data:/var/www/html
    ports:
      - "8000:80"
    restart: always
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress
      WORDPRESS_DB_NAME: wordpress
volumes:
  db_data: {}
  wordpress_data: {}

Sprawdzanie składni

To o czym jeszcze warto pamiętać to istnieją w sieci narzędzia, które analizują nasz kod YAML i wychwytują błędy. Przykładowo YAML Lint dostępne w tym miejscu:

http://www.yamllint.com/

Wprowadzasz swój kod, wciskasz GO i sprawdzasz czy wszystko jest ok:

Zielony komunikat „Valid YAML” informuje, że tak.

Multiline string

Multiline string, czyli kilka linii i jeden ciąg. Czasami może się zdarzyć tak, że w swoim dokumencie YAML chcesz zamieścić ciąg, który jest bardzo długi i psuje nam czytelność całego kodu.

Przykładowo coś takiego:

---
  - hosts: target1
    become: True
    tasks:
      - lineinfile:
         path: /home/mietek/.ssh/authorized_keys
         line: 'ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAQEAi6Gb1pl+WHmHDv6GB2tdoNc/QdURAaZ3YVjEmR+GXHhkqG3PvMn1iDN6aeaMX/nL1qEjv1EAzsWJnYJvNwS+923Jtz9BNi/FPuegO/cQewWuRrJVyb/Zyb5v3mmRvAby9yVFrKqKLtJsTGR7Bjo8I7jvuhNm5e1uTHPGvmN7yKnn5wnZPA8XnQCqXHqyphAqeHcHIDF1A5h8b9H8xOm4mAHN6EptVFH89NrjVgJfORwN8wrYFQVbfTQHfT1tn9+Uw9iSZzWttxrS+Gai9dohhgkOaUxufXkpiD04nTcZj893AvbRoV8/P5SQqsAop1BqdCQCeNWHJW5lqlGX4io8Ew== rsa-key-111111111111'

Jest to playbook dodający klucz publiczny dla użytkownika Mietek. Robi robotę, ale w edytorze rozciąga kod w nieskończoność. Zresztą, sprawdź sam. Skopiuj powyższy kod do swojego edytora i sprawdź. Aby poprawić jego czytelność możesz użyć tzw. „multiline string”. Wystarczy, że użyjesz znaku >

Następnie możesz podzielić klucz publiczny za pomocą entera. Dzięki temu wszystkie linie po znaku > będą traktowane jako jedna. Będzie to wyglądało następująco:

---
  - hosts: target1
    become: True
    tasks:
      - lineinfile:
         path: /home/mietek/.ssh/authorized_keys
         line: >
          'ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAQEAi6Gb1pl+
          WHmHDv6GB2tdoNc/QdURAaZ3YVjEmR+GXHhkqG3PvMn1i
          DN6aeaMX/nL1qEjv1EAzsWJnYJvNwS+923Jtz9BNi/FPu
          egO/cQewWuRrJVyb/Zyb5v3mmRvAby9yVFrKqKLtJsTGR
          7Bjo8I7jvuhNm5e1uTHPGvmN7yKnn5wnZPA8XnQCqXHqy
          phAqeHcHIDF1A5h8b9H8xOm4mAHN6EptVFH89NrjVgJfO
          \RwN8wrYFQVbfTQHfT1tn9+Uw9iSZzWttxrS+Gai9dohh
          gkOaUxufXkpiD04nTcZj893AvbRoV8/P5SQqsAop1BqdC
          QCeNWHJW5lqlGX4io8Ew== rsa-key-111111111111'

Edytory

Istnieje spora liczba edytorów, które usprawnią Ci pracę z YAML. Choćby popularny Notepad++ wspiera ten format.

Osobiści mogę polecić ATOM. Po zainstalowaniu odpowiedniej wtyczki , edytor zacznie Ci podpowiadać i pokazywać błędy w składni. Dodatkowo dosyć szybko wyśle Twój kod do repozytorium za pomocą opcji synchronizacji.

Jeżeli jesteś fanem narzędzi Microsoft to warto rozważyć Visual Studio.

Konwerter

Warto jeszcze wspomnieć o dostępnych konwerterach miedzy JSON lub XML, a YAML. Przykładowo:

https://www.json2yaml.com/

https://beautifytools.com/xml-to-yaml-converter.php

Jeżeli musisz przerobić JSON lub XML na YAML (lub w drugą stronę) to powyższe linki mogą być sporą pomocą.

Podsumowanie

YAML to potężny język, którego można używać do wielu zastosowań. Zarówno do plików konfiguracyjnych, automatyzowania zadań jak i do komunikacji między aplikacjami. W dzisiejszym artykule omówiliśmy jego najczęściej używane funkcje, w tym sposób korzystania z wbudowanych typów danych i struktury złożonych dokumentów.

Jeżeli chcesz przetestować działanie YAML w praktyce to zachęcam do pobrania mojego, darmowego ebooka „Ogarnij Ansible”. W ramach ćwiczeń pokazuję jak wykorzystać YAML w praktyce na przykładzie Ansible. Pobierz Podręcznik Ansible.

Warto odwiedzić również stronę https://www.tutorialspoint.com/yaml/index.htm Znajdziesz tam rozbudowany tutorial YAML i sporo, ciekawych przykładów.

Spis Treści:

Sprawdź, czego nauczysz się dzięki kursowi Grafany!

YAML

Przykład

Wcięcia

Komentarze

Co to jest YAML – Typy Danych

Yaml – Klucz i Wartość

Null

Logiczny typ danych

Tablice

Co to jest YAML – Część 2

Oznaczenie początku i zakończenia pliku YAML

Sprawdź, czego nauczysz się dzięki kursowi Grafany!

Przykład

Listy

Inny przykład

Przykłady YAML z życia wzięte

Ansible

Docker

Sprawdzanie składni

Multiline string

Edytory

Konwerter

Podsumowanie

Sprawdź, czego nauczysz się dzięki kursowi Grafany!

Wyszukiwarka Google – jak z niej korzystać?