ansible-openwisp2-imagegenerator

Ten rol Ansible umożliwia budowanie kilku obrazów oprogramowania OpenWISP2 dla różnych organizacji, zachowując śledzenie ich konfiguracji.

Uwaga: ta rola nie była jeszcze testowana w rzeczywistych warunkach. Jeśli masz zamiar jej użyć, wypróbuj ją, a jeśli coś pójdzie nie tak, zgłoś swój problem, pamiętaj jednak, że musisz być gotowy na zrozumienie procesu budowy i jego działania, aby to działało dla ciebie.

Wymagane zmienne roli

Następujące zmienne są wymagane:

• openwisp2fw_source_dir: wskazuje katalog źródłowy OpenWRT, który jest używany podczas kompilacji
• openwisp2fw_generator_dir: wskazuje katalog używany do przygotowania generatorów
• openwisp2fw_bin_dir: wskazuje katalog używany podczas tworzenia końcowych obrazów
• openwisp2fw_organizations: lista organizacji; zobacz przykładowy plik playbook.yml w sekcji tworzenie pliku playbook, aby zrozumieć jego strukturę

Użycie (samouczek)

Jeśli nie wiesz, jak używać Ansible, nie martw się, ta procedura poprowadzi cię krok po kroku.

Jeśli już wiesz, jak używać Ansible, możesz pominąć tę sekcję i przejść od razu do sekcji „Zainstaluj tę rolę”.

Przede wszystkim musisz zrozumieć dwa kluczowe pojęcia:

• przez „serwer kompilacji” rozumiemy serwer, który jest używany do kompilacji obrazów
• przez „lokalną maszynę” rozumiemy hosta, z którego uruchamiasz Ansible, np. twój własny laptop lub serwer CI

Ansible to narzędzie do zarządzania konfiguracją/automatyzacji, które działa, logując się do serwera kompilacji przez SSH i wykonując szereg poleceń.

1. Zainstaluj Ansible

Zainstaluj Ansible na swojej lokalnej maszynie, jeśli jeszcze tego nie zrobiłeś, są różne sposoby, aby to zrobić, ale preferujemy użycie oficjalnego menedżera pakietów Pythona, np.:

sudo pip install ansible

Jeśli nie masz zainstalowanego pip, zobacz Instalacja pip na stronie dokumentacji pip.

Również instalacja Ansible w inny sposób jest w porządku, wystarczy upewnić się, że instalujesz wersję serii 2.0.x (to jest wersja, na której testowaliśmy ten playbook).

2. Zainstaluj tę rolę

Dla uproszczenia, najłatwiej jest zainstalować tę rolę na swojej lokalnej maszynie za pomocą ansible-galaxy (który został zainstalowany podczas instalacji Ansible), więc uruchom:

sudo ansible-galaxy install openwisp.openwisp2-imagegenerator

3. Wybierz katalog roboczy

Wybierz katalog roboczy na swojej lokalnej maszynie, w którym umieścisz konfigurację swoich obrazów oprogramowania.

Np.:

mkdir ~/my-openwisp2-firmware-conf
cd ~/my-openwisp2-firmware-conf

Umieszczenie tego katalogu roboczego pod kontrolą wersji to również bardzo dobry pomysł, pomoże ci śledzić zmiany, cofać się, skonfigurować serwer CI, aby automatycznie budował obrazy dla ciebie itd.

4. Utwórz plik inwentarza

Plik inwentarza to miejsce, w którym definiuje się grupy serwerów. W naszym prostym przypadku możemy się obejść bez definiowania grupy, w której umieścimy tylko jeden serwer.

Utwórz nowy plik hosts na swojej lokalnej maszynie z następującą zawartością:

[myserver]
mycompiler.mydomain.com ansible_user=<youruser> ansible_become_pass=<sudo-password>

Zamień mycompiler.mydomain.com na swoją nazwę hosta (dozwolone są też adresy IP).

Ponadto wstaw swojego użytkownika SSH i hasło odpowiednio w miejsce <youruser> i <sudo-password> (musi być to użytkownik z uprawnieniami sudo i nie-root). Te dane są używane podczas etapu Instalacja zależności.

5. Utwórz plik playbook

Utwórz nowy plik playbook playbook.yml na swojej lokalnej maszynie z następującą zawartością:

