Ansible – poradnik dla początkujących: instalacja, inventory, playbooki i role

Ansible to darmowe narzędzie do automatyzacji, które pozwala z jednego komputera konfigurować dziesiątki czy setki serwerów: instalować pakiety, zmieniać pliki konfiguracyjne, zarządzać usługami i wdrażać aplikacje. Łączy się z maszynami przez SSH, nie wymaga na nich agenta, a pożądany stan opisujesz w czytelnych plikach YAML, zwanych playbookami.

W tym poradniku przejdziesz przez cały podstawowy cykl pracy: instalację, plik inventory, polecenia ad-hoc, pierwszy playbook, zmienne, role i bezpieczne przechowywanie haseł. Przykłady dotyczą serwerów z Debianem lub Ubuntu, ale zasada jest taka sama dla innych dystrybucji.

Jak działa Ansible: węzeł sterujący, inventory i moduły

Kilka pojęć, bez których trudno czytać dokumentację:

• Węzeł sterujący (control node) – komputer z zainstalowanym Ansible, z którego uruchamiasz polecenia. Może to być Linux, macOS albo WSL w Windows.
• Węzły zarządzane (managed nodes) – serwery, które konfigurujesz. Potrzebują tylko SSH i Pythona (Windows – WinRM lub OpenSSH).
• Inventory – lista serwerów podzielonych na grupy, z ewentualnymi zmiennymi.
• Moduł – jednostka pracy, np. ansible.builtin.apt instaluje pakiety, ansible.builtin.template tworzy pliki z szablonów, ansible.builtin.service zarządza usługami.
• Playbook – plik YAML z listą zadań (tasków) do wykonania na wybranych grupach hostów.
• Rola i kolekcja – sposób pakowania i współdzielenia gotowych zestawów zadań, modułów i szablonów.

Najważniejsza cecha modułów to idempotentność. Zadanie „pakiet nginx ma być zainstalowany” przy pierwszym uruchomieniu zainstaluje nginx, a przy kolejnych tylko sprawdzi, że jest – i nic nie zmieni. Dzięki temu playbook możesz uruchamiać wielokrotnie, a wynik changed mówi Ci dokładnie, co zostało zmienione.

Instalacja Ansible

Najprościej zainstalować Ansible z repozytorium dystrybucji, ale wersja bywa tam starsza:

# Debian / Ubuntu
sudo apt update && sudo apt install ansible

# Fedora / RHEL / Rocky / Alma
sudo dnf install ansible-core

Najnowszą wersję daje instalacja z PyPI. Dokumentacja Ansible zaleca do tego pipx, który instaluje narzędzie w osobnym środowisku:

sudo apt install pipx
pipx install --include-deps ansible
ansible --version

Aktualne wydania ansible-core wymagają na węźle sterującym jednej z nowszych wersji Pythona 3, a na węzłach zarządzanych – Pythona 3 w wersji wspieranej przez dane wydanie. Tabelę zgodności znajdziesz w dokumentacji projektu na docs.ansible.com.

Klucze SSH

Ansible korzysta ze zwykłego klienta SSH, więc najwygodniej jest zalogować się kluczem:

ssh-keygen -t ed25519 -C "ansible"
ssh-copy-id admin@192.168.10.11
ssh-copy-id admin@192.168.10.12

Jeśli na serwerach potrzebujesz uprawnień roota, użytkownik powinien mieć prawo do sudo. Ansible podniesie uprawnienia sam, gdy dodasz become: true w playbooku lub --become w poleceniu.

Plik inventory i ansible.cfg

Utwórz katalog projektu, np. ~/ansible-lab, a w nim plik inventory.yml:

all:
  vars:
    ansible_user: admin
  children:
    web:
      hosts:
        web1:
          ansible_host: 192.168.10.11
        web2:
          ansible_host: 192.168.10.12
    db:
      hosts:
        db1:
          ansible_host: 192.168.10.21

Ten sam układ można zapisać w formacie INI, ale YAML lepiej sprawdza się przy większej liczbie zmiennych. Obok utwórz ansible.cfg, żeby nie podawać inventory przy każdym poleceniu:

[defaults]
inventory = inventory.yml
host_key_checking = True
forks = 10

Sprawdź, czy Ansible widzi hosty i może się z nimi połączyć:

