Skrypty startowe

os.startup_scripts tworzy ograniczoną pracę one-shot systemd dla powstałego obrazu. Każdy wpis deklaruje polecenie powłoki, wymagane pakiety, użytkownika wykonującego i jednostkę kolejności.

Skrypty startowe to kod z uprawnieniami root, o ile run_as nie stanowi inaczej. Wymagają takiego samego przeglądu jak każdy skrypt instalacyjny.

Kanoniczny kształt

{
  "os": {
    "startup_scripts": [
      {
        "name": "write-build-marker",
        "description": "Create a local readiness marker after networking is available.",
        "command": "set -Eeuo pipefail\ninstall -d -m 0755 /var/lib/example\nprintf '%s\\n' ready > /var/lib/example/build-ready",
        "packages": [],
        "run_as": "root",
        "after": "network-online.target"
      }
    ]
  }
}

Pola to description i command, a nie legacy pole script. run_as i after również używają snake_case. after to jeden łańcuch jednostki systemd, nie tablica.

Schemat akceptuje co najwyżej 32 wpisy i ograniczony rozmiar polecenia. Walidacja odrzuca puste polecenia i bajty NUL, ale nie czyni zawartości powłoki bezpieczną ani idempotentną.

Projektowanie pod ponowienia i częściowe błędy

Boot może zostać przerwany po wystąpieniu skutków ubocznych. Pisz skrypty tak, aby kolejne uruchomienie albo kończyło się bezpiecznie, albo wychodziło ze stanem jasnym i możliwym do inspekcji.

Dobre wzorce obejmują:

• zapis do pliku tymczasowego, weryfikacja, potem atomowa zmiana nazwy;
• sprawdzenie, czy użytkownicy, katalogi lub wpisy konfiguracyjne już istnieją;
• użycie install dla jawnego właściciela i trybu;
• zastosowanie set -Eeuo pipefail i świadome obsługiwanie oczekiwanych wyników różnych od zera;
• ograniczone timeouts sieciowe i skończoną liczbę ponowień; oraz
• zapis markera gotowości dopiero po powodzeniu wszystkich wymaganych kroków.

Nie polegaj na sleep jako sprawdzeniu gotowości. Sprawdź rzeczywistą zależność.

Pobieranie zewnętrzne

Unikaj curl ... | sh. Jeśli first boot musi pobrać artefakt:

1. użyj HTTPS z weryfikacją certyfikatu;
2. przypnij oczekiwany artefakt lub wersję źródła;
3. zweryfikuj digest kryptograficzny lub zatwierdzony podpis przed wykonaniem;
4. ustaw connect i total timeouts;
5. fail closed, gdy weryfikacja się nie powiedzie; oraz
6. nie loguj credentials ani podpisanych URL-i.

Dla naprawdę offline lub reprodukowalnego zachowania umieść przejrzany content w obrazie lub zatwierdzonym repozytorium pakietów zamiast pobierać przy first boot.

Sekrety

Nigdy nie osadzaj credentials w postaci jawnego tekstu w przepisie, poleceniu, URL-u ani wygenerowanym markerze. JSON przepisu i logi buildu są zachowywane jako dowód i mogą być widoczne dla operatorów. Użyj zatwierdzonego mechanizmu enrollment lub dostarczania sekretów w czasie wdrożenia i ogranicz wynikowe credential do celu.

Tożsamość wykonania

Preferuj konto usługi bez uprawnień. Jeśli root jest wymagany, ogranicz polecenie do najmniejszego kroku z uprawnieniami i ustaw jawną własność plików. Potwierdź, że run_as wskazuje konto utworzone przed startem jednostki.

Weryfikacja

Testuj wyniki, a nie tylko status zakończenia jednostki:

{
  "type": "file_contains",
  "description": "The startup unit wrote its readiness marker.",
  "params": {
    "path": "/var/lib/example/build-ready",
    "content": "ready"
  }
}

Przetestuj też drugi boot, niedostępną zależność i odzyskiwanie po przerwanym pierwszym uruchomieniu. Przy błędzie sprawdź systemctl status i dziennik jednostki.