Zwracanie JSON i respektowanie changed

Po zakończeniu działania moduł musi przekazać Ansible wynik w formacie JSON. Dzięki temu kontroler dowiaduje się, co wydarzyło się na hoście.

W przypadku powodzenia należy wywołać module.exit_json. Wypisuje ono wynik jako JSON i poprawnie kończy działanie modułu, zwracając właściwy kod wyjścia.

Zawsze należy prawidłowo raportować wartość changed. Informuje ona Ansible, czy system został zmodyfikowany, i decyduje o wyświetleniu w wyniku wiersza ok lub changed.

Aby poprawnie obsłużyć wartość changed, należy najpierw odczytać bieżący stan. Jeśli już odpowiada on celowi, trzeba ustawić changed=False i niczego nie zmieniać.

Do exit_json można dodać dowolne klucze, które pojawią się w wyniku zadania. Użytkownicy mogą później zarejestrować te dane i ponownie je wykorzystać.

Gdy coś pójdzie nie tak, należy wywołać module.fail_json z jasnym komunikatem. Ansible oznaczy zadanie jako zakończone błędem i wyświetli ten tekst.

Nie należy używać print ani surowego stdout. Ansible oczekuje wyłącznie końcowego obiektu JSON, dlatego dodatkowy print uszkadza wynik i powoduje niepowodzenie zadania.

Każdy moduł kończy się dokładnie jednym wywołaniem exit_json lub fail_json. Oba wywołania zgłaszają SystemExit, więc kod znajdujący się za nimi nie zostanie wykonany.

W wynikach należy umieścić przyjazny komunikat msg opisujący wykonane działania. Dobre komunikaty zmieniają trudne do zrozumienia wykonania w czytelne wyniki.

Wynik powinien przypominać wyniki modułów podstawowych: należy raportować changed, zwracać znaczące pola i wyraźnie zgłaszać błędy wraz z ich przyczyną. Spójność buduje zaufanie.

Procedury obsługi, instrukcje warunkowe i zarejestrowane zmienne odczytują dane z JSON. Poprawne ustawienie wartości changed sprawia, że moduł właściwie współpracuje z Ansible.

Proszę zastanowić się, co moduł powinien zaraportować, gdy nic nie zostało zmodyfikowane.

W przypadku powodzenia należy zakończyć działanie za pomocą exit_json, a w przypadku błędu za pomocą fail_json, uczciwie raportować changed i nigdy nie wypisywać surowego wyniku. To protokół wyników modułu. 📦