blocknode

package
v0.18.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 2, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// PresetTier1LFH selects Local Full History storage (blocks stored on disk).
	PresetTier1LFH = "tier1-lfh"

	// PresetTier1RFH selects Remote Full History storage (blocks stored in S3-compatible cloud storage).
	PresetTier1RFH = "tier1-rfh"

	// PresetCustom indicates the operator selected a custom set of plugins.
	PresetCustom = "custom"
)

Plugin preset IDs used by the --plugin-preset flag and TUI prompt.

Each preset maps to a fixed, ordered plugin list maintained here in lockstep with block-node chart releases. When the block-node team changes a preset's contents or adds/removes presets, this file must be updated in the same release cycle.

View Source 
const (
	// Kubernetes resources
	ResourceNameSuffix = "-block-node-server"
	PodLabelSelector   = "app.kubernetes.io/name=block-node-server"

	// Template paths
	NamespacePath       = "files/block-node/namespace.yaml"
	StorageConfigPath   = "files/block-node/storage-config.yaml"
	OptionalStoragePath = "files/block-node/optional-storage.yaml"
	ValuesPath          = "files/block-node/full-values.yaml"
	NanoValuesPath      = "files/block-node/nano-values.yaml"

	// Timeouts
	PodReadyTimeoutSeconds      = 300
	ReachabilityProbeTimeoutSec = 60
)
View Source 
const BlockNodePublicPort int64 = 40840

BlockNodePublicPort is the well-known TCP port the block-node gRPC service listens on. It's an ecosystem-wide contract (the chart defaults to it, every SDK and tool assumes it), so the reachability probe dials it directly instead of trying to look the port up by name on the Service — chart versions have used `http`, `grpc`, and other names for it, and matching any of those is more fragile than dialing the well-known number.

View Source 
const SoloProvisionerStorageLabelSelector = "app.kubernetes.io/managed-by=solo-provisioner,app.kubernetes.io/component=block-node-storage"

SoloProvisionerStorageLabelSelector matches PVs/PVCs created by solo-provisioner's own block-node storage templates.

Variables

View Source 
var (
	ReachabilityProbeDialTimeout = 10 * time.Second
	ReachabilityProbeRetryDelay  = 2 * time.Second
)

Reachability probe dial cadence. A single dial attempt uses ReachabilityProbeDialTimeout; failed attempts back off by ReachabilityProbeRetryDelay before retrying, until the overall ReachabilityProbeTimeoutSec budget is exhausted. The dial-timeout/back-off split gives MetalLB ARP convergence and Cilium reconciler latency time to settle without making the whole probe block on a single hung connection.

View Source 
var AllBlockNodePlugins = []string{
	"facility-messaging",
	"block-access-service",
	"health",
	"server-status",
	"stream-publisher",
	"stream-subscriber",
	"verification",
	"blocks-file-historic",
	"blocks-file-recent",
	"backfill",
	"s3-archive",
}

AllBlockNodePlugins is the ordered list of available plugins shown in the TUI multi-select when the operator chooses the Custom preset. Source of truth: hiero-block-node block-node/app/build.gradle.kts (blockNodePlugins configuration).

Functions

func AvailablePresets added in v0.17.0 

func AvailablePresets() []string

AvailablePresets returns the ordered preset IDs for TUI display.

func BuildMigrationWorkflow added in v0.7.0 

func BuildMigrationWorkflow(manager *Manager, profile, valuesFile string) (*automa.WorkflowBuilder, error)

BuildMigrationWorkflow returns an automa workflow for executing applicable migrations. Returns nil if no migrations are needed (installed version is empty or no applicable migrations).

The workflow structure is: 

[migration-start] → [migration-<id>] → ... → [migration-upgrade-chart]

Each migration step creates its PV/PVC. The final upgrade step performs a single StatefulSet delete + Helm upgrade to the target version with all new storages included.

func IsKnownPreset added in v0.17.0 

func IsKnownPreset(presetID string) bool

IsKnownPreset returns true when presetID is a recognised non-custom preset.

func PluginListForPreset added in v0.17.0 

func PluginListForPreset(presetID string) string

