Add PrefetchConfig section

Add PrefetchConfig with enable flag and max_concurrency.

Fixes: awslabs#1832

Signed-off-by: ChengyuZhu6 <hudson@cyzhu.com>

Author: ChengyuZhu6

config/config.toml

@@ -7,7 +7,6 @@ max_concurrency = 100
 no_prometheus = false
 mount_timeout_sec = 30
 fuse_metrics_emit_wait_duration_sec = 60
-prefetch_max_concurrency = 0
 metrics_address = ''
 metrics_network = 'tcp'
 debug_address = ''
@@ -55,6 +54,10 @@ skip_check_snapshotter_supported = false
   type = 'soci'
   containerd_address = '/run/containerd/containerd.sock'
 
+[prefetch]
+  enable = false
+  max_concurrency = 0
+
 [pull_modes]
   [pull_modes.soci_v1]
     enable = false

config/config_test.go

@@ -76,10 +76,15 @@ func TestConfigDefaults(t *testing.T) {
 			expected: int64(defaultMaxConcurrency),
 			actual:   cfg.MaxConcurrency,
 		},
+		{
+			name:     "prefetch enabled",
+			expected: defaultPrefetchEnable,
+			actual:   cfg.PrefetchConfig.Enable,
+		},
 		{
 			name:     "prefetch max concurrency",
 			expected: int64(defaultPrefetchMaxConcurrency),
-			actual:   cfg.PrefetchMaxConcurrency,
+			actual:   cfg.PrefetchConfig.MaxConcurrency,
 		},
 		{
 			name:     "fuse attr timeout",

config/defaults.go

@@ -83,6 +83,9 @@ const (
 	// defaultMaxConcurrency is the maximum number of layers allowed to be pulled at once
 	defaultMaxConcurrency = 100
 
+	// defaultPrefetchEnable is the default value for whether prefetch is enabled.
+	defaultPrefetchEnable = false
+
 	// defaultPrefetchMaxConcurrency limits the maximum number of layers that can perform
 	// prefetch operations concurrently at the snapshotter level.
 	// 0 means no limit

config/fs.go

@@ -54,7 +54,6 @@ type FSConfig struct {
 	NoPrometheus                   bool   `toml:"no_prometheus"`
 	MountTimeoutSec                int64  `toml:"mount_timeout_sec"`
 	FuseMetricsEmitWaitDurationSec int64  `toml:"fuse_metrics_emit_wait_duration_sec"`
-	PrefetchMaxConcurrency         int64  `toml:"prefetch_max_concurrency"`
 
 	RetryableHTTPClientConfig `toml:"http"`
 	BlobConfig                `toml:"blob"`
@@ -66,6 +65,20 @@ type FSConfig struct {
 	BackgroundFetchConfig `toml:"background_fetch"`
 
 	ContentStoreConfig `toml:"content_store"`
+
+	PrefetchConfig `toml:"prefetch"`
+}
+
+// PrefetchConfig configures the prefetch feature for downloading specified files
+// before marking a layer download as complete.
+type PrefetchConfig struct {
+	// Enable controls whether the prefetch feature is enabled.
+	Enable bool `toml:"enable"`
+
+	// MaxConcurrency limits the maximum number of layers that can perform
+	// prefetch operations concurrently at the snapshotter level.
+	// 0 means no limit.
+	MaxConcurrency int64 `toml:"max_concurrency"`
 }
 
 // BlobConfig is config for layer blob management.
@@ -200,9 +213,9 @@ func parseFSConfig(cfg *Config) error {
 	if cfg.MaxConcurrency < 0 {
 		cfg.MaxConcurrency = 0
 	}
-	// If PrefetchMaxConcurrency is not set or negative, disable concurrency limits entirely.
-	if cfg.PrefetchMaxConcurrency < 0 {
-		cfg.PrefetchMaxConcurrency = defaultPrefetchMaxConcurrency
+	// If PrefetchConfig.MaxConcurrency is negative, disable concurrency limits entirely.
+	if cfg.PrefetchConfig.MaxConcurrency < 0 {
+		cfg.PrefetchConfig.MaxConcurrency = defaultPrefetchMaxConcurrency
 	}
 
 	// Parse nested fs configs

docs/config.md

@@ -23,7 +23,6 @@ This set of variables must be at the top of your TOML file due to not belonging
 - `resolve_result_entry` (int) — Max amount of entries allowed in the cache. Default: 30.
 - `debug` (bool) — Enables debugging for go-fuse in logs. This often emits sensitive data, so this should be false in production. Default: false.
 - `disable_verification` (bool) — Allows skipping TOC validation, which can give slight performance improvements if files have already been verified elsewhere. Default: false.
-- `prefetch_max_concurrency` (int) — Maximum number of layers that can perform prefetch operations concurrently at the snapshotter level. `0` means no limit. Default: 0.
 - `no_prometheus` (bool) — Toggle prometheus metrics. Default: false.
 - `mount_timeout_sec` (int) — Timeout for mount if a layer can't be resolved. Default: 30.
 - `fuse_metrics_emit_wait_duration_sec` (int) — The wait time before the snaphotter emits FUSE operation counts for an image. Default: 60.
@@ -82,6 +81,10 @@ This set of variables must be at the top of your TOML file due to not belonging
 - `type` (string) — Sets content store (e.g. "soci", "containerd"). Default: "soci".
 - `namespace` (string) — Default: "default".
 
+### [prefetch]
+- `enable` (bool) — Enables the prefetch feature for downloading specified files before marking a layer download as complete. Default: false.
+- `max_concurrency` (int) — Maximum number of layers that can perform prefetch operations concurrently at the snapshotter level. `0` means no limit. Default: 0.
+
 ## config/resolver.go
 
 ### [resolver]

docs/prefetch.md

@@ -198,31 +198,38 @@ Total spans to prefetch: 12
 
 ## Configuration
 
-### Concurrency Control
+### Enabling Prefetch
 
-The snapshotter implements bounded concurrency for prefetch operations to prevent overwhelming the system when multiple containers start simultaneously.
-
-#### Snapshotter Configuration
-
-Prefetch concurrency is controlled via the snapshotter configuration file (typically `/etc/soci-snapshotter-grpc/config.toml`):
+Prefetch must be explicitly enabled in the snapshotter configuration file:
 
 ```toml
+[prefetch]
+# Enable the prefetch feature
+enable = true
+
 # Maximum number of layers that can perform prefetch operations concurrently
 # at the snapshotter level
 # 0 = no limit (default)
 # Positive value = maximum concurrent prefetch operations
-prefetch_max_concurrency = 0
+max_concurrency = 0
 ```
 
-**Configuration options:**
-- `0` (default): No limit on concurrent prefetch operations
-- Positive integer (e.g., `10`): Maximum number of layers that can prefetch simultaneously
+### Configuration Options
 
-#### Example Configuration
+- `enable` (default: `false`): Controls whether the prefetch feature is enabled. When disabled, prefetch artifacts are ignored even if present.
+- `max_concurrency` (default: `0`): Limits concurrent prefetch operations across all layers.
+  - `0`: No limit on concurrent prefetch operations
+  - Positive integer (e.g., `10`): Maximum number of layers that can prefetch simultaneously
+
+### Example Configuration
 
 ```toml
 # /etc/soci-snapshotter-grpc/config.toml
 
+[prefetch]
+# Enable prefetch feature
+enable = true
+
 # Limit to 10 concurrent prefetch operations
-prefetch_max_concurrency = 10
+max_concurrency = 10
 ```

fs/layer/layer.go

@@ -173,8 +173,8 @@ func NewResolver(root string, cfg config.FSConfig, resolveHandlers map[string]re
 	}
 
 	var prefetchSem *semaphore.Weighted
-	if cfg.PrefetchMaxConcurrency > 0 {
-		prefetchSem = semaphore.NewWeighted(cfg.PrefetchMaxConcurrency)
+	if cfg.PrefetchConfig.Enable && cfg.PrefetchConfig.MaxConcurrency > 0 {
+		prefetchSem = semaphore.NewWeighted(cfg.PrefetchConfig.MaxConcurrency)
 	}
 
 	return &Resolver{
@@ -554,6 +554,11 @@ func (r *Resolver) executePrefetch(ctx context.Context, spanManager *spanmanager
 		return nil
 	}
 
+	if !r.config.PrefetchConfig.Enable {
+		log.G(ctx).Debug("Prefetch is disabled in config, skipping prefetch")
+		return nil
+	}
+
 	prefetchArtifact, err := r.loadPrefetchArtifact(ctx, prefetchDesc)
 	if err != nil {
 		if errors.Is(err, soci.ErrEmptyPrefetchArtifact) {

integration/create_test.go

@@ -357,7 +357,7 @@ func TestSociCreateWithPrefetchArtifacts(t *testing.T) {
 
 	sh.X("soci", "push", "--user", regConfig.creds(), mirrorImg.ref)
 
-	logMonitor := rebootContainerd(t, sh, getContainerdConfigToml(t, false), getSnapshotterConfigToml(t))
+	logMonitor := rebootContainerd(t, sh, getContainerdConfigToml(t, false), getSnapshotterConfigToml(t, withPrefetch()))
 
 	const prefetchMonitorKey = "prefetch-artifact-monitor"
 	prefetchLogCh := make(chan struct{}, 1)

integration/util_test.go

@@ -347,6 +347,12 @@ func withFuseWaitDuration(i int64) snapshotterConfigOpt {
 	}
 }
 
+func withPrefetch() snapshotterConfigOpt {
+	return func(c *config.Config) {
+		c.ServiceConfig.FSConfig.PrefetchConfig.Enable = true
+	}
+}
+
 func withPullModes(pullModes config.PullModes) snapshotterConfigOpt {
 	return func(c *config.Config) {
 		c.ServiceConfig.PullModes = pullModes