grzegorznowak.cardano_node

Descripción general Versiones Perspectivas

Rol del Nodo de Cardano

Instala el Nodo de Cardano como un servicio systemd en Ubuntu y Debian. Luego, lo envuelve con una tortilla de Ansible para hacer ciertas operaciones controlables, idempotentes y mucho más simples en general.

Puede agregar e integrar CNCLI cuando se indique.

Distribuciones Soportadas

La adopción y soporte de más distribuciones dependerá en gran medida de los comentarios de los usuarios.

Por favor, agrega tus casos de uso al rastreador de problemas y los clasificaremos a medida que avancemos.

Ubuntu

20.04
18.04

Debian

bullseye

Instalación

una de las siguientes:

ansible-galaxy install grzegorznowak.cardano_node
clonar el repositorio directamente

Ejemplo de playbook

Hay 2 modos principales de instalación:

Compilación desde la fuente
Uso de binarios precompilados de IOHK

controlable con el flag cardano_install_method. Consulta la sección de Configuración más adelante.

La instalación de distros en binario debería ajustarse en general a la mayoría de los casos, pero siéntete libre de usar la fuente para desbloquear la construcción máxima.

Este rol intenta probar ambas opciones.

Cuando se clona desde GitHub

- name: Converge Nodo Cardano
  hosts: all
  vars:
    cncli_add: true  # incluirá CNCLI
    cardano_wallets:  # creará dos billeteras para ti
      - ahorros
      - operaciones
  roles:
    - cardano-node-role

Cuando se instala con ansible-galaxy

- name: Converge Nodo Cardano
  hosts: all
  vars:
    cncli_add: true  # incluirá CNCLI
    cardano_wallets:  # creará dos billeteras para ti
      - ahorros
      - operaciones
  roles:
    - grzegorznowak.cardano_node

Configuración y Uso

Por defecto, instala Cardano para un usuario y grupo cardano. Lo cual es una práctica recomendada. Todos los demás elementos que puedes modificar se encuentran en defaults/main.yml.

Ejemplos de uso más detallados y comandos para copiar y pegar llegarán en sprints posteriores.

Tokens NFT

Crea tokens NFT nativos de manera idempotente con este rol. No volveré a intentar acuñar el token si ya está presente y en la cantidad deseada.

En este punto, los tokens acuñados se envían a la dirección que usamos para acuñar.

Configuración mínima necesaria en mainnet:

cardano_install_method: dist
active_network: main
cardano_wallets:
  - &wallet_default default
cardano_nfts:
  - slug: BurningGiraffe
    description: Jirafa Ardiente
    image: ""  # un hash IPFS del NFT
    name: Jirafa Ardiente
    id: 1
    # cantidad de espacios para reservar para que los metadatos de política de este NFT sean editables:
    open_period: 1000000  
    quantity: 10
    wallet: *wallet_default

Tokens Nativos

Crea tokens nativos (no NFT) de manera idempotente con este rol. No volveré a intentar acuñar el token si ya está presente y en la cantidad deseada.

En este punto, los tokens acuñados se envían a la dirección que usamos para acuñar.

Configuración mínima necesaria en mainnet:

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

Direcciones de Pago

Podemos llevar un registro de las direcciones ADA a nuestra disposición.

NOTA: Este rol no integra (aún) ningún tipo de software de billetera. Lo que hacemos es crear archivos necesarios para enviar y recibir pagos usando comandos cli. "Billetera" en este contexto significa una ruta nombrada que contiene archivos que pertenecen juntos.

El enfoque actual es crear solo billeteras que no existan, así como informar si encuentra alguna que esté rota, es decir, faltan claves privadas. Por razones de seguridad, no intentaremos eliminar billeteras existentes, aunque esto contrasta con la filosofía de ansible de definir y converger al estado especificado del sistema.

# completa con una lista de nombres de billeteras que deseas rastrear con el rol
cardano_wallets:
  - ahorros
  - operaciones

Basado en el ejemplo anterior, suponiendo que se utilizan todos los valores por defecto, las direcciones de billetera materializadas se ubicarán en:

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

junto con las claves privadas de las billeteras.

Verificación del Estado de Sincronización del Nodo

Bloquea la ejecución de un playbook hasta que el nodo de Cardano esté completamente sincronizado.

- name: Esperar hasta que estemos completamente sincronizados
  assert_cardano_synced:
    cardano_node_socket: "{{ cardano_node_socket }}"
    cardano_bin_path: "{{ cardano_bin_path }}"
    active_network: "{{ active_network }}"
    testnet_magic: "{{ network_magic }}"  # solo usado en testnet
  retries: 60
  delay: 240    # esperar hasta 4h para la sincronización completa
  become: true
  become_user: "{{ cardano_user }}"
  register: sync_check_result
  until: sync_check_result.progress | int == 100

Verificación de Fondos

Asegúrate de que la dirección específica tenga al menos la cantidad dada de Ada a su disposición. Útil para monitorear un servicio que debe tener algo de Ada todo el tiempo, o bloquear operaciones específicas que requieren ciertos montos disponibles.

- set_fact
      wallet_to_check: default
      lovelace_needed: 1000000000

- name: Recoger billeteras
  cardano_wallet:
    cardano_bin_path: "{{ cardano_bin_path }}"
    name: "{{ wallet_to_check }}"
    active_network: "{{ active_network }}"
    testnet_magic: "{{ network_magic }}"  # solo usado en testnet
  become: true
  become_user: "{{ cardano_user }}"
  register: wallet_results

