feat(ilm): relocate hot objects across server pools by GET frequency

Keep NVMe/HDD pool pairs useful without remote tiering: promote objects that
are read often, demote previously moved objects once they go idle, and leave
the feature off until operators set a two-pool topology.

Signed-off-by: mr javad seydi <seydi.birjand@gmail.com>

internal/config/ilm/help.go

@@ -22,10 +22,43 @@ import "github.com/minio/minio/internal/config"
 const (
 	transitionWorkers = "transition_workers"
 	expirationWorkers = "expiration_workers"
+
+	accessTiering          = "access_tiering"
+	accessPools            = "access_pools"
+	accessMaxSize          = "access_max_size"
+	accessPromoteWatermark = "access_promote_watermark"
+	accessBinWidth         = "access_bin_width"
+	accessBins             = "access_bins"
+	accessFlush            = "access_flush"
+	accessMinResidency     = "access_min_residency"
+	accessWorkers          = "access_workers"
+	accessMaxTracked       = "access_max_tracked"
+
 	// EnvILMTransitionWorkers env variable to configure number of transition workers
 	EnvILMTransitionWorkers = "MINIO_ILM_TRANSITION_WORKERS"
 	// EnvILMExpirationWorkers env variable to configure number of expiration workers
 	EnvILMExpirationWorkers = "MINIO_ILM_EXPIRATION_WORKERS"
+
+	// EnvILMAccessTiering env variable to enable access based tiering
+	EnvILMAccessTiering = "MINIO_ILM_ACCESS_TIERING"
+	// EnvILMAccessPools env variable listing pool indices hottest first
+	EnvILMAccessPools = "MINIO_ILM_ACCESS_POOLS"
+	// EnvILMAccessMaxSize env variable capping bytes held on the hottest pool
+	EnvILMAccessMaxSize = "MINIO_ILM_ACCESS_MAX_SIZE"
+	// EnvILMAccessPromoteWatermark env variable for the hottest pool fill limit
+	EnvILMAccessPromoteWatermark = "MINIO_ILM_ACCESS_PROMOTE_WATERMARK"
+	// EnvILMAccessBinWidth env variable for the access counter resolution
+	EnvILMAccessBinWidth = "MINIO_ILM_ACCESS_BIN_WIDTH"
+	// EnvILMAccessBins env variable for the number of access counter bins
+	EnvILMAccessBins = "MINIO_ILM_ACCESS_BINS"
+	// EnvILMAccessFlush env variable for the counter publish and sweep interval
+	EnvILMAccessFlush = "MINIO_ILM_ACCESS_FLUSH"
+	// EnvILMAccessMinResidency env variable for the anti-thrash floor
+	EnvILMAccessMinResidency = "MINIO_ILM_ACCESS_MIN_RESIDENCY"
+	// EnvILMAccessWorkers env variable to configure number of access tiering workers
+	EnvILMAccessWorkers = "MINIO_ILM_ACCESS_WORKERS"
+	// EnvILMAccessMaxTracked env variable capping tracked objects per node
+	EnvILMAccessMaxTracked = "MINIO_ILM_ACCESS_MAX_TRACKED"
 )
 
 var (
@@ -48,5 +81,65 @@ var (
 			Description: `set the number of expiration workers` + defaultHelpPostfix(expirationWorkers),
 			Optional:    true,
 		},
+		config.HelpKV{
+			Key:         accessTiering,
+			Type:        "on|off",
+			Description: `move objects between fast and slow server pools based on how often they are read` + defaultHelpPostfix(accessTiering),
+			Optional:    true,
+		},
+		config.HelpKV{
+			Key:         accessPools,
+			Type:        "string",
+			Description: `server pool indices for access tiering, hottest first, e.g. "0,1"` + defaultHelpPostfix(accessPools),
+			Optional:    true,
+		},
+		config.HelpKV{
+			Key:         accessMaxSize,
+			Type:        "string",
+			Description: `cap total bytes access tiering keeps on the fastest pool, e.g. "2TiB", 0 for unlimited` + defaultHelpPostfix(accessMaxSize),
+			Optional:    true,
+		},
+		config.HelpKV{
+			Key:         accessPromoteWatermark,
+			Type:        "number",
+			Description: `stop promoting once the fastest pool is this percent full` + defaultHelpPostfix(accessPromoteWatermark),
+			Optional:    true,
+		},
+		config.HelpKV{
+			Key:         accessBinWidth,
+			Type:        "duration",
+			Description: `resolution of the access counter` + defaultHelpPostfix(accessBinWidth),
+			Optional:    true,
+		},
+		config.HelpKV{
+			Key:         accessBins,
+			Type:        "number",
+			Description: `number of access counter bins; bins times bin width caps the rule Window` + defaultHelpPostfix(accessBins),
+			Optional:    true,
+		},
+		config.HelpKV{
+			Key:         accessFlush,
+			Type:        "duration",
+			Description: `how often access counters are published and a promotion sweep runs` + defaultHelpPostfix(accessFlush),
+			Optional:    true,
+		},
+		config.HelpKV{
+			Key:         accessMinResidency,
+			Type:        "duration",
+			Description: `minimum time an object stays on a pool after access tiering moved it` + defaultHelpPostfix(accessMinResidency),
+			Optional:    true,
+		},
+		config.HelpKV{
+			Key:         accessWorkers,
+			Type:        "number",
+			Description: `set the number of access tiering workers` + defaultHelpPostfix(accessWorkers),
+			Optional:    true,
+		},
+		config.HelpKV{
+			Key:         accessMaxTracked,
+			Type:        "number",
+			Description: `maximum number of objects each node keeps access counters for` + defaultHelpPostfix(accessMaxTracked),
+			Optional:    true,
+		},
 	}
 )

