Organize blobs on disk by epoch (#14023)

* organize blob directories by period and epoch

* changelog

* remove Indices and replace with Summary

* old PR feedback

* log to advise about the speed of blob migration

* rename level->layer (hoping term is more clear)

* assert path in tests for increased legibility

* lint

* lint

* remove test covering a newly impossible error

* improve feedback from flag validation failure

* Try to clean dangling dirs epoch->flat migration

* lint

* Preston feedback

* try all layouts and short-circuit if base not found

---------

Co-authored-by: Kasey Kirkham <kasey@users.noreply.github.com>

cmd/beacon-chain/main.go

@@ -145,6 +145,7 @@ var appFlags = []cli.Flag{
 	flags.JwtId,
 	storage.BlobStoragePathFlag,
 	storage.BlobRetentionEpochFlag,
+	storage.BlobStorageLayout,
 	bflags.EnableExperimentalBackfill,
 	bflags.BackfillBatchSize,
 	bflags.BackfillWorkerCount,

cmd/beacon-chain/storage/options.go

@@ -2,6 +2,7 @@ package storage
 
 import (
 	"path"
+	"strings"
 
 	"github.com/pkg/errors"
 	"github.com/prysmaticlabs/prysm/v5/beacon-chain/db/filesystem"
@@ -24,8 +25,30 @@ var (
 		Value:   uint64(params.BeaconConfig().MinEpochsForBlobsSidecarsRequest),
 		Aliases: []string{"extend-blob-retention-epoch"},
 	}
+	BlobStorageLayout = &cli.StringFlag{
+		Name:  "blob-storage-layout",
+		Usage: layoutFlagUsage(),
+		Value: filesystem.LayoutNameFlat,
+	}
 )
 
+func layoutOptions() string {
+	return "available options are: " + strings.Join(filesystem.LayoutNames, ", ") + "."
+}
+
+func layoutFlagUsage() string {
+	return "Dictates how to organize the blob directory structure on disk, " + layoutOptions()
+}
+
+func validateLayoutFlag(_ *cli.Context, v string) error {
+	for _, l := range filesystem.LayoutNames {
+		if v == l {
+			return nil
+		}
+	}
+	return errors.Errorf("invalid value '%s' for flag --%s, %s", v, BlobStorageLayout.Name, layoutOptions())
+}
+
 // BeaconNodeOptions sets configuration values on the node.BeaconNode value at node startup.
 // Note: we can't get the right context from cli.Context, because the beacon node setup code uses this context to
 // create a cancellable context. If we switch to using App.RunContext, we can set up this cancellation in the cmd
@@ -36,7 +59,9 @@ func BeaconNodeOptions(c *cli.Context) ([]node.Option, error) {
 		return nil, err
 	}
 	opts := []node.Option{node.WithBlobStorageOptions(
-		filesystem.WithBlobRetentionEpochs(e), filesystem.WithBasePath(blobStoragePath(c)),
+		filesystem.WithBlobRetentionEpochs(e),
+		filesystem.WithBasePath(blobStoragePath(c)),
+		filesystem.WithLayout(c.String(BlobStorageLayout.Name)), // This is validated in the Action func for BlobStorageLayout.
 	)}
 	return opts, nil
 }
@@ -69,3 +94,7 @@ func blobRetentionEpoch(cliCtx *cli.Context) (primitives.Epoch, error) {
 
 	return re, nil
 }
+
+func init() {
+	BlobStorageLayout.Action = validateLayoutFlag
+}

cmd/beacon-chain/usage.go

@@ -142,6 +142,7 @@ var appHelpFlagGroups = []flagGroup{
 			genesis.BeaconAPIURL,
 			storage.BlobStoragePathFlag,
 			storage.BlobRetentionEpochFlag,
+			storage.BlobStorageLayout,
 			backfill.EnableExperimentalBackfill,
 			backfill.BackfillWorkerCount,
 			backfill.BackfillBatchSize,