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/bucket/lifecycle/access-transition.go

@@ -0,0 +1,129 @@
+// Copyright (c) 2015-2026 MinIO, Inc.
+//
+// This file is part of MinIO Object Storage stack
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+package lifecycle
+
+import (
+	"encoding/xml"
+	"time"
+)
+
+var (
+	errAccessInvalidDuration  = Errorf("Window and DemoteAfterIdle must be valid Go durations, e.g. 10m or 24h")
+	errAccessInvalidWindow    = Errorf("Window must be a positive duration with AccessTransition")
+	errAccessInvalidPromote   = Errorf("PromoteAfterAccesses must be a positive integer with AccessTransition")
+	errAccessInvalidDemote    = Errorf("DemoteAfterAccesses must be smaller than PromoteAfterAccesses and 0 or greater")
+	errAccessInvalidIdle      = Errorf("DemoteAfterIdle must be a positive duration no shorter than Window")
+	errAccessInvalidQuotaSize = Errorf("AccessTierQuota must be a valid size, e.g. 500GiB")
+)
+
+// Duration is a time.Duration that marshals to and from an XML element
+// holding a Go duration string, e.g. <Window>10m</Window>.
+type Duration time.Duration
+
+// UnmarshalXML parses a duration string such as "10m" or "24h".
+func (d *Duration) UnmarshalXML(dec *xml.Decoder, start xml.StartElement) error {
+	var s string
+	if err := dec.DecodeElement(&s, &start); err != nil {
+		return err
+	}
+	dur, err := time.ParseDuration(s)
+	if err != nil {
+		return errAccessInvalidDuration
+	}
+	*d = Duration(dur)
+	return nil
+}
+
+// MarshalXML encodes a non-zero duration, and nothing otherwise.
+func (d Duration) MarshalXML(enc *xml.Encoder, start xml.StartElement) error {
+	if d == 0 {
+		return nil
+	}
+	return enc.EncodeElement(time.Duration(d).String(), start)
+}
+
+// D returns the value as a time.Duration.
+func (d Duration) D() time.Duration {
+	return time.Duration(d)
+}
+
+// AccessTransition is a Silo extension to the S3 lifecycle rule. It relocates
+// an object between server pools based on how often it is read, rather than on
+// its age: an object read at least PromoteAfterAccesses times within Window
+// moves to the fastest configured pool, and moves back once it has been idle
+// for DemoteAfterIdle and its windowed hit count has fallen to
+// DemoteAfterAccesses or below.
+//
+// The gap between the two thresholds, together with DemoteAfterIdle and the
+// server-side access_min_residency, is what keeps an object from oscillating
+// between pools.
+type AccessTransition struct {
+	XMLName              xml.Name `xml:"AccessTransition"`
+	Window               Duration `xml:"Window,omitempty"`
+	PromoteAfterAccesses int      `xml:"PromoteAfterAccesses,omitempty"`
+	DemoteAfterAccesses  int      `xml:"DemoteAfterAccesses,omitempty"`
+	DemoteAfterIdle      Duration `xml:"DemoteAfterIdle,omitempty"`
+
+	set bool
+}
+
+// IsNull returns true if no usable access transition is configured.
+func (a AccessTransition) IsNull() bool {
+	return !a.set || a.PromoteAfterAccesses <= 0
+}
+
+// MarshalXML encodes an AccessTransition element, and nothing if unset.
+func (a AccessTransition) MarshalXML(enc *xml.Encoder, start xml.StartElement) error {
+	if !a.set {
+		return nil
+	}
+	type accessTransitionWrapper AccessTransition
+	return enc.EncodeElement(accessTransitionWrapper(a), start)
+}
+
+// UnmarshalXML decodes an AccessTransition element.
+func (a *AccessTransition) UnmarshalXML(dec *xml.Decoder, start xml.StartElement) error {
+	type accessTransitionWrapper AccessTransition
+	var atw accessTransitionWrapper
+	if err := dec.DecodeElement(&atw, &start); err != nil {
+		return err
+	}
+	*a = AccessTransition(atw)
+	a.set = true
+	return nil
+}
+
+// Validate checks the AccessTransition element.
+func (a AccessTransition) Validate() error {
+	if !a.set {
+		return nil
+	}
+	if a.Window <= 0 {
+		return errAccessInvalidWindow
+	}
+	if a.PromoteAfterAccesses <= 0 {
+		return errAccessInvalidPromote
+	}
+	if a.DemoteAfterAccesses < 0 || a.DemoteAfterAccesses >= a.PromoteAfterAccesses {
+		return errAccessInvalidDemote
+	}
+	if a.DemoteAfterIdle <= 0 || a.DemoteAfterIdle < a.Window {
+		return errAccessInvalidIdle
+	}
+	return nil
+}