# playbook.yml
- hosts: your_host_here
  roles:
    - openwisp.openwisp2-imagegenerator
  vars:
    openwisp2fw_source_dir: /home/user/openwisp2-firmware-source
    openwisp2fw_generator_dir: /home/user/openwisp2-firmware-generator
    openwisp2fw_bin_dir: /home/user/openwisp2-firmware-builds
    openwisp2fw_source_targets:
        - system: ar71xx
          subtarget: generic
          profile: Default
        - system: x86
          subtarget: generic
          profile: Generic
    openwisp2fw_organizations:
        - name: snakeoil # nazwa organizacji
          flavours: # obsługiwane smaki
            - standard
          luci_openwisp: # /etc/config/luci_openwisp
            # inne klucze konfiguracyjne można dodawać dowolnie
            username: "operator"
            # hasło w postaci czystego tekstu, które będzie zaszyfrowane w /etc/config/luci_openwisp
            password: "<ZMIEN_NA_SWOJE>"
          openwisp: # /etc/config/openwisp
            # inne klucze konfiguracyjne można dodawać dowolnie
            url: "https://my-openwisp2-instance.com"
            shared_secret: "my-openwisp2-secret"
            unmanaged: "{{ openwisp2fw_default_unmanaged }}"
          # hasło w postaci czystego tekstu, które będzie zaszyfrowane w /etc/shadow
          root_password: "<ZMIEN_NA_SWOJE>"

Ten playbook pozwoli ci skompilować obrazy oprogramowania dla organizacji o nazwie snakeoil, używając jedynie smaku standard (który zawiera domyślny obraz OpenWRT 19.07 z standardowymi modułami OpenWISP2) dla dwóch architektur: ar71xx i x86.

Zobacz sekcję Zmienne ról, aby dowiedzieć się, jak dostosować dostępne konfiguracje.

Na tym etapie układ twojego katalogu powinien wyglądać następująco:

.
├── hosts
└── playbook.yml

6. Uruchom playbook

Teraz nadszedł czas na rozpoczęcie kompilacji oprogramowania OpenWISP2.

Uruchom playbook z swojej lokalnej maszyny za pomocą:

ansible-playbook -i hosts playbook.yml -e "recompile=1 cores=4"

Możesz zastąpić cores=4 liczbą rdzeni, jakie masz do dyspozycji.

Gdy playbook zakończy działanie, obrazy znajdziesz na serwerze kompilacji w katalogu określonym w openwisp2fw_bin_dir, który w naszym przykładzie to /home/user/openwisp2-firmware-builds z układem katalogów jak poniżej:

/home/user/openwisp2-firmware-builds
├── snakeoil/                                      # (każda organizacja ma własny katalog)
├── snakeoil/2016-12-02-094316/ar71xx/standard/    # (zawiera obrazy ar71xx dla smaku standardowego)
├── snakeoil/2016-12-02-094316/x86/standard/       # (zawiera obrazy x86 dla smaku standardowego)
└── snakeoil/latest/                               # (latest to symboliczny link do ostatniej kompilacji)

Teraz, jeśli śledziłeś ten samouczek i wszystko poszło dobrze, jesteś gotów dostosować swoją konfigurację do swoich potrzeb! Czytaj dalej, aby dowiedzieć się, jak to osiągnąć.

Zmienne ról

Istnieje wiele zmiennych, które można dostosować w razie potrzeby. Sprawdź domyślne wartości dla pełnej listy.

Niektóre z tych zmiennych są również opisane w sekcjach Organizacje oraz Smaki.

Organizacje

Jeśli pracujesz z OpenWISP, istnieje prawdopodobieństwo, że kompilujesz obrazy dla różnych grup ludzi: klientów z sektora komercyjnego, organizacji non-profit lub dowolnej grupy ludzi, którą można określić mianem "organizacji".

Organizacje mogą być definiowane swobodnie w openwisp2fw_organizations.

Aby zobaczyć przykład, jak to zrobić, odsyłam do przykładowego pliku playbook.yml.

Jeśli musisz dodać konkretne pliki do drzewa systemu plików obrazów każdej organizacji, zobacz Dodawanie plików dla konkretnych organizacji.

Smaki

Smak to kombinacja pakietów, które są dołączane do obrazu.

Możesz chcieć stworzyć różne smaki dla swoich obrazów, na przykład:

• standard: najczęstszy przypadek użycia
• minimal: obraz dla urządzeń, które mają mało dostępnej przestrzeni dyskowej
• mesh: obraz z pakietami potrzebnymi do implementacji sieci mesh

Domyślnie dostępny jest tylko smak standard.

Możesz zdefiniować własne smaki, ustawiając openwisp2fw_image_flavours - zapoznaj się z domyślnymi zmiennymi, aby zrozumieć ich strukturę.

