Pierwszy playbook — YAML bez niespodzianek — Ansible od zera do bohatera

Pierwszy playbook — YAML bez niespodzianek

Playbook to nie jest zwykły skrypt. To deklaracja stanu, którą Ansible ma wprowadzić na Twoich serwerach. Jeśli skrypt Bashowy to lista instrukcji "zrób to, potem tamto", to playbook jest opisem rzeczywistości: "chcę, aby ten serwer miał zainstalowany Nginx i działał na porcie 80". Przejście na myślenie deklaratywne wymaga zrozumienia struktury pliku oraz bezwzględnego respektowania reguł języka YAML.

Anatomia playbooka

Każdy playbook składa się z jednej lub wielu "gier" (plays). Gra to logiczna jednostka, która wiąże grupę serwerów z zestawem zadań.

Oto wzorcowa struktura pojedynczej gry:

- name: Konfiguracja serwera WWW
  hosts: webservers
  become: yes
  tasks:
    - name: Instalacja pakietu nginx
      ansible.builtin.package:
        name: nginx
        state: present

    - name: Uruchomienie usługi nginx
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: yes

Rozbijmy to na czynniki pierwsze:

name (na poziomie gry): Opisuje, co robi cała ta sekcja. Dobra praktyka to pisanie konkretnych celów, a nie ogólników.
hosts: Definiuje grupę maszyn (zdefiniowaną w inventory), na których ta gra zostanie wykonana. Nigdy nie zostawiaj hosts: all w produkcji bez wyraźnego powodu, bo jeden błąd w zadaniu może położyć całą infrastrukturę jednocześnie.
become: yes: To odpowiednik sudo. Jeśli Twoje zadania wymagają uprawnień roota (instalacja pakietów, edycja plików w /etc), musisz to zadeklarować. Brak become przy zadaniach systemowych to najczęstsza przyczyna błędów Permission denied.
tasks: Lista zadań, które Ansible wykona po kolei.
name (na poziomie zadania): To nie jest tylko komentarz. To Twoja jedyna linia obrony podczas awarii. Gdy playbook wyłoży się na 45. zadaniu w środku nocy, w logach nie zobaczysz "zadanie nr 45", tylko "Konfiguracja certyfikatów SSL". Jeśli nie nazwiesz zadań, będziesz błądzić po omacku w gąszczu nieczytelnych komunikatów.

Pułapki YAML: Gdzie kończy się logika, a zaczyna błąd składni

YAML jest językiem bardzo czytelnym dla człowieka, ale niezwykle rygorystycznym dla parsera. Większość incydentów typu "playbook nie chce ruszyć" wynika z błędów, które nie są błędami logiki, lecz składni.

1. Wcięcia (Indentation)

W YAML-u nie istnieją nawiasy klamrowe określające zakresy. Wszystko opiera się na wcięciach. Zasada numer jeden: Używaj wyłącznie spacji. Nigdy nie używaj tabulatorów. Większość nowoczesnych edytorów (VS Code z rozszerzeniem Ansible) zamienia tabulator na spacje, ale jeśli pracujesz na surowym terminalu, jeden ukryty tabulator sprawi, że Ansible wyrzuci błąd syntax error, którego nie będziesz w stanie znaleźć wzrokiem.

2. Pułapka cudzysłowów przy zmiennych

To błąd, który kosztuje ludzi wiele godzin debugowania. Jeśli Twoje zadanie zaczyna się od zmiennej, musisz użyć cudzysłowu.

# BŁĄD - Parser uzna, że to początek nowego słownika (mappingu)
command: {{ my_variable }}

# POPRAWNIE
command: "{{ my_variable }}"

Jeśli linia zaczyna się od {{, parser YAML myśli, że budujesz strukturę danych, a nie podajesz wartość tekstową. Zawsze otaczaj wartości zaczynające się od {{ cudzysłowem.

3. Niejednoznaczne Booleany

YAML stara się być "inteligentny", co w automatyzacji jest przekleństwem. Wartości takie jak yes, no, on, off są interpretowane jako true lub false.

Może to brzmieć niegroźnie, ale wyobraź sobie, że konfigurujesz system, który ma przyjąć tekst "on" jako nazwę trybu pracy. Ansible może to zamienić na true, co zepsuje Twoją konfigurację. Zalecenie: Używaj jawnych true i false zamiast yes/no lub on/off.

4. Liczby z zerem wiodącym (Octal Trap)

To klasyk, który potrafi zniszczyć konfigurację sieciową lub uprawnienia. W YAML-u liczba zaczynająca się od zera (np. 08) może zostać zinterpretowana jako liczba w systemie ósemkowym (octal).

# BŁĄD - Może zostać zinterpretowane jako błąd składni lub inna liczba
zip_code: 01234

# POPRAWNIE
zip_code: "01234"

Jeśli Twoja wartość ma być ciągiem znaków (numer telefonu, kod pocztowy, ID), zawsze trzymaj ją w cudzysłowie.

Uruchamianie i interpretacja wyników

Playbook uruchamiasz komendą: ansible-playbook -i inventory.ini playbook.yml

Kiedy playbook ruszy, zobaczysz strumień tekstu. Musisz nauczyć się go czytać, zamiast tylko czekać na koniec.

ok (zielony): Zadanie zostało wykonane, ale nie wprowadziło żadnych zmian. To dowód na idempotencję – system jest już w pożądanym stanie.
changed (żółty): Zadanie zostało wykonane i faktycznie coś zmieniło na serwerze (np. zainstalowano pakiet, zmieniło się uprawnienie). Jeśli widzisz changed przy każdym uruchomieniu tego samego playbooka, oznacza to, że Twoje zadania nie są idempotentne i właśnie tworzysz niestabilny system.
failed (czerwony): Zadanie nie powiodło się. Ansible natychmiast przerywa wykonywanie dalszych zadań dla tego konkretnego hosta.
unreachable: Problem z połączeniem (np. SSH). Ansible nawet nie mógł dotrzeć do maszyny.

Na samym końcu zobaczysz sekcję PLAY RECAP. To Twój ostateczny raport. Sprawdzaj tam kolumny changed i failed. Jeśli w failed masz cokolwiek innego niż 0, Twój playbook nie wykonał się w pełni i nie możesz założyć, że infrastruktura jest w stanie docelowym.

Zasada do zapamiętania: W Ansible nie walczysz z systemem, walczysz ze składnią YAML. Jeśli playbook nie działa, najpierw sprawdź cudzysłowy i spacje, zanim zaczniesz zmieniać logikę zadań.