besu-eks-reference

A reference architecture for running a permissioned Hyperledger Besu network on AWS EKS — provisioned with Terraform, operated with Helm, and built the way a regulated-finance platform team would: remote signing, mTLS, secrets in Vault, and observability from day one.

This is a reference blueprint distilled from production experience, not a one-click deploy. It shows how the pieces fit together; you bring your account, secrets, and the upstream chart versions you standardise on.

Architecture

flowchart LR
  tf["Terraform"] --> eks["EKS + VPC (3 AZs)"]
  subgraph cluster["EKS"]
    besu["Besu nodes (QBFT)"]
    ws["Web3Signer"]
    ff["FireFly"]
    bs["Blockscout + verifier"]
    obs["Prometheus / Grafana / OTel"]
  end
  eks --> cluster
  besu -->|sign| ws --> vault["Vault (PKI + KV)"]
  ff & bs -->|JSON-RPC| besu
  besu & ff & bs --> obs

Loading

Full diagram and design rationale: docs/architecture.md.

What's here

Path	Contents
terraform/	VPC + EKS (managed node group, IRSA, EBS CSI, core add-ons) — terraform validate-clean
helm/	Reference values.yaml for Besu, Web3Signer, FireFly, Blockscout, and the observability stack
docs/	Architecture diagram and design decisions
.github/	CI: terraform fmt/validate + Checkov

Highlights

• Permissioned Besu (QBFT) across a multi-AZ managed node group.
• Remote signing with Web3Signer — validator keys live in Vault, never in node pods.
• mTLS in-cluster via cert-manager backed by a Vault PKI issuer.
• IRSA, not static keys — pods assume IAM roles through the cluster OIDC provider.
• FireFly as the application/orchestration layer and Blockscout (with a contract verifier) for exploration and auditing.
• Observability first — Prometheus scrapes Besu's metrics endpoint; OTel collects traces; Grafana dashboards on top.

Quick start

cd terraform
terraform init
terraform apply              # provisions the VPC + EKS cluster

aws eks update-kubeconfig --name besu-net --region eu-west-2
# then install the platform + chain components — see helm/README.md

Prerequisites

Terraform ≥ 1.6 · AWS account + CLI · kubectl · Helm 3 · (in-cluster) cert-manager, AWS Load Balancer Controller, and HashiCorp Vault.

License

MIT © Valente Vidal