blocknode

package
v0.19.2 Latest Latest
Warning

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

 Go to latest Published: Jun 13, 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 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.

Adding a new BN version that changes plugin lists:

  1. Add a new blockNodePluginConfig entry to blockNodePluginHistory (in ascending MinVersion order).
  2. Populate Presets with ALL preset IDs (copy unchanged ones from the previous entry; update only the ones that changed).
  3. Populate AllPlugins with the full list for that version.
  4. Add tests in blocknode_plugins_test.go for the new version boundary.
  5. No changes to PluginListForPreset, PluginsForVersion, or any caller.
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 HelmOwnedServiceDeleteTimeout = 30 * time.Second

HelmOwnedServiceDeleteTimeout caps how long DeleteHelmOwnedServices waits for the API server to finalize deletion of the matched Services before failing the upgrade. Background propagation usually completes in <1s; the budget is generous enough to absorb a slow apiserver without masking a real stuck finalizer.

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 = blockNodePluginHistory[len(blockNodePluginHistory)-1].AllPlugins

AllBlockNodePlugins is the ordered list of available plugins for the current (latest) chart release. Use PluginsForVersion when the target chart version may be older.

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, chartVersion string) string

PluginListForPreset returns the canonical comma-separated plugin list for a named preset at the given chart version, or an empty string when the preset ID is not recognised. When chartVersion is empty, the current-default (latest) list is returned.

func PluginsForVersion added in v0.19.0 

func PluginsForVersion(chartVersion string) []string

PluginsForVersion returns the ordered list of available plugins for the given chart version, for use in the TUI custom multi-select. When chartVersion is empty, the current-default (latest) list is returned. Always returns an independent copy.

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, helm-owned Service teardown
  • values.go — Helm values file computation and YAML injection helpers
  • reachability.go — post-upgrade external-reachability probe

func NewManager 

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

NewManager creates a new block node manager

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) DeleteHelmOwnedServices added in v0.18.1 

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

DeleteHelmOwnedServices deletes every Service in the block-node namespace that belongs to the current Helm release (labels `app.kubernetes.io/managed-by=Helm` and `app.kubernetes.io/instance=<release>`) and waits for the API server to confirm their removal.

Run this immediately before `helm upgrade`. Helm's reconciliation phase will recreate the Services as part of the upgrade, which forces Cilium's eBPF service reconciler through a CREATE event rather than the `spec.type` transition UPDATE event it silently drops (see issue #619 / #644). Helm's 3-way merge handles the missing-from-cluster-but-in-last-release case transparently.

A no-match is a successful no-op: a prior failed upgrade may have already removed the Services, and the headless / LB Services may genuinely not exist on certain chart variants. The caller (the saga step) is responsible for the post-upgrade reachability probe that turns any remaining failure mode into a loud workflow error.

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) 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) 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.