ansible-inventory --graph
ansible all -m ansible.builtin.ping

Moduł ping nie wysyła pakietów ICMP – loguje się przez SSH i sprawdza, czy na serwerze działa Python. Odpowiedź pong oznacza, że wszystko jest gotowe.

Polecenia ad-hoc: szybkie zadania na wielu serwerach

Polecenia ad-hoc służą do jednorazowych czynności, których nie warto zapisywać w playbooku. Składnia to ansible <grupa> -m <moduł> -a "<argumenty>".

# Czas działania i obciążenie na wszystkich serwerach WWW
ansible web -m ansible.builtin.command -a "uptime"

# Wolne miejsce na dyskach
ansible all -m ansible.builtin.shell -a "df -h / | tail -1"

# Instalacja pakietu z podniesieniem uprawnień
ansible web -m ansible.builtin.apt -a "name=htop state=present update_cache=true" --become

# Restart usługi
ansible db -m ansible.builtin.service -a "name=postgresql state=restarted" --become

# Informacje o systemie zebrane przez Ansible (facts)
ansible web1 -m ansible.builtin.setup -a "filter=ansible_distribution*"

Moduł command uruchamia polecenie bez powłoki, więc nie zadziałają w nim potoki i przekierowania – do nich służy shell. Tam, gdzie istnieje dedykowany moduł (pakiety, usługi, pliki, użytkownicy), używaj go zamiast shell, bo tylko wtedy zachowujesz idempotentność. Jeśli dopiero oswajasz się z wierszem poleceń, przyda się lista 20 podstawowych poleceń Linuksa.

Pierwszy playbook: nginx z własną stroną

Playbook opisuje stan, do którego mają dojść serwery. Utwórz plik web.yml:

---
- name: Konfiguracja serwerów WWW
  hosts: web
  become: true
  vars:
    site_name: "Moja strona"

  tasks:
    - name: Zainstaluj nginx
      ansible.builtin.apt:
        name: nginx
        state: present
        update_cache: true
        cache_valid_time: 3600

    - name: Wgraj stronę startową z szablonu
      ansible.builtin.template:
        src: templates/index.html.j2
        dest: /var/www/html/index.html
        owner: www-data
        mode: "0644"

    - name: Wgraj konfigurację nginx
      ansible.builtin.copy:
        src: files/default.conf
        dest: /etc/nginx/sites-available/default
        mode: "0644"
      notify: Przeładuj nginx

    - name: Upewnij się, że nginx działa i startuje z systemem
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: true

  handlers:
    - name: Przeładuj nginx
      ansible.builtin.service:
        name: nginx
        state: reloaded

Szablon templates/index.html.j2 korzysta ze składni Jinja2, np. <h1>{{ site_name }} – {{ inventory_hostname }}</h1>. Handler „Przeładuj nginx” uruchomi się tylko wtedy, gdy zadanie, które go powiadamia (notify), faktycznie coś zmieniło – i tylko raz, na końcu playbooka.

Uruchomienie:

# Sprawdzenie składni
ansible-playbook web.yml --syntax-check

# Próba na sucho: co by się zmieniło, z różnicami w plikach
ansible-playbook web.yml --check --diff

# Właściwe uruchomienie, tylko na jednym hoście
ansible-playbook web.yml --limit web1

Wskazówka: Uruchamiaj nowe playbooki najpierw z --check --diff i --limit na jednym serwerze. Tryb check nie jest doskonały (np. zadania zależne od wcześniejszych zmian mogą się w nim mylić), ale wyłapuje większość pomyłek, zanim trafią na wszystkie maszyny.

Usługami, którymi zarządza moduł service, w nowoczesnych dystrybucjach steruje systemd – jak działa ręcznie, przeczytasz w poradniku systemctl – do czego służy.

Zmienne, group_vars i warunki

Zmienne można definiować w wielu miejscach, ale dobrą praktyką jest trzymanie ich w katalogach group_vars i host_vars obok inventory:

ansible-lab/
├── ansible.cfg
├── inventory.yml
├── group_vars/
│   ├── all.yml
│   └── web.yml
├── host_vars/
│   └── db1.yml
└── web.yml