internal/config/ilm/ilm.go

@@ -18,12 +18,29 @@
 package ilm
 
 import (
+	"errors"
 	"strconv"
+	"strings"
+	"time"
 
+	"github.com/dustin/go-humanize"
 	"github.com/minio/minio/internal/config"
 	"github.com/minio/pkg/v3/env"
 )
 
+// Errors returned when the access tiering configuration is unusable.
+var (
+	ErrAccessPoolsInvalid     = errors.New("ilm access_pools must be a comma separated list of distinct pool indices, hottest first, e.g. \"0,1\"")
+	ErrAccessPoolsTooFew      = errors.New("ilm access_pools needs at least two pools to move objects between")
+	ErrAccessWatermarkInvalid = errors.New("ilm access_promote_watermark must be between 1 and 100")
+	ErrAccessBinsInvalid      = errors.New("ilm access_bins must be between 2 and 64")
+	ErrAccessBinWidthInvalid  = errors.New("ilm access_bin_width must be at least 1s")
+	ErrAccessFlushInvalid     = errors.New("ilm access_flush must be at least 1s")
+	ErrAccessResidencyInvalid = errors.New("ilm access_min_residency cannot be negative")
+	ErrAccessWorkersInvalid   = errors.New("ilm access_workers must be a positive integer")
+	ErrAccessTrackedInvalid   = errors.New("ilm access_max_tracked must be a positive integer")
+)
+
 // DefaultKVS default configuration values for ILM subsystem
 var DefaultKVS = config.KVS{
 	config.KV{
@@ -34,12 +51,124 @@ var DefaultKVS = config.KVS{
 		Key:   expirationWorkers,
 		Value: "100",
 	},
+	config.KV{
+		Key:   accessTiering,
+		Value: config.EnableOff,
+	},
+	config.KV{
+		Key:   accessPools,
+		Value: "",
+	},
+	config.KV{
+		Key:   accessMaxSize,
+		Value: "0",
+	},
+	config.KV{
+		Key:   accessPromoteWatermark,
+		Value: "85",
+	},
+	config.KV{
+		Key:   accessBinWidth,
+		Value: "1m",
+	},
+	config.KV{
+		Key:   accessBins,
+		Value: "12",
+	},
+	config.KV{
+		Key:   accessFlush,
+		Value: "1m",
+	},
+	config.KV{
+		Key:   accessMinResidency,
+		Value: "24h",
+	},
+	config.KV{
+		Key:   accessWorkers,
+		Value: "10",
+	},
+	config.KV{
+		Key:   accessMaxTracked,
+		Value: "1000000",
+	},
 }
 
 // Config represents the different configuration values for ILM subsystem
 type Config struct {
 	TransitionWorkers int
 	ExpirationWorkers int
+
+	// AccessTiering enables access-frequency driven relocation of objects
+	// between server pools. Off by default: it moves data.
+	AccessTiering bool
+	// AccessPools lists pool indices hottest first, e.g. []int{0, 1}.
+	AccessPools []int
+	// AccessMaxSize caps total bytes held on the hottest pool, 0 == unlimited.
+	AccessMaxSize uint64
+	// AccessPromoteWatermark stops promotion once the hottest pool is this
+	// percentage full.
+	AccessPromoteWatermark int
+	// AccessBinWidth and AccessBins size the rolling hit counter. Their
+	// product is the longest rule Window that can be evaluated.
+	AccessBinWidth time.Duration
+	AccessBins     int
+	// AccessFlush is how often each node publishes its counters and the
+	// leader merges them and runs a promotion sweep.
+	AccessFlush time.Duration
+	// AccessMinResidency is the minimum time an object stays put after a
+	// move, regardless of what the counters say.
+	AccessMinResidency time.Duration
+	AccessWorkers      int
+	// AccessMaxTracked caps how many objects each node keeps counters for.
+	AccessMaxTracked int
+}
+
+// HotPool returns the index of the hottest configured pool and whether access
+// tiering is usable at all.
+func (c Config) HotPool() (int, bool) {
+	if !c.AccessTiering || len(c.AccessPools) < 2 {
+		return -1, false
+	}
+	return c.AccessPools[0], true
+}
+
+// ColdPool returns the index of the coldest configured pool, i.e. where
+// demoted objects go.
+func (c Config) ColdPool() (int, bool) {
+	if !c.AccessTiering || len(c.AccessPools) < 2 {
+		return -1, false
+	}
+	return c.AccessPools[len(c.AccessPools)-1], true
+}
+
+// HistoryWindow is the longest window the rolling counter can answer for.
+func (c Config) HistoryWindow() time.Duration {
+	return time.Duration(c.AccessBins) * c.AccessBinWidth
+}
+
+// parseAccessPools parses "0,1" into []int{0, 1}, rejecting duplicates and
+// negative indices. An empty string yields no pools, which disables the
+// feature rather than erroring - operators enable the switch before they
+// configure the topology.
+func parseAccessPools(s string) ([]int, error) {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return nil, nil
+	}
+	var pools []int
+	seen := make(map[int]struct{})
+	for _, f := range strings.Split(s, ",") {
+		idx, err := strconv.Atoi(strings.TrimSpace(f))
+		if err != nil || idx < 0 {
+			return nil, ErrAccessPoolsInvalid
+		}
+		if _, dup := seen[idx]; dup {
+			return nil, ErrAccessPoolsInvalid
+		}
+		seen[idx] = struct{}{}
+		pools = append(pools, idx)
+	}
+	return pools, nil
 }
 
 // LookupConfig - lookup ilm config and override with valid environment settings if any.