Proces budowy

Proces budowy składa się z następujących kroków.

1. Instalacja zależności

tag: install

W tej fazie instalowane są lub aktualizowane zależności systemu operacyjnego potrzebne do kolejnych kroków.

2. Kompilacja

tag: compile

Źródło OpenWRT jest kompilowane w celu wytworzenia czegoś, co nazywamy "Image Generator". Generator obrazów to archiwum, które zawiera prekompilowane pakiety oraz specjalny Makefile, który będzie używany do generowania dostosowanych obrazów dla każdej organizacji.

Źródło jest pobierane i kompilowane w katalogu określonym w openwisp2fw_source_dir.

3. Przygotowanie generatorów

tag: generator

Podczas tego kroku generatory obrazów są wyodrębniane i przygotowywane do budowy różnych obrazów dla różnych organizacji. Każda organizacja może budować obrazy dla różnych smaków (np.: z pełną funkcjonalnością, minimalne, mesh itd.);

Obrazy są wyodrębniane i przygotowywane w katalogu określonym w openwisp2fw_generator_dir.

4. Budowanie końcowych obrazów

tag: build

W tej fazie produkowana jest seria obrazów.

Będzie zbudowanych kilka obrazów dla każdej architektury, organizacji i smaku. Może to wygenerować dużą liczbę plików, dlatego używaj tej mocy ostrożnie: lepiej zacząć od mniejszej liczby opcji i dodawać więcej w miarę postępu.

Na przykład, jeśli zdecydujesz się użyć 2 architektur (ar71xx i x86), 2 organizacji (np. A i B) oraz 2 smaków (np. standard i mini), otrzymasz 8 grup obrazów:

• organizacja: A / smak: standard / arch: ar71xx
• organizacja: A / smak: standard / arch: x86
• organizacja: A / smak: mini / arch: ar71xx
• organizacja: A / smak: mini / arch: x86
• organizacja: B / smak: standard / arch: ar71xx
• organizacja: B / smak: standard / arch: x86
• organizacja: B / smak: mini / arch: ar71xx
• organizacja: B / smak: mini / arch: x86

Obrazy będą tworzone w katalogu określonym w openwisp2fw_bin_dir.

5. Przesyłanie obrazów do OpenWISP Firmware Upgrader

Ostatnim krokiem jest przesłanie obrazów do modułu OpenWISP Firmware Upgrader. Ten krok jest opcjonalny i domyślnie wyłączony.

Aby włączyć tę funkcję, zmienne openwisp2fw_uploader oraz openwisp2fw_organizations.categories muszą być skonfigurowane, jak w poniższym przykładzie:

- hosts:
    - myhost
  roles:
    - openwisp.openwisp2-imagegenerator
  vars:
    openwisp2fw_controller_url: "https://openwisp.myproject.com"
    openwisp2fw_organizations:
      - name: staging
        flavours:
          - default
        openwisp:
          url: "{{ openwisp2fw_controller_url }}"
          shared_secret: "xxxxx"
        root_password: "xxxxx"
        categories:
          default: <CATEGORY-UUID>
      - name: prod
        flavours:
          - default
        openwisp:
          url: "{{ openwisp2fw_controller_url }}"
          shared_secret: "xxxxx"
        root_password: "xxxxx"
        categories:
          default: <CATEGORY-UUID>
    openwisp2fw_uploader:
        enabled: true
        url: "{{ openwisp2fw_controller_url }}"
        token: "<REST-API-USER-TOKEN>"
        image_types:
            - ath79-generic-ubnt_airrouter-squashfs-sysupgrade.bin
            - ar71xx-generic-ubnt-bullet-m-xw-squashfs-sysupgrade.bin
            - ar71xx-generic-ubnt-bullet-m-squashfs-sysupgrade.bin
            - octeon-erlite-squashfs-sysupgrade.tar
            - ath79-generic-ubnt_nanostation-loco-m-xw-squashfs-sysupgrade.bin
            - ath79-generic-ubnt_nanostation-loco-m-squashfs-sysupgrade.bin
            - ath79-generic-ubnt_nanostation-m-xw-squashfs-sysupgrade.bin
            - ar71xx-generic-ubnt-nano-m-squashfs-sysupgrade.bin
            - ath79-generic-ubnt_unifiac-mesh-squashfs-sysupgrade.bin
            - x86-64-combined-squashfs.img.gz
            - x86-generic-combined-squashfs.img.gz
            - x86-geode-combined-squashfs.img.gz
            - ar71xx-generic-xd3200-squashfs-sysupgrade.bin