Plik group_vars/web.yml z zawartością site_name: "Sklep testowy" nadpisze wartość dla wszystkich hostów z grupy web. Ansible ma ustaloną kolejność pierwszeństwa zmiennych – najwyższe ma przekazanie z wiersza poleceń przez -e.

Zadania można też uzależniać od warunków i wykonywać w pętli:

- name: Utwórz konta administratorów
  ansible.builtin.user:
    name: "{{ item }}"
    groups: sudo
    append: true
    shell: /bin/bash
  loop:
    - anna
    - piotr
  when: ansible_facts['os_family'] == "Debian"

Role i kolekcje z Ansible Galaxy

Gdy playbook rośnie, podziel go na role. Rola ma stałą strukturę katalogów (tasks, handlers, templates, files, defaults, vars, meta), dzięki czemu łatwo ją przenosić między projektami. Szkielet utworzysz poleceniem:

ansible-galaxy role init roles/nginx

Playbook korzystający z ról jest wtedy bardzo krótki:

- name: Serwery WWW
  hosts: web
  become: true
  roles:
    - nginx
    - firewall

Ansible Galaxy (galaxy.ansible.com) to publiczne repozytorium ról i kolekcji. Kolekcje zawierają moduły, wtyczki i role – np. community.general, ansible.posix, community.docker czy ansible.windows. Zależności projektu zapisz w requirements.yml:

collections:
  - name: community.general
  - name: community.docker
roles:
  - name: geerlingguy.mysql

i zainstaluj je poleceniem ansible-galaxy install -r requirements.yml. Zanim użyjesz cudzej roli na produkcji, przejrzyj jej kod – to oprogramowanie, które wykona się z uprawnieniami roota na Twoich serwerach.

Hasła i sekrety: Ansible Vault

Hasła do baz, klucze API czy certyfikaty nie powinny leżeć otwartym tekstem w repozytorium. Ansible Vault szyfruje pliki lub pojedyncze wartości algorytmem AES-256:

# Nowy zaszyfrowany plik ze zmiennymi
ansible-vault create group_vars/db/vault.yml

# Edycja i podgląd
ansible-vault edit group_vars/db/vault.yml
ansible-vault view group_vars/db/vault.yml

# Uruchomienie playbooka z hasłem do Vault
ansible-playbook db.yml --ask-vault-pass

W automatyzacji (CI/CD) zamiast pytania o hasło użyj --vault-password-file z plikiem dostępnym tylko dla konta uruchamiającego Ansible albo integracji z zewnętrznym menedżerem sekretów.

Uwaga: Nie commituj do repozytorium plików z hasłem do Vault ani niezaszyfrowanych kopii sekretów. Dodaj je do .gitignore i sprawdź historię repozytorium, jeśli kiedykolwiek się tam znalazły – usunięcie pliku w nowym commicie nie usuwa go z historii.

Ansible czy skrypty Bash?

Proste zadanie na jednym serwerze szybciej napiszesz w Bashu – i nie ma w tym nic złego. Przewaga Ansible pojawia się przy wielu maszynach i konfiguracji, która ma być powtarzalna:

Skrypty Bash nadal przydają się do drobnych zadań i wewnątrz ról (np. jako moduł script). Jeśli piszesz ich dużo, przyda się poradnik o instrukcjach warunkowych w Bash.

Co dalej: dobre praktyki i kolejne kroki

1. Trzymaj projekt Ansible w Git i wprowadzaj zmiany przez przegląd kodu – to fundament podejścia Infrastructure as Code. Różnice między Gitem a GitHubem wyjaśniamy w artykule Git a GitHub.
2. Używaj pełnych nazw modułów (FQCN), np. ansible.builtin.copy zamiast copy – unikasz konfliktów między kolekcjami.
3. Sprawdzaj kod narzędziem ansible-lint, a role testuj w Molecule na kontenerach lub maszynach wirtualnych.
4. Nazywaj zadania opisowo – nazwy zobaczysz w wynikach i logach.
5. Gdy playbooki ma uruchamiać więcej osób lub harmonogram, rozważ AWX lub Red Hat Ansible Automation Platform, które dodają interfejs webowy, uprawnienia i historię uruchomień.

Ansible dobrze współpracuje też z wirtualizacją – możesz nim konfigurować hosty i maszyny w klastrze Proxmox, o którym piszemy w poradniku Proxmox – instalacja i konfiguracja.