internal/bucket/lifecycle/access-transition_test.go

@@ -0,0 +1,219 @@
+// Copyright (c) 2015-2026 MinIO, Inc.
+//
+// This file is part of MinIO Object Storage stack
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+package lifecycle
+
+import (
+	"bytes"
+	"encoding/xml"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/minio/minio/internal/bucket/object/lock"
+)
+
+const accessTieringXML = `<LifecycleConfiguration>
+  <AccessTierQuota>500GiB</AccessTierQuota>
+  <Rule>
+    <ID>hot-logs</ID>
+    <Status>Enabled</Status>
+    <Filter><And><Prefix>logs/</Prefix><ObjectSizeGreaterThan>65536</ObjectSizeGreaterThan></And></Filter>
+    <AccessTransition>
+      <Window>10m</Window>
+      <PromoteAfterAccesses>100</PromoteAfterAccesses>
+      <DemoteAfterAccesses>5</DemoteAfterAccesses>
+      <DemoteAfterIdle>24h</DemoteAfterIdle>
+    </AccessTransition>
+  </Rule>
+</LifecycleConfiguration>`
+
+func TestAccessTransitionParse(t *testing.T) {
+	lc, err := ParseLifecycleConfig(strings.NewReader(accessTieringXML))
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	if err := lc.Validate(lock.Retention{}); err != nil {
+		t.Fatalf("validate: %v", err)
+	}
+	if got := lc.AccessQuotaBytes(); got != 500*1024*1024*1024 {
+		t.Fatalf("quota = %d, want %d", got, 500*1024*1024*1024)
+	}
+	if !lc.HasAccessTransition() {
+		t.Fatal("HasAccessTransition = false, want true")
+	}
+	at := lc.Rules[0].AccessTransition
+	if at.Window.D() != 10*time.Minute {
+		t.Fatalf("window = %v, want 10m", at.Window.D())
+	}
+	if at.DemoteAfterIdle.D() != 24*time.Hour {
+		t.Fatalf("idle = %v, want 24h", at.DemoteAfterIdle.D())
+	}
+	if at.PromoteAfterAccesses != 100 || at.DemoteAfterAccesses != 5 {
+		t.Fatalf("thresholds = %d/%d, want 100/5", at.PromoteAfterAccesses, at.DemoteAfterAccesses)
+	}
+}
+
+// A round trip through Marshal must preserve both the rule element and the
+// bucket-wide quota, since PutBucketLifecycle stores whatever we re-encode.
+func TestAccessTransitionRoundTrip(t *testing.T) {
+	lc, err := ParseLifecycleConfig(strings.NewReader(accessTieringXML))
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	buf, err := xml.Marshal(lc)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	if !bytes.Contains(buf, []byte("<AccessTierQuota>500GiB</AccessTierQuota>")) {
+		t.Fatalf("quota lost in round trip: %s", buf)
+	}
+	got, err := ParseLifecycleConfig(bytes.NewReader(buf))
+	if err != nil {
+		t.Fatalf("reparse: %v", err)
+	}
+	if got.AccessQuotaBytes() != lc.AccessQuotaBytes() {
+		t.Fatalf("quota %d != %d", got.AccessQuotaBytes(), lc.AccessQuotaBytes())
+	}
+	if got.Rules[0].AccessTransition != lc.Rules[0].AccessTransition {
+		t.Fatalf("rule %+v != %+v", got.Rules[0].AccessTransition, lc.Rules[0].AccessTransition)
+	}
+}
+
+// A rule with no AccessTransition must not emit an empty element - otherwise
+// every existing lifecycle config would change shape on rewrite.
+func TestAccessTransitionUnsetNotMarshalled(t *testing.T) {
+	lc, err := ParseLifecycleConfig(strings.NewReader(`<LifecycleConfiguration><Rule>
+		<ID>old</ID><Status>Enabled</Status><Filter><Prefix>a/</Prefix></Filter>
+		<Expiration><Days>3</Days></Expiration></Rule></LifecycleConfiguration>`))
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	buf, err := xml.Marshal(lc)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	if bytes.Contains(buf, []byte("AccessTransition")) || bytes.Contains(buf, []byte("AccessTierQuota")) {
+		t.Fatalf("unset elements emitted: %s", buf)
+	}
+	if lc.HasAccessTransition() {
+		t.Fatal("HasAccessTransition = true for a plain expiry rule")
+	}
+}
+
+func TestAccessTransitionValidate(t *testing.T) {
+	tests := []struct {
+		name string
+		at   AccessTransition
+		err  error
+	}{
+		{"ok", AccessTransition{Window: Duration(10 * time.Minute), PromoteAfterAccesses: 100, DemoteAfterAccesses: 5, DemoteAfterIdle: Duration(time.Hour), set: true}, nil},
+		{"unset", AccessTransition{}, nil},
+		{"zero window", AccessTransition{PromoteAfterAccesses: 100, DemoteAfterIdle: Duration(time.Hour), set: true}, errAccessInvalidWindow},
+		{"zero promote", AccessTransition{Window: Duration(time.Minute), DemoteAfterIdle: Duration(time.Hour), set: true}, errAccessInvalidPromote},
+		{"demote >= promote", AccessTransition{Window: Duration(time.Minute), PromoteAfterAccesses: 5, DemoteAfterAccesses: 5, DemoteAfterIdle: Duration(time.Hour), set: true}, errAccessInvalidDemote},
+		{"negative demote", AccessTransition{Window: Duration(time.Minute), PromoteAfterAccesses: 5, DemoteAfterAccesses: -1, DemoteAfterIdle: Duration(time.Hour), set: true}, errAccessInvalidDemote},
+		{"idle shorter than window", AccessTransition{Window: Duration(time.Hour), PromoteAfterAccesses: 5, DemoteAfterIdle: Duration(time.Minute), set: true}, errAccessInvalidIdle},
+		{"zero idle", AccessTransition{Window: Duration(time.Minute), PromoteAfterAccesses: 5, set: true}, errAccessInvalidIdle},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if err := tc.at.Validate(); err != tc.err {
+				t.Fatalf("err = %v, want %v", err, tc.err)
+			}
+		})
+	}
+}
+
+func TestAccessTierQuotaInvalid(t *testing.T) {
+	lc, err := ParseLifecycleConfig(strings.NewReader(`<LifecycleConfiguration>
+		<AccessTierQuota>not-a-size</AccessTierQuota>
+		<Rule><ID>r</ID><Status>Enabled</Status><Expiration><Days>3</Days></Expiration></Rule>
+		</LifecycleConfiguration>`))
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	if err := lc.Validate(lock.Retention{}); err != errAccessInvalidQuotaSize {
+		t.Fatalf("err = %v, want %v", err, errAccessInvalidQuotaSize)
+	}
+	// An invalid quota that somehow reached the evaluator means "unlimited",
+	// never "zero bytes allowed".
+	if got := lc.AccessQuotaBytes(); got != 0 {
+		t.Fatalf("quota = %d, want 0 (unlimited)", got)
+	}
+}
+
+func TestAccessTransitionBadDuration(t *testing.T) {
+	_, err := ParseLifecycleConfig(strings.NewReader(`<LifecycleConfiguration><Rule>
+		<ID>r</ID><Status>Enabled</Status>
+		<AccessTransition><Window>ten minutes</Window><PromoteAfterAccesses>1</PromoteAfterAccesses></AccessTransition>
+		</Rule></LifecycleConfiguration>`))
+	if err == nil {
+		t.Fatal("expected a parse error for a malformed duration")
+	}
+}
+
+// AccessRule must reuse the standard rule filtering: prefix, tags, size and
+// Status all have to be honored.
+func TestAccessRuleFiltering(t *testing.T) {
+	lc, err := ParseLifecycleConfig(strings.NewReader(accessTieringXML))
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	tests := []struct {
+		name string
+		obj  ObjectOpts
+		want bool
+	}{
+		{"match", ObjectOpts{Name: "logs/a.log", Size: 1 << 20, IsLatest: true}, true},
+		{"wrong prefix", ObjectOpts{Name: "data/a.log", Size: 1 << 20, IsLatest: true}, false},
+		{"too small", ObjectOpts{Name: "logs/a.log", Size: 1024, IsLatest: true}, false},
+		{"no name", ObjectOpts{Size: 1 << 20}, false},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			_, id, ok := lc.AccessRule(tc.obj)
+			if ok != tc.want {
+				t.Fatalf("ok = %v, want %v", ok, tc.want)
+			}
+			if ok && id != "hot-logs" {
+				t.Fatalf("ruleID = %q, want hot-logs", id)
+			}
+		})
+	}
+
+	lc.Rules[0].Status = Disabled
+	if _, _, ok := lc.AccessRule(ObjectOpts{Name: "logs/a.log", Size: 1 << 20, IsLatest: true}); ok {
+		t.Fatal("disabled rule still matched")
+	}
+	if lc.HasAccessTransition() {
+		t.Fatal("HasAccessTransition = true with only a disabled rule")
+	}
+}
+
+func TestAccessTransitionCountsAsActiveRule(t *testing.T) {
+	lc, err := ParseLifecycleConfig(strings.NewReader(accessTieringXML))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !lc.HasActiveRules("logs/2026") {
+		t.Fatal("access-only lifecycle rule was not active for its prefix")
+	}
+	if lc.HasActiveRules("data/") {
+		t.Fatal("access rule was active outside its prefix")
+	}
+}

