grzegorznowak.cardano_node

Rola Węzła Cardano

Instaluje Węzeł Cardano jako usługę systemd na systemach Ubuntu i Debian. Następnie opakowuje go w tortilla Ansible, aby te operacje były kontrolowalne, idempotentne i znacznie prostsze.

Można dodać i zintegrować CNCLI, gdy tak wskazano.

Obsługiwane dystrybucje

Przyjęcie i wsparcie więcej dystrybucji będzie w dużej mierze zależało od opinii użytkowników.

Prosimy o dodanie swoich przypadków użycia do trackerów problemów, a my je przeanalizujemy w miarę postępu prac.

Ubuntu

20.04
18.04

Debian

Bullseye

Instalacja

jedna z opcji:

ansible-galaxy install grzegorznowak.cardano_node
klonowanie repozytorium bezpośrednio

Przykład playbooka

Istnieją 2 główne metody instalacji:

Kompilacja ze źródła
Użycie gotowych binariów od IOHK

można kontrolować za pomocą flagi cardano_install_method. Zobacz sekcję Konfiguracja poniżej.

Instalacja z binariów powinna zwykle odpowiadać większości przypadków, ale można użyć źródła, aby odblokować ostateczną wersję dla geeków.

Ten role stara się przetestować obie metody.

Gdy sklonowane z Github

- name: Konfiguracja Węzła Cardano
  hosts: all
  vars:
    cncli_add: true  # doda CNCLI
    cardano_wallets:  # utworzy dwa portfele dla Ciebie
      - oszczędności
      - operacje
  roles:
    - cardano-node-role

Gdy zainstalowane za pomocą ansible-galaxy

- name: Konfiguracja Węzła Cardano
  hosts: all
  vars:
    cncli_add: true  # doda CNCLI
    cardano_wallets:  # utworzy dwa portfele dla Ciebie
      - oszczędności
      - operacje
  roles:
    - grzegorznowak.cardano_node

Konfiguracja i użycie

Domyślnie instaluje Cardano dla użytkownika i grupy cardano. Jest to zalecana praktyka. Wszystkie inne elementy do dostosowania można znaleźć w pliku defaults/main.yml.

Szczegółowe przykłady użycia i polecenia do skopiowania będą dostępne w kolejnych sprintach.

Tokeny NFT

Idempotentnie mintuj natywne tokeny NFT za pomocą tej roli. Nie będę ponownie próbować mintować tokenu, jeśli jest już obecny w pożądanej ilości.

W tym momencie wybite tokeny są wysyłane na adres użyty do ich wybicia.

Minimalna konfiguracja potrzebna na mainnet:

cardano_install_method: dist
active_network: main
cardano_wallets:
  - &wallet_default default
cardano_nfts:
  - slug: BurningGiraffe
    description: Burning Giraffe
    image: ""  # hash IPFS NFT
    name: Burning Giraffe
    id: 1
    open_period: 1000000  
    quantity: 10
    wallet: *wallet_default

Tokeny Natywne

Idempotentnie mintuj natywne tokeny (nie NFT) za pomocą tej roli. Nie będę ponownie próbować mintować tokenu, jeśli jest już obecny w pożądanej ilości.

W tym momencie wybite tokeny są wysyłane na adres użyty do ich wybicia.

Minimalna konfiguracja potrzebna na mainnet:

cardano_install_method: dist
active_network: main
cardano_wallets:
  - &wallet_default default
cardano_assets:
  - name: MyAsset
    quantity: 1000000
    wallet: *wallet_default

Adresy Płatności

Możemy śledzić adresy ADA, które mamy do dyspozycji.

Uwaga: Ta rola (jeszcze) nie integruje żadnego oprogramowania portfelowego. To, co robimy, to tworzenie potrzebnych plików do wysyłania i odbierania płatności za pomocą poleceń cli. "Portfel" w tym kontekście oznacza nazwaną ścieżkę, która przechowuje powiązane pliki.

Aktualne podejście to tylko tworzenie portfeli, które nie istnieją, a także raportowanie, jeśli znajdzie uszkodzone – np. brakujące klucze prywatne. Z powodów bezpieczeństwa nie będziemy próbować usuwać istniejących portfeli, chociaż stoi to w sprzeczności z filozofią Ansible definiowania i konwergencji do określonego stanu systemu.

