Rola Ansible dla usługi systemd

Rola Ansible, która tworzy i konfiguruje pliki jednostek usługi systemd. Umożliwia automatyczne uruchamianie niektórych usług w tle, ich włączanie i wyłączanie na określone zdarzenia, zarządzanie grupami procesów oraz konfigurowanie zależności od innych jednostek.

Rola zawiera następujące zadania:

1. Tworzy plik usługi systemd w /etc/systemd/system/ z określoną nazwą service_name.service dla każdego elementu systemd_service.
2. Konfiguruje ważne opcje sekcji Unit, Service i Install.
3. Powiadamia systemd o nowo utworzonych plikach usług. Restartuje usługę.
4. Włącza automatyczne uruchamianie usługi przy starcie systemu, jeśli to konieczne.

Ta rola może być uruchamiana we wszystkich wersjach Ubuntu.

Wymagania

Rola wymaga dostępu roota, więc można ją uruchomić w playbooku z globalnym parametrem become: yes lub wywołać rolę w swoim playbooku w następujący sposób:

- hosts: apps
  roles:
    - role: systemd-service
      become: yes

Zmienne roli

Wszystkie niezbędne usługi mogą być określone poprzez zmienną słownika systemd_service (zobacz defaults/main.yml):

systemd_service: {}

Dla każdej usługi należy ustawić service_name oraz potrzebne wartości parametrów. Na przykład, aby określić, czy usługa powinna uruchamiać się przy starcie, użyj parametru enabled.

systemd_service:
  service_name:
    enabled:

Wszystkie inne dostępne parametry, które powinny być określone dla konkretnego klucza service_name (jako zagnieżdżone parametry), są podane poniżej.

Opcje sekcji Unit

Ta grupa parametrów zawiera ogólne informacje o jednostce.

description:   # Swobodny opis jednostki

Dwa następne parametry konfigurować będą zależności od innych jednostek. Jeśli usługa zostanie uruchomiona, jednostki wymienione tam również zostaną aktywowane. Jeśli jedna z jednostek requires nie może być uruchomiona lub nagle się nie powiedzie, usługa również zostanie zatrzymana. Natomiast lista wants nie zatrzyma usługi, jeśli któraś z jednostek z niej zostanie dezaktywowana. Parametry mogą zawierać kilka nazw jednostek oddzielonych spacjami. Mogą być także podane więcej niż raz.

requires:   # Jednostki, które muszą być uruchomione wraz z usługą
wants:      # Jednostki, które powinny być uruchomione wraz z usługą

Aby skonfigurować kolejność uruchamiania lub zatrzymywania usług, użyj następujących parametrów. Należy zauważyć, że jeśli jednostki nie mają zależności porządkowych między sobą, są one zatrzymywane lub uruchamiane jednocześnie. Oba parametry ustawiane są w postaci listy jednostek oddzielonej spacjami.

after:   # Jednostki, które muszą być uruchomione po usłudze
before:  # Jednostki, które muszą być uruchomione przed usługą

Opcje sekcji Service

Ta sekcja zawiera informacje o usłudze i nadzorowanym przez nią procesie. Parametr type konfiguruje typ uruchamiania procesu dla tej jednostki usługi.

type:

Może przyjmować wartości:

• simple - typ ten zakłada, że usługa zostanie uruchomiona natychmiast. Proces nie powinien się rozdzielać. Nie używaj tego typu, jeśli inne usługi mają zależności porządkowe od uruchamiania tej usługi. Jeśli usługa oferuje funkcjonalność innym procesom w systemie, jej kanały komunikacyjne powinny być zainstalowane przed uruchomieniem demona.
• forking - zakłada, że usługa jest uruchamiana raz, a proces rozdziela się po zakończeniu procesu macierzystego. Ten typ jest używany do uruchamiania klasycznych demonów. Jeśli używasz tego trybu, zaleca się również użycie parametru pid_file (zobacz poniżej), aby systemd mógł zidentyfikować główny proces demona.

Inne wartości mają podobne zachowanie do wartości simple, jednak różnią się pewnymi cechami:

