Роль узла Cardano

Устанавливает узел Cardano как службу systemd на Ubuntu и Debian. Затем оборачивает его в "тортилью" Ansible, чтобы сделать определенные операции управляемыми, идемпотентными и значительно проще в целом.

Можно добавить и интегрировать CNCLI, если это будет указано.

Поддерживаемые дистрибутивы

Адаптация и поддержка большего количества дистрибутивов будет во многом зависеть от отзывов пользователей.

Пожалуйста, добавьте ваши случаи использования в трекер ошибок, и мы обработаем их по мере поступления.

Ubuntu

• 20.04
• 18.04

Debian

• bullseye

Установка

Один из способов:

• ansible-galaxy install grzegorznowak.cardano_node
• Клонировать репозиторий напрямую

Пример плейбука

Существуют 2 основных метода установки:

• Компиляция из источника
• Использование заранее собранных бинарных файлов от IOHK

Управляется с помощью флага cardano_install_method. Смотрите раздел Конфигурация ниже.

Установка бинарного дистрибутива должна в целом подойти для большинства случаев, но можете использовать источник, чтобы открыть возможности для глубокой настройки.

Эта роль пытается протестировать оба подхода.

При клонировании с GitHub

- name: Установка узла Cardano
  hosts: all
  vars:
    cncli_add: true  # будет включен CNCLI
    cardano_wallets:  # создаст два кошелька для вас
      - сбережения
      - операции
  roles:
    - cardano-node-role

При установке с ansible-galaxy

- name: Установка узла Cardano
  hosts: all
  vars:
    cncli_add: true  # будет включен CNCLI
    cardano_wallets:  # создаст два кошелька для вас
      - сбережения
      - операции
  roles:
    - grzegorznowak.cardano_node

Конфигурация и использование

По умолчанию устанавливает Cardano для пользователя и группы cardano. Это рекомендуемая практика. Все остальные параметры можно найти в файле defaults/main.yml.

Более детальные примеры использования и команды для копирования и вставки будут добавлены с последующими релизами.

NFT Токены

Идемпотентно создавайте нативные NFT токены с этой ролью. Я не буду повторно пытаться создать токен, если он уже присутствует и в нужном количестве.

На данный момент созданные токены отправляются на адрес, который мы использовали для их создания.

Минимальная конфигурация, необходимая в основной сети:

cardano_install_method: dist
active_network: main
cardano_wallets:
  - &wallet_default default
cardano_nfts:
  - slug: BurningGiraffe
    description: Burning Giraffe
    image: ""  # IPFS хэш NFT
    name: Burning Giraffe
    id: 1
    # сколько слотов зарезервировать для редактирования метаданных политики этого NFT:
    open_period: 1000000  
    quantity: 10
    wallet: *wallet_default

Нативные Токены

Идемпотентно создавайте нативные токены (не NFT) с этой ролью. Я не буду повторно пытаться создать токен, если он уже присутствует и в нужном количестве.

На данный момент созданные токены отправляются на адрес, который мы использовали для их создания.

Минимальная конфигурация, необходимая в основной сети:

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

Платежные Адреса

Мы можем отслеживать адреса ADA, которые у нас есть.

ПРИМЕЧАНИЕ: Эта роль пока не интегрирует никакое программное обеспечение для кошельков. Мы создаем необходимые файлы для отправки и получения платежей с помощью CLI-команд. "Кошелек" в этом контексте означает именованный путь, содержащий связанные файлы.

Текущий подход заключается в том, чтобы создавать только кошельки, которые не существуют, а также сообщать если найдены сломанные кошельки - т.е. отсутствуют закрытые ключи. По соображениям безопасности мы не будем пытаться удалять существующие кошельки, хотя это противоречит философии Ansible, заключающейся в определении и конвергентном переходе к определенному состоянию системы.

# Заполните списком имен кошельков, которые вы хотите отслеживать с помощью этой роли
cardano_wallets:
  - сбережения
  - операции