# wypełnij listą nazw portfeli, które chcesz śledzić za pomocą tej roli
cardano_wallets:
  - oszczędności
  - operacje

Na podstawie powyższego przykładu – zakładając, że używane są wszystkie domyślne wartości – wygenerowane adresy portfeli będą znajdować się pod:

/home/cardano/wallets/savings/payment.addr
/home/cardano/wallets/operations/payment.addr

obok kluczy prywatnych portfeli

Asercja Statusu Synchronizacji Węzła

Zatrzymaj wykonanie playbooka, aż węzeł Cardano będzie w pełni zsynchronizowany.

- name: Czekaj, aż w pełni się zsynchronizujemy
  assert_cardano_synced:
    cardano_node_socket: "{{ cardano_node_socket }}"
    cardano_bin_path: "{{ cardano_bin_path }}"
    active_network: "{{ active_network }}"
    testnet_magic: "{{ network_magic }}"  # używane tylko w testnecie
  retries: 60
  delay: 240    # czekaj do 4 godzin na pełną synchronizację
  become: true
  become_user: "{{ cardano_user }}"
  register: sync_check_result
  until: sync_check_result.progress | int == 100

Asercja Funduszy

Upewnij się, że dany adres ma przynajmniej określoną ilość Ada do dyspozycji. Przydatne do monitorowania usługi, która musi mieć zawsze trochę Ada, lub do blokowania określonych operacji, które wymagają dostępności określonych ilości.

- set_fact
      wallet_to_check: default
      lovelace_needed: 1000000000

- name: Zbieranie portfeli
  cardano_wallet:
    cardano_bin_path: "{{ cardano_bin_path }}"
    name: "{{ wallet_to_check }}"
    active_network: "{{ active_network }}"
    testnet_magic: "{{ network_magic }}"  # używane tylko w testnecie
  become: true
  become_user: "{{ cardano_user }}"
  register: wallet_results

- name: Upewnij się, że mamy trochę Lovelace
  assert_address_funded:
    cardano_node_socket: "{{ cardano_node_socket }}"
    cardano_bin_path: "{{ cardano_bin_path }}"
    active_network: "{{ active_network }}"
    testnet_magic: "{{ network_magic }}"  # używane tylko w testnecie
    expected_lovelace: "{{ lovelace_needed }}"
    address: "{{ wallet_results['wallets_addresses'][wallet_to_check] }}"    
  retries: 60
  delay: 240    # czekaj do 4 godzin na pełną synchronizację
  become: true
  become_user: "{{ cardano_user }}"
  register: lovelace_result
  until: lovelace_result.lovelace | int > lovelace_needed

Ustawienia Ogólne

# Użytkownik Cardano
cardano_user: cardano
cardano_group: cardano
cardano_home_directory: "/home/{{ cardano_user }}"

# możliwe opcje:
# src - kompilacja ze źródła
# dist - użycie oficjalnego binarnego
cardano_install_method: dist

# Zmienne wersji
ghc_version: 8.10.4
cabal_version: 3.4.0.0

# Dotyczy tylko przy budowie ze źródła
cardano_node_version: 1.33.0

# Dotyczy tylko przy instalacji z dystrybucji
cardano_hydra_build: 9941151
# zawsze sprawdzaj swój sha, inaczej możesz otrzymać coś szkodliwego
cardano_dist_sha_256: eb7fbc652f79bcb8f56699ed7fee174a4ed321307c7086838d44972136795543
cardano_dist_url: "https://hydra.iohk.io/build/{{ cardano_hydra_build }}/download/1"

# Konfiguracja usługi
cardano_listen_addr: 127.0.0.1
cardano_listen_port: 22322  # musi być w górnym zakresie, jeśli działa jako użytkownik bez uprawnień

# Konfiguracja CNCLI
cncli_add: false  # ustaw na 'true', aby włączyć cncli z usługą cncli-sync

Jest tego więcej, więc przejdź do pliku defaults/main.yml, aby zobaczyć wszystkie szczegóły.

CLI Cardano

Jednym z końcowych celów tego repozytorium jest zdelokalizowanie operacji Cardano za pomocą zadań Ansible, ale nic nie stoi na przeszkodzie, aby bezpośrednio komunikować się z usługami i binariami.