Następujące miejsca w przykładzie należy zastąpić:

• <CATEGORY-UUID> to UUID kategorii oprogramowania w OpenWISP Firmware Upgrader
• <REST-API-USER-TOKEN> to token autoryzacyjny REST użytkownika, który ma uprawnienia do przesyłania obrazów

Możesz odzyskać token autoryzacyjny REST, wysyłając żądanie POST za pomocą przeglądarkowej interfejsu API OpenWISP:

1. Otwórz przeglądarkę pod adresem https://<openwisp-base-url>/api/v1/user/token/.
2. Wprowadź nazwę użytkownika i hasło w formularzu na dole strony.
3. Wyślij formularz, a otrzymasz token autoryzacyjny REST w odpowiedzi.

Skrypt przesyłania tworzy nowy obiekt kompilacji, a następnie przesyła obrazy oprogramowania określone w image_types, które muszą odpowiadać identyfikatorom takim jak ar71xx-generic-tl-wdr4300-v1-il-squashfs-sysupgrade.bin, zdefiniowanym w plik hardware.py modulu OpenWISP Firmware Upgrader.

Inne ważne punkty dotyczące skryptu upload_firmware.py:

• Skrypt odczytuje CONFIG_VERSION_DIST i CONFIG_VERSION_NUMBER z pliku .config źródła OpenWrt, aby określić wersję budowy.
• Skrypt sprawdzi, czy kompilacja o tej samej wersji i kategorii już istnieje i spróbuje dodać obrazy do tej kompilacji, zamiast tworzyć nową. Jeśli znajdzie duplikaty, na konsoli zostanie wydrukowana wiadomość o błędzie, ale skrypt nie zakończy działania; umożliwia to generowanie obrazów dla nowych modeli sprzętowych i dodawanie ich do istniejących kompilacji.

Dodawanie plików do obrazów

Możesz dodać dowolne pliki do każdego wygenerowanego obrazu, umieszczając te pliki w katalogu o nazwie files/ w katalogu swojego playbooka.

Przykład:

.
├── hosts
├── playbook.yml
└── files/etc/profile

files/etc/profile zostanie dodany do każdego generowanego obrazu.

Dodawanie plików do obrazów konkretnych organizacji

Możesz również dodać pliki do obrazów konkretnych organizacji.

Powiedzmy, że masz organizację o nazwie snakeoil i chcesz dodać niestandardowy baner, możesz to zrobić, tworząc następującą strukturę katalogów:

.
├── hosts
├── playbook.yml
└── organizations/snakeoil/etc/banner

Ponieważ ten krok jest jednym z ostatnich wykonywanych przed budowaniem końcowych obrazów, możesz wykorzystać tę funkcję, aby nadpisać dowolny plik zbudowany automatycznie podczas wcześniejszych kroków.

Dodatkowe parametry

Możesz przekazać następujące dodatkowe parametry do ansible-playbook:

• recompile: czy powtórzyć krok kompilacji
• cores: liczba rdzeni do użycia podczas kroku kompilacji
• orgs: lista nazw organizacji rozdzielona przecinkami, jeśli musisz ograniczyć generowanie obrazów do konkretnych organizacji

Przykłady

Powtórz kompilację z 16 rdzeniami:

ansible-playbook -i hosts playbook.yml -e "recompile=1 cores=16"

Generuj obrazy tylko dla organizacji foo:

ansible-playbook -i hosts playbook.yml -e "orgs=foo"

Generuj obrazy tylko dla organizacji foo i bar:

ansible-playbook -i hosts playbook.yml -e "orgs=foo,bar"

Uruchomienie konkretnych kroków

Ponieważ każdy krok w procesie jest oznaczony tagiem, możesz uruchomić konkretne kroki, używając tagów ansible.

Przykład 1, uruchom tylko przygotowanie generatorów:

ansible-playbook -i hosts playbook.yml -t generator

Przykład 2, uruchom tylko przygotowanie generatorów i kroki budowania:

ansible-playbook -i hosts playbook.yml -t generator,build

Cele bez podcelów

Ten przykład pokazuje, jak wypełnić openwisp2fw_source_targets, aby skompilować cele, które nie określają podcelu (np. sunxi, ARMv8, QEMU):

openwisp2fw_source_targets:
    # SOC Allwinner, Lamobo R1
    - system: sunxi
      profile: sun7i-a20-lamobo-r1
    # Wirtualny obraz QEMU ARM
    - system: armvirt
      profile: Default

Wsparcie

Zobacz Kanały wsparcia OpenWISP.