На основе приведенного выше примера - при условии, что используются все значения по умолчанию - созданные адреса кошельков будут находиться по следующим путям:

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

вместе с закрытыми ключами кошельков.

Проверка Статуса Синхронизации Узла

Блокирует выполнение плейбука, пока узел Cardano полностью синхронизирован.

- name: Ждать полной синхронизации
  assert_cardano_synced:
    cardano_node_socket: "{{ cardano_node_socket }}"
    cardano_bin_path: "{{ cardano_bin_path }}"
    active_network: "{{ active_network }}"
    testnet_magic: "{{ network_magic }}"  # используется только в тестовой сети
  retries: 60
  delay: 240    # ожидание до 4 часов для полной синхронизации
  become: true
  become_user: "{{ cardano_user }}"
  register: sync_check_result
  until: sync_check_result.progress | int == 100

Проверка Средств

Убедитесь, что у конкретного адреса есть как минимум указанная сумма ADA. Полезно для мониторинга сервиса, который должен иметь некоторую сумму ADA в любое время, или блокировке определенных операций, которые требуют наличия определенных сумм.

- set_fact
      wallet_to_check: default
      lovelace_needed: 1000000000

- name: Сбор кошельков
  cardano_wallet:
    cardano_bin_path: "{{ cardano_bin_path }}"
    name: "{{ wallet_to_check }}"
    active_network: "{{ active_network }}"
    testnet_magic: "{{ network_magic }}"  # используется только в тестовой сети
  become: true
  become_user: "{{ cardano_user }}"
  register: wallet_results

- name: Убедитесь, что у нас есть немного Lovelace
  assert_address_funded:
    cardano_node_socket: "{{ cardano_node_socket }}"
    cardano_bin_path: "{{ cardano_bin_path }}"
    active_network: "{{ active_network }}"
    testnet_magic: "{{ network_magic }}"  # используется только в тестовой сети
    expected_lovelace: "{{ lovelace_needed }}"
    address: "{{ wallet_results['wallets_addresses'][wallet_to_check] }}"    
  retries: 60
  delay: 240    # ожидание до 4 часов для полной синхронизации
  become: true
  become_user: "{{ cardano_user }}"
  register: lovelace_result
  until: lovelace_result.lovelace | int > lovelace_needed

Общие Настройки

# Пользователь Cardano
cardano_user: cardano
cardano_group: cardano
cardano_home_directory: "/home/{{ cardano_user }}"

# возможные варианты:
# src - компилировать из источника
# dist - использовать официальный бинарный файл
cardano_install_method: dist

# Версионные переменные
ghc_version: 8.10.4
cabal_version: 3.4.0.0

# Применимо только при сборке из src
cardano_node_version: 1.33.0

# Применимо только при установке из dist
cardano_hydra_build: 9941151
# всегда проверяйте свою sha, иначе может быть добавлен вредоносный код
cardano_dist_sha_256: eb7fbc652f79bcb8f56699ed7fee174a4ed321307c7086838d44972136795543
cardano_dist_url: "https://hydra.iohk.io/build/{{ cardano_hydra_build }}/download/1"

# Конфигурация службы
cardano_listen_addr: 127.0.0.1
cardano_listen_port: 22322  # должен быть в верхнем диапазоне, если работает как непривилегированный пользователь

# Конфигурация CNCLI
cncli_add: false  # установите в 'true', чтобы включить cncli с cncli-sync службой 

Есть еще больше, поэтому смело переходите к файлу defaults/main.yml, чтобы увидеть все мелкие детали.

Cardano CLI

Одна из конечных целей этого репозитория — абстрагировать операции Cardano с помощью задач Ansible, но ничто не мешает вам взаимодействовать с сервисами и бинарными файлами напрямую.

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

Для получения деталей использования перейдите непосредственно к документации cardano-cli.

CNCLI

Для получения деталей использования смотрите оригинальный репозиторий.