• oneshot - oczekuje się, że usługa zakończy działanie przed uruchomieniem jednostek podążających;
• dbus - oczekuje się, że demon uzyska nazwę na magistrali D-Bus;
• notify - demon wysyła komunikat powiadamiający za pośrednictwem sd_notify(3) lub podobnego wywołania, gdy zakończy uruchamianie;
• idle - rzeczywiste uruchomienie binarnego pliku usługi jest opóźnione do momentu wysłania wszystkich aktywnych zadań. Zauważ, że ten typ jest przydatny tylko do poprawy wyjścia konsolowego, nie jest przydatny jako ogólny narzędzie do porządkowania jednostek.

Ustaw ścieżkę do pliku PID, aby użyć typu uruchamiania forking.

pid_file:    # Przyjmuje absolutną nazwę pliku wskazującą na plik PID tego demona

Możesz określić użytkownika UNIX oraz grupę, pod którą usługa powinna być uruchamiana. Parametry przyjmują jako wartości pojedynczą nazwę użytkownika lub grupy lub identyfikator liczbowy. Dla usług systemowych i dla usług użytkownika roota domyślnym użytkownikiem jest root, co można zmienić na innego. Dla usług użytkownika innego użytkownika nie zezwala się na zmianę tożsamości użytkownika. Zatem jedyną dozwoloną wartością jest ten sam użytkownik, pod którym działa menedżer usług użytkownika. Jeśli żadna grupa nie jest ustawiona, używana jest domyślna grupa użytkownika.

user:
group:

Ustaw priorytet harmonogramu dla jednostki za pomocą następnego parametru. Przyjmuje liczbę całkowitą w przedziale od -20 (najwyższy priorytet) do 19 (najniższy priorytet).

nice:    # Domyślny poziom nice dla usługi

Poziom dostosowujący dla zabójcy pamięci (Out-Of-Memory killer) dla procesu określa się za pomocą następującej opcji. Przyjmuje wartość całkowitą od -1000 (wyłączenie zabijania OOM) do 1000 (preferowane zabijanie OOM).

oom_score_adjust:

Następne parametry pozwalają określić polecenia, które będą wykonywane w zależności od stanu twojej usługi. Parametry mogą być używane więcej niż raz lub ich wartości mogą zawierać kilka poleceń. Wiele linii poleceń może być połączonych w jednej dyrektywie poprzez oddzielenie ich średnikami. Polecenie do wykonania musi być ścieżką bezwzględną. Może zawierać spacje, ale znaki sterujące nie są dozwolone. Dla każdego polecenia pierwszy argument musi być bezwzględną ścieżką do pliku wykonywalnego. Pusta wartość zresetuje wcześniej podaną listę poleceń dla parametru.

# Polecenia, które są wykonywane, gdy ta usługa jest uruchamiana
# Chyba że `type` jest `oneshot`, dokładnie jedno polecenie musi być tutaj podane
exec_start:

# Polecenia, które są wykonywane przed poleceniami `exec_start`
exec_start_pre:

# Polecenia, które są wykonywane po poleceniach `exec_start`
exec_start_post:

# Polecenia do wykonania w celu zatrzymania usługi uruchomionej przez `exec_start`
exec_stop:

# Polecenia, które są wykonywane po zatrzymaniu usługi
exec_stop_post:

# Polecenia do wykonania w celu wywołania przeładowania konfiguracji w usłudze
exec_reload:

Określ, czy usługa powinna być restartowana, gdy proces usługi (główny proces usługi lub proces określony przez parametry 'exec_start_pre', 'exec_start_post', 'exec_stop', 'exec_stop_post' lub 'exec_reload') zakończy działanie, zostanie zabity lub upłynie limit czasowy. Parametr restart przyjmuje jedną z następujących wartości:

• no (domyślnie) - usługa nie zostanie zrestartowana;
• on-success - usługa zostanie zrestartowana tylko wtedy, gdy proces usługi zakończy działanie prawidłowo (z kodem zakończenia 0 lub jednym z sygnałów SIGHUP, SIGINT, SIGTERM lub SIGPIPE);
• on-failure - usługa zostanie zrestartowana, gdy proces zakończy działanie z niezerowym kodem zakończenia, zostanie zakończony sygnałem, gdy operacja nie powiedzie się, a także gdy wywoła się skonfigurowany limit czasowy watchdog;
• on-abnormal - usługa zostanie zrestartowana, gdy proces zostanie zakończony sygnałem, gdy operacja nie powiedzie się, lub gdy wywoła się limit czasowy watchdog;
• on-watchdog - usługa zostanie zrestartowana tylko, jeśli proces usługi zakończy działania z powodu nieobsłużonego sygnału niewskazującego status zakończenia;
• on-abort - usługa zostanie zrestartowana tylko, jeśli limit czasowy watchdog dla usługi wygaśnie;
• always - usługa zostanie zrestartowana w każdym przypadku.

# Kiedy usługa musi być restartowana
restart:

Możesz określić opóźnienie czasowe dla powyższych poleceń za pomocą następnych parametrów. Przyjmują wartości w sekundach lub wartość czasu, na przykład '5min 20s'. Parametr restart_sec konfiguruje czas oczekiwania przed ponownym uruchomieniem usługi (zgodnie z restart). Opcja timeout_sec definiuje czas oczekiwania na przetwarzanie poleceń start/stop.

restart_sec:
timeout_sec:

Użyj parametru environment, aby ustawić listę zmiennych środowiskowych dla wykonywanych procesów. Zawiera on oddzieloną spacjami listę zmiennych i ich wartości. Parametr może być używany więcej niż raz. Jeśli dla tego parametru przypisana zostanie pusta wartość, lista zmiennych środowiskowych zostanie zresetowana. Jeśli jakaś wartość zawiera spację, użyj podwójnych cudzysłowów dla przypisania.

Możesz również odczytać zmienne środowiskowe z pliku tekstowego. W tym celu ustaw wartość parametru environment_file jako ścieżkę do pliku.

environment:       # Oddzielona spacjami lista przypisań zmiennych
environment_file:  # Ścieżka do pliku ze zmiennymi środowiskowymi

Aktualny katalog roboczy określa się za pomocą następnego parametru. Jest on ustawiany przed uruchomieniem poleceń.

working_directory:

Następujące parametry pozwalają wybrać, gdzie deskryptory plików (STDIN, STDOUT, STDERR) wykonywanych procesów mają być podłączane. Parametr standard_input przyjmuje wartości "null", "tty", "tty-force", "tty-fail", "socket" lub "fd". Parametr standard_output może być równy "inherit", "null", "tty", "journal", "syslog", "kmsg", "journal+console", "syslog+console", "kmsg+console", "socket" lub "fd". Dostępne wartości standard_error są identyczne jak standard_output.

standard_input:
standard_output:
standard_error:

Opcje sekcji Install

Te zmienne sekcji niosą informacje o instalacji jednostki. Następujące dwa parametry mogą być używane więcej niż raz lub mogą zawierać oddzielone spacjami nazwy jednostek. Listy zawierają jednostki, które odnoszą się do tej usługi w swoich polach requires i wants.

wanted_by:
required_by:

Zależności

Brak

Przykład playbooka

- hosts: app
  roles:
    - role: systemd-service
      systemd_service:
        # Nazwa usługi
        railsapp:
          # Uruchomienie usługi przy starcie
          enabled: Yes
          # Wykonaj polecenie z określonymi argumentami, gdy usługa zostanie uruchomiona
          exec_start: "/bin/bash -lc 'puma -C config/puma.rb'"
          # Użyj określonego katalogu jako aktualnego
          working_directory: "/var/www/myapp"
          # Uruchom procesy pod tym użytkownikiem i grupą
          user: "deploy"
          group: "deploy"
          # Restartuj usługę tylko, gdy nie uzyskano kodu wyjścia lub sygnału
          restart: "on-failure"
          # Spróbuj aktywować 'redis', jeśli to możliwe
          wants: "redis.service"
          # Aktywuj 'postgresql' lub przestań działać w przypadku niepowodzenia
          requires: "postgresql.service"
          # jednostka multi-user.target preferuje uruchomienie usługi
          wanted_by: "multi-user.target"

Licencja

Licencjonowane na podstawie Licencji MIT.