internal/bucket/lifecycle/lifecycle.go

@@ -26,6 +26,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/dustin/go-humanize"
 	"github.com/google/uuid"
 	"github.com/minio/minio/internal/bucket/object/lock"
 	"github.com/minio/minio/internal/bucket/replication"
@@ -101,11 +102,56 @@ func (a Action) Delete() bool {
 
 // Lifecycle - Configuration for bucket lifecycle.
 type Lifecycle struct {
-	XMLName         xml.Name   `xml:"LifecycleConfiguration"`
+	XMLName xml.Name `xml:"LifecycleConfiguration"`
+	// AccessTierQuota caps how many bytes of this bucket access-based ILM
+	// may keep on the fastest pool, e.g. "500GiB". Empty means unlimited.
+	// It is bucket-wide rather than per-rule so it cannot be declared
+	// inconsistently by two rules matching the same object.
+	AccessTierQuota string     `xml:"AccessTierQuota,omitempty"`
 	Rules           []Rule     `xml:"Rule"`
 	ExpiryUpdatedAt *time.Time `xml:"ExpiryUpdatedAt,omitempty"`
 }
 
+// HasAccessTransition returns 'true' if any enabled rule carries a usable
+// AccessTransition. Used as a cheap per-bucket gate before consulting the
+// access tracker.
+func (lc Lifecycle) HasAccessTransition() bool {
+	for _, rule := range lc.Rules {
+		if rule.Status == Disabled {
+			continue
+		}
+		if !rule.AccessTransition.IsNull() {
+			return true
+		}
+	}
+	return false
+}
+
+// AccessRule returns the first enabled rule matching obj that carries a usable
+// AccessTransition, along with its rule ID.
+func (lc Lifecycle) AccessRule(obj ObjectOpts) (AccessTransition, string, bool) {
+	for _, rule := range lc.FilterRules(obj) {
+		if !rule.AccessTransition.IsNull() {
+			return rule.AccessTransition, rule.ID, true
+		}
+	}
+	return AccessTransition{}, "", false
+}
+
+// AccessQuotaBytes returns the bucket-wide fast-pool byte cap, 0 meaning
+// unlimited. The value is validated at PUT time, so a parse failure here is
+// treated as unlimited rather than as an error.
+func (lc Lifecycle) AccessQuotaBytes() uint64 {
+	if lc.AccessTierQuota == "" {
+		return 0
+	}
+	sz, err := humanize.ParseBytes(lc.AccessTierQuota)
+	if err != nil {
+		return 0
+	}
+	return sz
+}
+
 // HasTransition returns 'true' if lifecycle document has Transition enabled.
 func (lc Lifecycle) HasTransition() bool {
 	for _, rule := range lc.Rules {
@@ -158,6 +204,12 @@ func (lc *Lifecycle) UnmarshalXML(d *xml.Decoder, start xml.StartElement) (err e
 					return err
 				}
 				lc.ExpiryUpdatedAt = &t
+			case "AccessTierQuota":
+				var q string
+				if err = d.DecodeElement(&q, &se); err != nil {
+					return err
+				}
+				lc.AccessTierQuota = q
 			default:
 				return xml.UnmarshalError(fmt.Sprintf("expected element type <Rule> but have <%s>", se.Name.Local))
 			}
@@ -208,6 +260,9 @@ func (lc Lifecycle) HasActiveRules(prefix string) bool {
 		if !rule.Transition.IsNull() { // this allows for Transition.Days to be zero.
 			return true
 		}
+		if !rule.AccessTransition.IsNull() {
+			return true
+		}
 	}
 	return false
 }
@@ -248,6 +303,12 @@ func (lc Lifecycle) Validate(lr lock.Retention) error {
 		return errLifecycleNoRule
 	}
 
+	if lc.AccessTierQuota != "" {
+		if _, err := humanize.ParseBytes(lc.AccessTierQuota); err != nil {
+			return errAccessInvalidQuotaSize
+		}
+	}
+
 	// Validate all the rules in the lifecycle config
 	for _, r := range lc.Rules {
 		if err := r.Validate(); err != nil {

internal/bucket/lifecycle/rule.go

@@ -41,6 +41,7 @@ type Rule struct {
 	Expiration          Expiration          `xml:"Expiration,omitempty"`
 	Transition          Transition          `xml:"Transition,omitempty"`
 	DelMarkerExpiration DelMarkerExpiration `xml:"DelMarkerExpiration,omitempty"`
+	AccessTransition    AccessTransition    `xml:"AccessTransition,omitempty"`
 	// FIXME: add a type to catch unsupported AbortIncompleteMultipartUpload AbortIncompleteMultipartUpload `xml:"AbortIncompleteMultipartUpload,omitempty"`
 	NoncurrentVersionExpiration NoncurrentVersionExpiration `xml:"NoncurrentVersionExpiration,omitempty"`
 	NoncurrentVersionTransition NoncurrentVersionTransition `xml:"NoncurrentVersionTransition,omitempty"`
@@ -171,10 +172,13 @@ func (r Rule) Validate() error {
 	if err := r.validateNoncurrentTransition(); err != nil {
 		return err
 	}
+	if err := r.AccessTransition.Validate(); err != nil {
+		return err
+	}
 	if (!r.Filter.Tag.IsEmpty() || len(r.Filter.And.Tags) != 0) && !r.DelMarkerExpiration.Empty() {
 		return errInvalidRuleDelMarkerExpiration
 	}
-	if !r.Expiration.set && !r.Transition.set && !r.NoncurrentVersionExpiration.set && !r.NoncurrentVersionTransition.set && r.DelMarkerExpiration.Empty() {
+	if !r.Expiration.set && !r.Transition.set && !r.NoncurrentVersionExpiration.set && !r.NoncurrentVersionTransition.set && r.DelMarkerExpiration.Empty() && !r.AccessTransition.set {
 		return errXMLNotWellFormed
 	}
 	return nil