Instalación de un nodo de ejecución en la red ISBE
Este documento describe el procedimiento estándar para desplegar un nodo de ejecución (no validador) Hyperledger Besu dentro de la red ISBE (entornos dev, pre o pro). Los nodos de ejecución permiten a un caso de uso conectarse a la red, desplegar contratos y enviar transacciones.
El nodo de ejecución se despliega como un pod de Kubernetes mediante el Helm chart besu-node proporcionado por ISBE, no mediante Docker Compose. Esto es coherente con el resto de la infraestructura de red (ver Requisitos de infraestructura NAP), que también se ejecuta sobre Kubernetes/k3s.
Aunque despliegues y operes tu propio nodo de ejecución, tus aplicaciones no deben acceder directamente al puerto RPC del nodo. Todo el acceso RPC debe realizarse a través de un Filtering Proxy, que es quien internamente se conecta al puerto del nodo. Esto es un requisito obligatorio de cumplimiento RGPD, no una recomendación.
El Filtering Proxy no lo despliega ISBE por ti: lo despliegas tú, como parte del stack cliente ISBE (junto al node-manager y el middleware), siguiendo el mismo modelo que en la infraestructura de un NAP (ver Requisitos de infraestructura). Al operar tú ese Filtering Proxy, eres tú quien determina y expone la URL de acceso para tus propias aplicaciones — ISBE no te la asigna.
Como consecuencia, WebSocket no está disponible bajo ninguna modalidad: el Filtering Proxy solo expone HTTP RPC. El campo node.besu.ws.enabled del values.yaml debe permanecer en false.
El proceso consta de cuatro fases:
- Preparar el acceso al clúster y al registro de artefactos de ISBE.
- Configurar y desplegar el chart Helm del nodo Besu.
- Desplegar el stack cliente ISBE (Filtering Proxy, middleware y node-manager) junto al nodo.
- Solicitar el permisionado para unir el nodo al P2P de ISBE.
1. Requisitos previos
Antes de iniciar la instalación, el participante debe disponer de:
Acceso y herramientas
- Un clúster de Kubernetes (o k3s) donde desplegar el nodo, propio o gestionado.
- Cliente Helm ≥ 3.x instalado y configurado contra ese clúster.
- Credenciales de acceso al registro OCI privado de charts e imágenes que ISBE proporciona al participante.
Hardware recomendado (pod del nodo)
- 4 Gi de RAM
- 40 Gi de almacenamiento persistente (PVC)
- Sin límite estricto de CPU (según disponibilidad del clúster)
Sistema operativo de los nodos del clúster
- Linux 64-bit, compatible con Kubernetes/k3s
Red y puertos
| Puerto | Uso |
|---|---|
| 30303/tcp | P2P (entrada/salida) |
| 30303/udp | Discovery |
| 8545/tcp | RPC HTTP (si se expone) |
IMPORTANTE: Para que el nodo de ejecución se una al P2P de ISBE, el puerto 30303/tcp debe estar accesible desde Internet (habitualmente mediante un Ingress/Load Balancer gestionado en el clúster).
2. Obtener los artefactos de despliegue
ISBE proporciona, al dar de alta al participante:
- El Helm chart
besu-nodey su versión validada, publicados en un registro OCI privado. - Un fichero
values.yamlde referencia para nodo no-validador (nombre del nodo, recursos, configuración RPC/P2P). - El fichero
genesis.jsoncorrespondiente al entorno de destino (dev/pre/pro). - La lista de nodos estáticos (
static-nodes.json) con los enodes de los bootnodes de ISBE a los que debe conectarse el nodo.
Autenticarse en el registro OCI indicado por ISBE:
helm registry login <registro-oci-proporcionado-por-isbe>
3. Configurar el values.yaml del nodo
Parámetros principales a revisar/ajustar en el values.yaml proporcionado:
| Parámetro | Valor de referencia | Notas |
|---|---|---|
fullnameOverride | <Nombre_nodo> | Nombre del nodo/release Helm |
quorumFlags.isBootnode | false | Un nodo de ejecución nunca es bootnode |
quorumFlags.usesBootnodes | según entorno | Indica si se conecta a bootnodes desplegados en el propio clúster |
node.besu.resources.memLimit / memRequest | 4Gi | Memoria del pod |
node.besu.p2p.port | 30303 | Puerto P2P |
node.besu.p2p.staticNodes | /config/static/static-nodes.json | Enodes de los bootnodes de ISBE |
node.besu.p2p.maxPeers | 25 | Límite de peers |
node.besu.rpc.port | 8545 | Puerto RPC HTTP |
node.besu.rpc.api | ["ETH","NET","QBFT"] | APIs habilitadas |
node.besu.ws.enabled | false | WebSocket — debe permanecer deshabilitado (no soportado por el Filtering Proxy) |
image.besu.tag | según entorno | Versión de Besu validada por ISBE |
storage.pvcSizeLimit | 40Gi | Almacenamiento persistente del nodo |
El equipo ISBE proporciona estos ficheros ya ajustados a tu entorno para evitar errores de configuración; normalmente solo necesitas personalizar el nombre del nodo y, si aplica, la exposición pública (Ingress).
4. Desplegar el nodo con Helm
helm install <Nombre_nodo> oci://<registro-oci-proporcionado-por-isbe>/isbe-helm-charts/besu-node \
--version <version-indicada-por-isbe> \
-f values-nodo-ejecucion.yml
El chart genera automáticamente el par de claves del nodo al desplegarse (persistidas como Secret de Kubernetes). ISBE indicará el procedimiento (kubectl logs / kubectl exec sobre el pod) para obtener el enode de tu nodo, necesario para el paso de permisionado.
5. Desplegar el stack cliente ISBE (Filtering Proxy)
ISBE proporciona el chart/manifiestos del stack cliente ISBE (node-manager, middleware e isbe-client proxy — el Filtering Proxy), para que lo despliegues junto a tu nodo, en el mismo clúster/namespace. Debe usarse sin modificar.
Este componente es el que aplica el borrado lógico GDPR sobre los datos que salen de tu nodo, y es el único punto de acceso RPC permitido para tus aplicaciones. Tú decides cómo exponerlo (Ingress, Load Balancer interno, etc.) y, por tanto, cuál es la URL final que usarán tus aplicaciones — no es un dato que ISBE te asigne.
Consulta la guía de despliegue del stack cliente que te proporcione ISBE para los valores concretos de tu entorno.
6. Verificar el estado de los pods
kubectl get pods -l app.kubernetes.io/instance=<Nombre_nodo>
kubectl logs -f <pod-del-nodo>
El nodo no podrá sincronizar ni entrar en la red P2P hasta que ISBE autorice su enode (ver siguiente sección).
7. Solicitar el permisionado
Sigue el procedimiento descrito en Solicitud de permisionado, aportando el enode obtenido en el paso 4.
Una vez aprobado, el nodo:
- Será incluido en la lista de nodos autorizados.
- Podrá conectarse a los bootnodes.
- Empezará a sincronizar la cadena.
8. Verificación después del permisionado
Las siguientes comprobaciones son para verificación técnica interna del operador del nodo (por ejemplo, vía kubectl exec dentro del clúster). No representan cómo debe conectarse una aplicación: ese acceso se hace siempre a través del Filtering Proxy (ver más abajo).
Comprobar estado del P2P:
curl http://localhost:8545 \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}'
Debe devolver un número mayor que cero cuando esté conectado a la red.
Comprobar altura de bloque:
curl http://localhost:8545 \
-H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
El valor debe incrementarse aproximadamente cada 2 segundos.
9. Uso posterior del nodo
Una vez sincronizado, el nodo de ejecución permite:
- Desplegar contratos.
- Leer el estado on-chain.
- Enviar transacciones firmadas.
Tus aplicaciones deben conectarse siempre a través del Filtering Proxy que has desplegado en el paso 5 (nunca directamente al puerto del nodo). Tú, como Network Provider, eres quien define y comunica esa URL a tus propias aplicaciones.
El nodo queda bajo la responsabilidad operativa del caso de uso:
- Backups del PVC (por ejemplo, mediante Velero si el clúster lo soporta).
- Logs y monitorización del pod.
- Seguridad del clúster/namespace donde se aloja.
- Actualizaciones de la imagen de Besu y del chart, según las versiones validadas por ISBE.
La red ISBE únicamente controla el permisionado y la topología P2P.