Управление Службами

Используйте как любую другую службу.

# управление процессом cardano-node:
systemctl status cardano-node
systemctl restart cardano-node

# просмотр общих логов
journalctl -u cardano-node

Взаимодействие с службой синхронизации CNCLI, если она включена.

# управление процессом cncli-sync
systemctl status cncli-sync
systemctl restart cncli-sync

# просмотр общих логов
journalctl -u cncli-sync

Интеграционное Тестирование

Локально на LXD

LXD должен быть уже установлен и настроен.

Запустите полный пакет тестов с помощью ./test-local.sh.

Компиляция необходимых бинарных файлов — задача, требующая много ресурсов процессора, поэтому будьте готовы к долгому процессу.

В облаке через CI Pipeline

CI построен на базе инфраструктуры DO и запускается при каждом значительном изменении в основной ветке.

Чтобы ограничить расходы, CI-компиляция из источника на данный момент осуществляется только в Focal Fossa.

Предварительная компиляция бинарников CI проводилась для focal и bionic.

Другие поддерживаемые платформы оцениваются локально.

Мотивация

Эта роль — постоянное исследование конфигурации бэкенда и сервисов Cardano, с функциональностью, которая будет расти со временем по мере глубже понимания системы.

Создана с соблюдением высоких стандартов TDD и кодирования, чтобы изменения не ломали существующие компоненты.

Не забудьте всегда запрашивать тесты, заказывая свою "ансибле пиццу".

Когда следует использовать эту роль вместо официального образа Docker?

Во-первых, Docker — это отличное средство, которое я часто использую в своих проектах для обеспечения согласованных образов для конкретных задач. Специфика Docker имеет свою цену, и это неприятно, когда дело доходит до сетевого взаимодействия или systemd. Сам по себе он не может полностью справиться ни с одним из этих заданий, поэтому возникает необходимость в Kubernetes, Docker Swarm и т.д. Что совершенно нормально, пока вам не нужно на самом деле сделать индивидуальную настройку с VPN Mesh или мониторингом сервисов в реальном времени - вы начинаете добавлять один уровень сложности за другим, чтобы решить проблемы, которые сам Docker принёс; с множеством зависимостей, которые трудно развернуть с принципом инфраструктура как код.

Если я что-то усвоил за годы разработки, так это то, что нет универсального решения. На определённом этапе, когда рассматривается платформа уровня производства, попытка насильно интегрировать докер в корректно определённую и контролируемую среду требует гораздо больше усилий, чем компиляция хорошо понимаемого и минимального набора ролей, которые предоставляют конкретную ценность.

Если вы не разрабатываете систему с докер-первым подходом, что я лично считаю не совсем рациональным, то вам может понравиться эта роль. С дополнительным преимуществом быть совершенно прозрачной; так что вы никогда не будете волноваться о том, что ваш образ Docker включает в себя, кроме того, что он утверждает.

Первые тесты были проведены с использованием контейнеров LXD, которые легковесные, быстрые и родные для Ubuntu и могут симулировать реальные серверы на уровне, с которым Docker действительно не может справиться.

Примечания

Благодаря Molecule мы находимся в эпохе тестируемой инфраструктуры как кода. Этот проект тоже является её проявлением. Так что перейдите на https://github.com/ansible-community/molecule и уделите ему немного любви и внимания.

Целевая аудитория

Разработчики и операционные специалисты

Планы

Проект выполняется с недельными спринтами. Посмотрите там, что сейчас разрабатывается.

Общий план на будущее:

• Базовая установка узла Cardano
• Полный CI/CD
• Интеграция CNCLI
• Автоматизация создания нативных токенов
• Автоматизация создания NFT
• Интерфейс для смарт-контрактов
• Больше/лучшие примеры провизии
• Объяснение, каким будет результат выполнения этой роли в качестве публичного узла
• Автоматизация управления ключами

Это предполагается и может быть переработано в отдельные роли для модульности.