PluginListForPreset returns the canonical comma-separated plugin list for a named preset, or an empty string when the preset ID is not recognised.

func PresetLabel added in v0.17.0 

func PresetLabel(presetID string) string

PresetLabel returns the human-readable TUI label for a preset ID, or the preset ID itself when no label is registered.

func ResolveStoragePaths added in v0.17.0 

func ResolveStoragePaths(storage models.BlockNodeStorage, chartVersion string) (archivePath, livePath, logPath string, optionalPaths []string, err error)

ResolveStoragePaths is the pure-logic counterpart of Manager.GetStoragePaths: it derives the effective archive/live/log/optional storage paths from a BlockNodeStorage config and a chart version, without requiring a Manager (and therefore without constructing fsx/helm/kube clients). Use this when you only need to canonicalize or compare paths.

func ValidateStorageCompleteness added in v0.15.0 

func ValidateStorageCompleteness(storage models.BlockNodeStorage, chartVersion string) error

ValidateStorageCompleteness checks that enough storage paths are set to resolve all required paths for the given chart version. Either basePath must be set (to derive missing paths) or all required individual paths must be explicit. This includes core paths (archive, live, log) and version-dependent optional paths (verification, plugins).

Types

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager handles block node setup and management operations. Methods are grouped by concern across sibling files:

  • storage.go — directory setup, PV/PVC lifecycle, path resolution
  • chart.go — Helm install/upgrade/uninstall, StatefulSet and pod lifecycle
  • values.go — Helm values file computation and YAML injection helpers

func NewManager 

func NewManager(blockConfig models.BlockNodeInputs) (*Manager, error)

NewManager creates a new block node manager

func (*Manager) BlockNodeServicesChanged added in v0.18.0 

func (m *Manager) BlockNodeServicesChanged(ctx context.Context) (bool, error)

BlockNodeServicesChanged returns true if the current set of Services in the block-node namespace differs from the snapshot taken by SnapshotServices, by any of: Service added, Service removed, Service spec mutated.

If SnapshotServices was never called, returns true conservatively — the caller cannot prove that nothing changed, so the safe choice is to restart Cilium.

func (*Manager) ClearStorageDirectory added in v0.8.0 

func (m *Manager) ClearStorageDirectory(dirPath string) error

ClearStorageDirectory removes all files and subdirectories from a storage directory while preserving the directory itself.

func (*Manager) ComputeValuesFile 

func (m *Manager) ComputeValuesFile(profile string, valuesFile string) (string, error)

ComputeValuesFile generates the values file for helm installation based on profile and version. It writes the result to a temp file and returns the path.

When no custom values file is provided, the appropriate built-in template is rendered. When a custom values file is provided, persistence settings are injected to ensure weaver-managed PVCs are referenced (create: false + existingClaim) rather than letting the chart create its own.

In both cases, effective retention thresholds are merged into blockNode.config.

NOTE: Defense-in-depth path validation is applied even though the CLI layer also validates.

func (*Manager) CreateNamespace 

func (m *Manager) CreateNamespace(ctx context.Context, tempDir string) error

CreateNamespace creates the block-node namespace if it doesn't exist. ApplyManifest is idempotent so this is safe to call on every install.

func (*Manager) CreateOptionalStorage added in v0.10.0 

func (m *Manager) CreateOptionalStorage(ctx context.Context, tempDir string, optStor OptionalStorage) error

CreateOptionalStorage creates a single optional PV/PVC using the unified template. Used during migration when other PVs already exist.

func (*Manager) CreatePersistentVolumes 

func (m *Manager) CreatePersistentVolumes(ctx context.Context, tempDir string) error

CreatePersistentVolumes creates PVs and PVCs from the storage config

func (*Manager) DeleteAllPersistentVolumes added in v0.17.0 

func (m *Manager) DeleteAllPersistentVolumes(ctx context.Context) error