- name: Asegurarse de que tengamos algo de Lovelace
  assert_address_funded:
    cardano_node_socket: "{{ cardano_node_socket }}"
    cardano_bin_path: "{{ cardano_bin_path }}"
    active_network: "{{ active_network }}"
    testnet_magic: "{{ network_magic }}"  # solo usado en testnet
    expected_lovelace: "{{ lovelace_needed }}"
    address: "{{ wallet_results['wallets_addresses'][wallet_to_check] }}"    
  retries: 60
  delay: 240    # esperar hasta 4h para la sincronización completa
  become: true
  become_user: "{{ cardano_user }}"
  register: lovelace_result
  until: lovelace_result.lovelace | int > lovelace_needed

Configuración General

# Usuario de Cardano
cardano_user: cardano
cardano_group: cardano
cardano_home_directory: "/home/{{ cardano_user }}"

# posibles opciones:
# src - compilar desde la fuente
# dist - usar el binario oficial
cardano_install_method: dist

# Variables de versión
ghc_version: 8.10.4
cabal_version: 3.4.0.0

# Aplicable solo cuando se construye desde src
cardano_node_version: 1.33.0

# Aplicable solo cuando se instala desde dist
cardano_hydra_build: 9941151
# siempre confirma tu sha, o podrías estar recibiendo un veneno
cardano_dist_sha_256: eb7fbc652f79bcb8f56699ed7fee174a4ed321307c7086838d44972136795543
cardano_dist_url: "https://hydra.iohk.io/build/{{ cardano_hydra_build }}/download/1"

# Configuración del Servicio
cardano_listen_addr: 127.0.0.1
cardano_listen_port: 22322  # debe estar en el rango superior si se ejecuta como usuario no privilegiado

# Configuración de CNCLI
cncli_add: false  # establece en 'true' para habilitar cncli con el servicio cncli-sync

Hay más, así que dirígete al archivo defaults/main.yml directamente para ver todos los pequeños detalles.

Cardano CLI

Uno de los objetivos finales de este repositorio es abstraer las operaciones de Cardano con tareas de ansible, pero no hay nada que te impida interactuar directamente con los servicios y binarios.

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

Para detalles de uso ve a la documentación de cardano-cli directamente

CNCLI

Para detalles de uso, consulta el repositorio original

Gestión de Servicios

Úsalo como cualquier otro servicio

# gestionando el proceso cardano-node:
systemctl status cardano-node
systemctl restart cardano-node

# viendo registros generales
journalctl -u cardano-node

Interacción con el servicio de sincronización CNCLI, cuando esté habilitado

# gestionando el proceso cncli-sync
systemctl status cncli-sync
systemctl restart cncli-sync

# viendo registros generales
journalctl -u cncli-sync

Pruebas de Integración

localmente en LXD

LXD debería estar ya instalado y configurado.

Inicia la suite completa con ./test-local.sh

La compilación de los binarios requeridos es una tarea pesada para la CPU, así que prepárate para un proceso largo.

en la Nube a través de la canalización CI

La CI se construyó sobre la infraestructura de DO y se activa contra cada cambio significativo en la rama main.

Para limitar los costos de ejecución, la CI que compila desde fuente se realiza solo contra Focal Fossa en este momento.

La CI de binarios precompilados se realiza contra focal y bionic.

Las otras plataformas soportadas se están evaluando localmente.

Motivación

Este rol es una exploración continua de la configuración de backend y servicios de Cardano, con una funcionalidad que crecerá con el tiempo a medida que comprendamos mejor el campo de búsqueda.

Elaborado utilizando altos estándares de TDD y codificación, asegurando que los cambios no rompan ninguno de los componentes existentes.

Recuerda siempre pedir pruebas cuando pidas tu pizza de ansible.

¿Cuándo debería usar este rol en lugar de la imagen oficial de Docker?

Primero que todo, Docker es una gran herramienta que utilizo en mis proyectos para proporcionar imágenes consistentes para tareas concretas. La especificidad de Docker tiene un precio y eso es que no es divertido cuando se trata de redes o systemd. Por sí solo, realmente no puede hacer ninguna de esas cosas completamente y así existen Kubernetes, Docker Swarms, etc. Eso está perfectamente bien hasta que necesites hacer una configuración específica con VPN de malla o monitoreo de servicios en vivo; comienzas a agregar capa tras capa de complejidad al sistema solo para resolver problemas que Docker mismo trajo, con muchas dependencias que no son fáciles de implementar con el principio de infraestructura como código.

Si he aprendido algo a lo largo de los años en el desarrollo, es que verdaderamente no hay solución que se ajuste a todo. En algún momento, cuando se considera una plataforma de nivel de producción, intentar modelar Docker dentro de un entorno definido y controlado es simplemente mucho más trabajo que compilar un conjunto bien entendido y mínimo de roles que proporcionen un valor específico.

Si no estás desarrollando el sistema con un enfoque de Docker primero, lo cual personalmente encuentro un poco indirecto eventualmente, entonces podrías disfrutar este rol. Con el valor agregado de ser perfectamente transparente; así que nunca te preocupas por lo que viene empaquetado en tu imagen de Docker, más allá de lo que dice.

Las pruebas iniciales se realizaron usando contenedores LXD, que son livianos, rápidos y nativos de Ubuntu, y pueden simular servidores reales a un nivel que Docker realmente no puede.

Notable

Gracias a Molecule, actualmente estamos en la era de infraestructura como código basada en pruebas. Lo cual también es una manifestación de este proyecto. Así que dirígete a https://github.com/ansible-community/molecule y dale un poco de amor y atención.