@@ -65,5 +194,79 @@ func LookupConfig(kvs config.KVS) (cfg Config, err error) {
 
 	cfg.TransitionWorkers = tw
 	cfg.ExpirationWorkers = ew
+
+	if err := cfg.lookupAccess(kvs); err != nil {
+		return cfg, err
+	}
 	return cfg, nil
 }
+
+func (c *Config) lookupAccess(kvs config.KVS) (err error) {
+	c.AccessTiering, err = config.ParseBool(env.Get(EnvILMAccessTiering, kvs.GetWithDefault(accessTiering, DefaultKVS)))
+	if err != nil {
+		return err
+	}
+
+	if c.AccessPools, err = parseAccessPools(env.Get(EnvILMAccessPools, kvs.GetWithDefault(accessPools, DefaultKVS))); err != nil {
+		return err
+	}
+	// Enabling the feature without a usable topology is a configuration
+	// error worth surfacing at set time rather than silently doing nothing.
+	if c.AccessTiering && len(c.AccessPools) < 2 {
+		return ErrAccessPoolsTooFew
+	}
+
+	maxSize := env.Get(EnvILMAccessMaxSize, kvs.GetWithDefault(accessMaxSize, DefaultKVS))
+	if maxSize == "" || maxSize == "0" {
+		c.AccessMaxSize = 0
+	} else if c.AccessMaxSize, err = humanize.ParseBytes(maxSize); err != nil {
+		return err
+	}
+
+	if c.AccessPromoteWatermark, err = strconv.Atoi(env.Get(EnvILMAccessPromoteWatermark, kvs.GetWithDefault(accessPromoteWatermark, DefaultKVS))); err != nil {
+		return err
+	}
+	if c.AccessPromoteWatermark < 1 || c.AccessPromoteWatermark > 100 {
+		return ErrAccessWatermarkInvalid
+	}
+
+	if c.AccessBinWidth, err = time.ParseDuration(env.Get(EnvILMAccessBinWidth, kvs.GetWithDefault(accessBinWidth, DefaultKVS))); err != nil {
+		return err
+	}
+	if c.AccessBinWidth < time.Second {
+		return ErrAccessBinWidthInvalid
+	}
+	if c.AccessBins, err = strconv.Atoi(env.Get(EnvILMAccessBins, kvs.GetWithDefault(accessBins, DefaultKVS))); err != nil {
+		return err
+	}
+	if c.AccessBins < 2 || c.AccessBins > 64 {
+		return ErrAccessBinsInvalid
+	}
+
+	if c.AccessFlush, err = time.ParseDuration(env.Get(EnvILMAccessFlush, kvs.GetWithDefault(accessFlush, DefaultKVS))); err != nil {
+		return err
+	}
+	if c.AccessFlush < time.Second {
+		return ErrAccessFlushInvalid
+	}
+	if c.AccessMinResidency, err = time.ParseDuration(env.Get(EnvILMAccessMinResidency, kvs.GetWithDefault(accessMinResidency, DefaultKVS))); err != nil {
+		return err
+	}
+	if c.AccessMinResidency < 0 {
+		return ErrAccessResidencyInvalid
+	}
+
+	if c.AccessWorkers, err = strconv.Atoi(env.Get(EnvILMAccessWorkers, kvs.GetWithDefault(accessWorkers, DefaultKVS))); err != nil {
+		return err
+	}
+	if c.AccessWorkers < 1 {
+		return ErrAccessWorkersInvalid
+	}
+	if c.AccessMaxTracked, err = strconv.Atoi(env.Get(EnvILMAccessMaxTracked, kvs.GetWithDefault(accessMaxTracked, DefaultKVS))); err != nil {
+		return err
+	}
+	if c.AccessMaxTracked < 1 {
+		return ErrAccessTrackedInvalid
+	}
+	return nil
+}