DeleteAllPersistentVolumes deletes every block-node PV and PVC that belongs to this release: both solo-provisioner-managed (from our templates) and Helm-managed (if the chart's persistence.create override is ever turned on). PVs are cluster-scoped so the returned list is additionally filtered by spec.claimRef.namespace. Missing resources are silently ignored.

func (*Manager) DeleteNamespace 

func (m *Manager) DeleteNamespace(ctx context.Context, tempDir string) error

DeleteNamespace deletes the block-node namespace

func (*Manager) DeleteStatefulSetForUpgrade added in v0.10.0 

func (m *Manager) DeleteStatefulSetForUpgrade(ctx context.Context) error

DeleteStatefulSetForUpgrade deletes the block node StatefulSet using orphan cascading and waits for it to be fully removed from the API server. This is required before any Helm upgrade that changes volumeClaimTemplates, since Kubernetes forbids in-place updates. Returns nil if the StatefulSet does not exist.

func (*Manager) GetInstalledVersion added in v0.7.0 

func (m *Manager) GetInstalledVersion() (string, error)

GetInstalledVersion returns the currently installed Block Node chart version. Returns empty string if not installed.

func (*Manager) GetReleaseValues added in v0.7.0 

func (m *Manager) GetReleaseValues() (map[string]interface{}, error)

GetReleaseValues returns the user-supplied values from the currently installed release. Returns nil if not installed or if no user values were supplied.

func (*Manager) GetStoragePaths added in v0.6.0 

func (m *Manager) GetStoragePaths() (archivePath, livePath, logPath string, optionalPaths []string, err error)

GetStoragePaths returns the computed storage paths based on configuration. If individual paths are specified, they are used; otherwise, paths are derived from basePath. All paths are validated using sanity checks. optionalPaths contains the paths for applicable optional storages (in registry order).

func (*Manager) GetTargetVersion added in v0.10.0 

func (m *Manager) GetTargetVersion() string

GetTargetVersion returns the configured target version for block node.

func (*Manager) InstallChart 

func (m *Manager) InstallChart(ctx context.Context, valuesFile string) (bool, error)

InstallChart installs the block node helm chart

func (*Manager) ResetStorage added in v0.8.0 

func (m *Manager) ResetStorage(ctx context.Context) error

ResetStorage clears all block node storage directories.

func (*Manager) RestartCiliumDaemonSetIfServicesChanged added in v0.18.0 

func (m *Manager) RestartCiliumDaemonSetIfServicesChanged(ctx context.Context) error

RestartCiliumDaemonSetIfServicesChanged compares the current block-node Service state with the snapshot recorded by SnapshotServices and restarts the Cilium agent DaemonSet only if anything changed. Most upgrades don't touch Services and shouldn't pay the ~30s Cilium-restart cost; topology-affecting upgrades must restart Cilium to refresh its eBPF reconciler (see issue #619).

func (*Manager) ScaleStatefulSet added in v0.8.0 

func (m *Manager) ScaleStatefulSet(ctx context.Context, replicas int32) error

ScaleStatefulSet scales the block node statefulset to the specified number of replicas

func (*Manager) SetupStorage 

func (m *Manager) SetupStorage(ctx context.Context) error

SetupStorage creates the required directories for block node storage

func (*Manager) SnapshotServices added in v0.18.0 

func (m *Manager) SnapshotServices(ctx context.Context) error

SnapshotServices records the current spec of every Service in the block-node namespace on the Manager. Call this before any operation that could mutate Services (e.g. helm upgrade) so that BlockNodeServicesChanged / the conditional Cilium restart can later decide whether anything actually changed.

Snapshots overwrite any previous snapshot on the same Manager.

func (*Manager) UninstallChart 

func (m *Manager) UninstallChart(ctx context.Context) error

UninstallChart uninstalls the block node helm chart

func (*Manager) UpgradeChart added in v0.5.0 

func (m *Manager) UpgradeChart(ctx context.Context, valuesFile string, reuseValues bool) error

UpgradeChart upgrades the block node helm chart. When reuseValues is true and no custom values file is provided, the existing release values are reused unchanged (following Helm CLI convention).

func (*Manager) VerifyExternalReachable added in v0.18.0 

func (m *Manager) VerifyExternalReachable(ctx context.Context) error

VerifyExternalReachable opens a TCP connection from the host running solo-provisioner to the block-node LoadBalancer Service's external endpoint and closes it immediately. No-ops when LoadBalancerEnabled is false (e.g. local profile, no MetalLB pool).

The probe converts the silent failure mode described in issue #619 — pod healthy, kubectl happy, traffic blackholed — into an immediate workflow error regardless of whether the cause is Cilium, MetalLB, the chart, or a firewall.

Traffic from this process to the LB IP traverses the same MetalLB-ARP + Cilium-DNAT path that any external client would hit, so a failure here is the same failure an outside caller would experience.

func (*Manager) WaitForPodReady 

func (m *Manager) WaitForPodReady(ctx context.Context) error

WaitForPodReady waits for the block node pod to be ready

func (*Manager) WaitForPodsTerminated added in v0.8.0 

func (m *Manager) WaitForPodsTerminated(ctx context.Context) error

WaitForPodsTerminated waits until all pods matching the block node label selector are terminated

type OptionalStorage added in v0.10.0 

type OptionalStorage struct {
	// Name is the human-readable name used in logs and template field names
	// (e.g., "verification", "plugins"). Must match the Helm persistence key.
	Name string

	// MinVersion is the minimum Block Node version that requires this storage.
	MinVersion string

	// PVName is the PersistentVolume resource name (e.g., "verification-storage-pv").
	PVName string

	// PVCName is the PersistentVolumeClaim resource name (e.g., "verification-storage-pvc").
	PVCName string

	// DirName is the subdirectory name under basePath (e.g., "verification").
	DirName string

	// GetPath returns the models.red path from the storage models.
	GetPath func(s *models.BlockNodeStorage) string

	// SetPath sets the path in the storage models.
	SetPath func(s *models.BlockNodeStorage, p string)

	// GetSize returns the models.red size from the storage models.
	GetSize func(s *models.BlockNodeStorage) string
}

OptionalStorage describes an optional storage volume that is conditionally required based on the target Block Node chart version.

func GetApplicableOptionalStorages added in v0.10.0 

func GetApplicableOptionalStorages(targetVersion string) []OptionalStorage

GetApplicableOptionalStorages returns the subset of optional storages that are required by the given target version.

func GetOptionalStorages added in v0.10.0 

func GetOptionalStorages() []OptionalStorage

GetOptionalStorages returns the full list of registered optional storages.

func (*OptionalStorage) RequiredByVersion added in v0.10.0 

func (o *OptionalStorage) RequiredByVersion(targetVersion string) bool

RequiredByVersion returns true if the given target version requires this optional storage.

type StorageMigration added in v0.10.0 

type StorageMigration struct {
	migration.VersionMigration
	// contains filtered or unexported fields
}

StorageMigration handles the breaking change pattern where a new storage PV/PVC is added to the Block Node StatefulSet. It is parameterized by the OptionalStorage descriptor, allowing a single implementation to serve all storage migrations.

Execute only creates the storage directory and PV/PVC — no Helm upgrade is performed. The single upgrade is appended as a final workflow step by BuildMigrationWorkflow.

func NewPluginsStorageMigration added in v0.10.0 

func NewPluginsStorageMigration() *StorageMigration

NewPluginsStorageMigration creates the plugins storage migration.

func NewStorageMigration added in v0.10.0 

func NewStorageMigration(optStorage OptionalStorage) *StorageMigration

NewStorageMigration creates a new storage migration for the given optional storage entry.

func NewVerificationStorageMigration added in v0.7.0 

func NewVerificationStorageMigration() *StorageMigration

NewVerificationStorageMigration creates the verification storage migration.

func (*StorageMigration) Execute added in v0.10.0 

func (m *StorageMigration) Execute(ctx context.Context, mctx *migration.Context) error

Execute creates the storage directory on the host and the PV/PVC in Kubernetes. It does NOT perform a Helm upgrade — that is handled once after all migrations complete, by the upgrade step appended in BuildMigrationWorkflow.

func (*StorageMigration) Rollback added in v0.10.0 

func (m *StorageMigration) Rollback(ctx context.Context, mctx *migration.Context) error

Rollback cleans up the PV/PVC created by this migration. Best-effort. No Helm downgrade is needed because the chart was never upgraded during Execute.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.