su cardano
cd ~/bin
./cardano-cli --help

Szczegóły użycia znajdują się bezpośrednio w dokumentacji cardano-cli

CNCLI

Szczegóły użycia dostępne są w oryginalnym repozytorium

Zarządzanie usługami

Używaj go jak każdej innej usługi

# zarządzanie procesem cardano-node:
systemctl status cardano-node
systemctl restart cardano-node

# przeglądanie ogólnych logów
journalctl -u cardano-node

Interakcja z usługą synchronizacji CNCLI, gdy jest włączona

# zarządzanie procesem cncli-sync
systemctl status cncli-sync
systemctl restart cncli-sync

# przeglądanie ogólnych logów
journalctl -u cncli-sync

Testowanie integracyjne

lokalnie na LXD

LXD powinno być już zainstalowane i skonfigurowane.

Uruchom pełny zestaw testów z ./test-local.sh

Kompilacja wymaganych binariów jest zadaniem wymagającym dużej mocy CPU, więc przygotuj się na długi proces.

w Chmurze za pomocą pipeline CI

CI zbudowane na infrastrukturze DO i uruchamiane przy każdym istotnym zestawie zmian w gałęzi main.

Aby ograniczyć koszty uruchamiania, obecnie CI dla kompilacji z źródła jest uruchamiane tylko na Focal Fossa.

CI dla gotowych binariów uruchamiane jest na focal i bionic.

Inne obsługiwane platformy są oceniane lokalnie.

Motywacja

Ta rola to ciągłe badanie konfiguracji backendu Cardano i usług, z funkcjonalnością, która będzie rosła w miarę lepszego zrozumienia.

Zrealizowana zgodnie z wysokimi standardami TDD i programowania, zapewniając, że zmiany nie łamią istniejących komponentów.

Pamiętaj, aby zawsze prosić o testy, zamawiając swoją pizzę Ansible.

Kiedy powinienem używać tej roli zamiast oficjalnego obrazu docker?

Po pierwsze, docker to świetne narzędzie, które wykorzystuję w swoich projektach, aby zapewnić spójne obrazy do konkretnych zadań. Specyfika dockera wiąże się z ceną, a mianowicie nie jest łatwe do pracy w zakresie sieci lub systemd. Sam w sobie nie potrafi naprawdę zrobić tego wszystkiego w pełni i dlatego musimy sięgnąć po kubernetes, docker-swarms itp. Co jest całkowicie w porządku, dopóki nie potrzebujesz rzeczywiście dostosowanej konfiguracji z VPN-mesh lub monitorowaniem usług na żywo - zaczynasz dodawać kolejne warstwy skomplikowania do systemu tylko po to, aby rozwiązać problemy, które przynosi sam docker; z wieloma zależnościami, które nie są łatwe do wdrożenia zgodnie z zasadą infra-as-code.

Jeśli czegokolwiek nauczyłem się przez lata w programowaniu, to to, że nie ma jednego rozwiązania, które spełnia wszystkie wymagania. W pewnym momencie, gdy rozważana jest platforma o krytycznym znaczeniu dla produkcji, próba wpasowania dockera w poprawnie zdefiniowane i kontrolowane otoczenie jest po prostu znacznie większą pracą niż skompilowanie dobrze rozumianego i minimalnego zestawu ról, które przynoszą konkretne korzyści.

Jeśli nie projektujesz systemu z podejściem "najpierw docker", co osobiście uważam za bardzo okrężną drogę, to możesz docenić tę rolę. Z wartością dodaną, że jest doskonale przejrzysta; więc nigdy nie martwisz się, co zawiera twój obraz dockera, oprócz tego, co obiecuje.

Pierwsze testy zostały przeprowadzone z użyciem kontenerów lxd, które są lekkie, szybkie i natywne dla ubuntu, i mogą symulować rzeczywiste serwery na poziomie, na którym docker naprawdę nie potrafi.

Warte uwagi

Dzięki Molecule obecnie znajdujemy się w erze test-driven-infra-as-code. Co także jest manifestacją tego projektu. Więc odwiedź https://github.com/ansible-community/molecule i daj mu trochę miłości i uwagi.