internal/config/ilm/ilm_test.go

@@ -0,0 +1,109 @@
+// Copyright (c) 2015-2026 MinIO, Inc.
+
+package ilm
+
+import (
+	"errors"
+	"reflect"
+	"testing"
+	"time"
+
+	"github.com/minio/minio/internal/config"
+)
+
+func clearAccessEnv(t *testing.T) {
+	t.Helper()
+	for _, name := range []string{
+		EnvILMAccessTiering, EnvILMAccessPools, EnvILMAccessMaxSize,
+		EnvILMAccessPromoteWatermark, EnvILMAccessBinWidth, EnvILMAccessBins,
+		EnvILMAccessFlush, EnvILMAccessMinResidency, EnvILMAccessWorkers,
+		EnvILMAccessMaxTracked,
+	} {
+		// The env helper treats an empty value as unset. t.Setenv restores the
+		// caller's exact value automatically when the test finishes.
+		t.Setenv(name, "")
+	}
+}
+
+func TestLookupAccessDefaults(t *testing.T) {
+	clearAccessEnv(t)
+	cfg, err := LookupConfig(DefaultKVS.Clone())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cfg.AccessTiering {
+		t.Fatal("access tiering must default off")
+	}
+	if cfg.AccessBinWidth != time.Minute || cfg.AccessBins != 12 || cfg.AccessFlush != time.Minute {
+		t.Fatalf("unexpected counter defaults: width=%s bins=%d flush=%s", cfg.AccessBinWidth, cfg.AccessBins, cfg.AccessFlush)
+	}
+	if cfg.AccessWorkers != 10 || cfg.AccessMaxTracked != 1000000 {
+		t.Fatalf("unexpected worker/map defaults: %d/%d", cfg.AccessWorkers, cfg.AccessMaxTracked)
+	}
+}
+
+func TestLookupAccessEnabled(t *testing.T) {
+	clearAccessEnv(t)
+	kvs := DefaultKVS.Clone()
+	kvs.Set(accessTiering, config.EnableOn)
+	kvs.Set(accessPools, "2, 0, 1")
+	kvs.Set(accessMaxSize, "2GiB")
+	kvs.Set(accessPromoteWatermark, "90")
+	kvs.Set(accessBinWidth, "30s")
+	kvs.Set(accessBins, "20")
+	kvs.Set(accessFlush, "15s")
+	kvs.Set(accessMinResidency, "2h")
+	kvs.Set(accessWorkers, "7")
+	kvs.Set(accessMaxTracked, "1234")
+
+	cfg, err := LookupConfig(kvs)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !cfg.AccessTiering || !reflect.DeepEqual(cfg.AccessPools, []int{2, 0, 1}) {
+		t.Fatalf("unexpected topology: enabled=%v pools=%v", cfg.AccessTiering, cfg.AccessPools)
+	}
+	if cfg.AccessMaxSize != 2<<30 || cfg.HistoryWindow() != 10*time.Minute {
+		t.Fatalf("unexpected size/history: %d/%s", cfg.AccessMaxSize, cfg.HistoryWindow())
+	}
+	if hot, ok := cfg.HotPool(); !ok || hot != 2 {
+		t.Fatalf("HotPool = %d/%v", hot, ok)
+	}
+	if cold, ok := cfg.ColdPool(); !ok || cold != 1 {
+		t.Fatalf("ColdPool = %d/%v", cold, ok)
+	}
+}
+
+func TestLookupAccessRejectsInvalidValues(t *testing.T) {
+	clearAccessEnv(t)
+	tests := []struct {
+		key, value string
+		want       error
+	}{
+		{accessPools, "0,0", ErrAccessPoolsInvalid},
+		{accessPromoteWatermark, "0", ErrAccessWatermarkInvalid},
+		{accessBinWidth, "500ms", ErrAccessBinWidthInvalid},
+		{accessBins, "1", ErrAccessBinsInvalid},
+		{accessFlush, "0s", ErrAccessFlushInvalid},
+		{accessMinResidency, "-1s", ErrAccessResidencyInvalid},
+		{accessWorkers, "0", ErrAccessWorkersInvalid},
+		{accessMaxTracked, "0", ErrAccessTrackedInvalid},
+	}
+	for _, tc := range tests {
+		t.Run(tc.key, func(t *testing.T) {
+			kvs := DefaultKVS.Clone()
+			kvs.Set(tc.key, tc.value)
+			_, err := LookupConfig(kvs)
+			if !errors.Is(err, tc.want) {
+				t.Fatalf("error = %v, want %v", err, tc.want)
+			}
+		})
+	}
+
+	kvs := DefaultKVS.Clone()
+	kvs.Set(accessTiering, config.EnableOn)
+	kvs.Set(accessPools, "0")
+	if _, err := LookupConfig(kvs); !errors.Is(err, ErrAccessPoolsTooFew) {
+		t.Fatalf("error = %v, want %v", err, ErrAccessPoolsTooFew)
+	}
+}