feat: Implement S3 Object Lock retention ceiling for tenants and ensure default value (#155)

Author: yehlo

.github/README.md

@@ -207,8 +207,36 @@ spec:
   credentialsSecret:
     name: storagegrid-credentials
     namespace: storagegrid-operator-system
+
+  # Grid-wide S3 Object Lock retention ceiling, in days, for tenants that do not
+  # set spec.s3ObjectLock.maxRetentionInDays themselves. Defaults to 365.
+  # Must be between 1 and 36500 (100 years). See "S3 Object Lock retention" below.
+  defaultMaxRetentionInDays: 365
 ```
 
+#### S3 Object Lock retention
+
+StorageGrid requires every tenant to carry an S3 Object Lock retention ceiling once Object Lock
+is enabled grid-wide, and **silently applies a 100-year ceiling to any tenant created without
+one**. The operator therefore always writes the field explicitly, resolving it as:
+
+| Setting | Effect |
+| --- | --- |
+| `S3Tenant.spec.s3ObjectLock.maxRetentionInDays` > 0 | That value is used |
+| `S3Tenant.spec.s3ObjectLock.maxRetentionInDays` unset or `0` | Inherits `StorageGrid.spec.defaultMaxRetentionInDays` |
+| Neither set | Falls back to 365 days |
+
+The ceiling is independent of `s3ObjectLock.mode`. Mode governs whether an `S3Bucket` may enable
+Object Lock at all, but the retention ceiling also caps Governance-mode retention that a tenant
+can request directly over the S3 API, where the operator's bucket-level checks do not apply.
+
+The operator owns this field: it is reconciled on every loop, so a value changed by hand in the
+Tenant Manager is reset to what the spec requires. It also expresses the ceiling in days only,
+clearing StorageGrid's `maxRetentionYears` whenever it writes.
+
+An `S3Bucket`'s `s3ObjectLock.retentionInDays` may never exceed its tenant's effective ceiling;
+the admission webhook rejects the bucket otherwise.
+
 ### 2. Define an S3TenantClass
 
 ```yaml
@@ -250,6 +278,16 @@ spec:
     project: "my-project"
     environment: "production"
     owner: "team-alpha"
+
+  # Optional: S3 Object Lock. Omit the whole block if the tenant does not need it -
+  # the operator still applies the grid's retention ceiling in the backend.
+  s3ObjectLock:
+    # Maximum mode buckets in this tenant may use: Disabled (default), Governance, Compliance.
+    # Compliance requires the parent StorageGrid to have Object Lock enabled grid-wide.
+    mode: Governance
+    # Caps retentionInDays on every bucket in this tenant.
+    # 0 or omitted inherits StorageGrid.spec.defaultMaxRetentionInDays.
+    maxRetentionInDays: 90
 ```
 
 #### Available Annotations

api/v1alpha1/s3tenant_common.go

@@ -119,8 +119,11 @@ type S3ObjectLockTenantSpec struct {
 
 	// MaxRetentionInDays caps the retentionInDays a bucket in this tenant may request.
 	// Mapped to the backend tenant policy MaxRetentionDays.
+	// Zero means inherit the grid-wide StorageGrid spec.defaultMaxRetentionInDays; the backend
+	// always ends up with a concrete ceiling because StorageGrid does not accept an empty one.
 	// +kubebuilder:default=0
 	// +kubebuilder:validation:Minimum=0
+	// +kubebuilder:validation:Maximum=36500
 	// +optional
 	MaxRetentionInDays int32 `json:"maxRetentionInDays,omitempty"`
 }

api/v1alpha1/storagegrid_types.go

@@ -27,6 +27,11 @@ const (
 	DefaultRetentionDuration       = "168h"                     // 7 days
 	DefaultTenantDeletionProcedure = TenantDeletionPolicyRetain // Default policy for tenant deletion
 
+	// DefaultMaxRetentionInDays is the fallback S3 Object Lock retention ceiling applied when
+	// neither the tenant nor the StorageGrid specifies one. StorageGrid itself would default to
+	// 100 years, so the operator pins one year instead, matching what the Tenant Manager writes.
+	DefaultMaxRetentionInDays int32 = 365
+
 	// Default bucket drain operation intervals.
 	DefaultDrainInitialPollInterval     = 3 * time.Minute
 	DefaultDrainLongRunningPollInterval = 30 * time.Minute
@@ -97,6 +102,17 @@ type StorageGridSpec struct {
 	// +kubebuilder:default={retentionDuration: "168h"}
 	DefaultTenantDeletionPolicy *TenantDeletionPolicy `json:"defaultTenantDeletionPolicy,omitempty"`
 
+	// DefaultMaxRetentionInDays is the S3 Object Lock retention ceiling applied to tenants on this
+	// grid that do not set spec.s3ObjectLock.maxRetentionInDays themselves.
+	// StorageGrid requires a value between 1 day and 100 years once S3 Object Lock is enabled
+	// grid-wide, and silently applies 100 years when no value is sent, so the operator always
+	// writes this field explicitly.
+	// +kubebuilder:default=365
+	// +kubebuilder:validation:Minimum=1
+	// +kubebuilder:validation:Maximum=36500
+	// +optional
+	DefaultMaxRetentionInDays int32 `json:"defaultMaxRetentionInDays,omitempty"`
+
 	// Amount of nodes (default: 1) that can be unavailable before the StorageGrid is considered not ready.
 	// This is a safeguard to prevent operations when the StorageGrid is not fully available.
 	// +kubebuilder:default=1
@@ -211,6 +227,11 @@ type StorageGridStatus struct {
 	// +kubebuilder:default={}
 	DefaultTenantDeletionPolicy *TenantDeletionPolicy `json:"defaultTenantDeletionPolicy,omitempty"`
 
+	// Currently active default S3 Object Lock retention ceiling in days, applied to tenants
+	// that do not set spec.s3ObjectLock.maxRetentionInDays themselves.
+	// +optional
+	DefaultMaxRetentionInDays int32 `json:"defaultMaxRetentionInDays,omitempty"`
+
 	// Usage of the StorageGrid summarizes the usage of all tenants.
 	// +optional
 	StorageGridUsage StorageGridUsage `json:"usage,omitempty"`

config/crd/bases/s3.bedag.ch_s3tenantaccounts.yaml

@@ -290,7 +290,10 @@ spec:
                     description: |-
                       MaxRetentionInDays caps the retentionInDays a bucket in this tenant may request.
                       Mapped to the backend tenant policy MaxRetentionDays.
+                      Zero means inherit the grid-wide StorageGrid spec.defaultMaxRetentionInDays; the backend
+                      always ends up with a concrete ceiling because StorageGrid does not accept an empty one.
                     format: int32
+                    maximum: 36500
                     minimum: 0
                     type: integer
                   mode:

config/crd/bases/s3.bedag.ch_s3tenants.yaml

@@ -226,7 +226,10 @@ spec:
                     description: |-
                       MaxRetentionInDays caps the retentionInDays a bucket in this tenant may request.
                       Mapped to the backend tenant policy MaxRetentionDays.
+                      Zero means inherit the grid-wide StorageGrid spec.defaultMaxRetentionInDays; the backend
+                      always ends up with a concrete ceiling because StorageGrid does not accept an empty one.
                     format: int32
+                    maximum: 36500
                     minimum: 0
                     type: integer
                   mode:

config/crd/bases/s3.bedag.ch_storagegrids.yaml

@@ -58,6 +58,18 @@ spec:
                 description: Default region for buckets created in the StorageGrid,
                   defaults to the first region in the list.
                 type: string
+              defaultMaxRetentionInDays:
+                default: 365
+                description: |-
+                  DefaultMaxRetentionInDays is the S3 Object Lock retention ceiling applied to tenants on this
+                  grid that do not set spec.s3ObjectLock.maxRetentionInDays themselves.
+                  StorageGrid requires a value between 1 day and 100 years once S3 Object Lock is enabled
+                  grid-wide, and silently applies 100 years when no value is sent, so the operator always
+                  writes this field explicitly.
+                format: int32
+                maximum: 36500
+                minimum: 1
+                type: integer
               defaultTenantDeletionPolicy:
                 default:
                   retentionDuration: 168h
@@ -303,6 +315,12 @@ spec:
               defaultBucketRegion:
                 description: DefaultRegion for buckets created in the StorageGrid.
                 type: string
+              defaultMaxRetentionInDays:
+                description: |-
+                  Currently active default S3 Object Lock retention ceiling in days, applied to tenants
+                  that do not set spec.s3ObjectLock.maxRetentionInDays themselves.
+                format: int32
+                type: integer
               defaultTenantDeletionPolicy:
                 default: {}
                 description: Currently active tenant deletion policy.

config/samples/s3_v1alpha1_storagegrid.yaml

@@ -23,3 +23,8 @@ spec:
   s3ApiEndpoint:
     pathStyleAccess: true
     url: https://s3.storagegrid.example.com:10443
+  # S3 Object Lock retention ceiling in days for tenants that do not set
+  # spec.s3ObjectLock.maxRetentionInDays themselves. Must be 1..36500 (100 years).
+  # StorageGrid applies a 100 year ceiling of its own when no value is sent, so the
+  # operator always writes this field explicitly.
+  defaultMaxRetentionInDays: 365

internal/controller/objectlock_retention_test.go

@@ -0,0 +1,94 @@
+/*
+Copyright 2025.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package controller
+
+import (
+	"testing"
+
+	s3v1alpha1 "github.com/bedag/storagegrid-operator/api/v1alpha1"
+)
+
+func gridWithDefault(days int32) *s3v1alpha1.StorageGrid {
+	return &s3v1alpha1.StorageGrid{
+		Spec: s3v1alpha1.StorageGridSpec{DefaultMaxRetentionInDays: days},
+	}
+}
+
+// StorageGrid rejects an empty S3 Object Lock ceiling and silently substitutes 100 years when a
+// request carries none, so this resolution must never yield zero no matter how sparse the input.
+func TestEffectiveMaxRetentionInDays(t *testing.T) {
+	tests := []struct {
+		name string
+		spec *s3v1alpha1.S3ObjectLockTenantSpec
+		sg   *s3v1alpha1.StorageGrid
+		want int32
+	}{
+		{
+			name: "tenant ceiling wins over the grid default",
+			spec: &s3v1alpha1.S3ObjectLockTenantSpec{Mode: s3v1alpha1.S3ObjectLockModeGovernance, MaxRetentionInDays: 90},
+			sg:   gridWithDefault(365),
+			want: 90,
+		},
+		{
+			name: "zero is the inherit sentinel",
+			spec: &s3v1alpha1.S3ObjectLockTenantSpec{Mode: s3v1alpha1.S3ObjectLockModeDisabled, MaxRetentionInDays: 0},
+			sg:   gridWithDefault(365),
+			want: 365,
+		},
+		{
+			name: "absent object lock config inherits the grid default",
+			spec: nil,
+			sg:   gridWithDefault(730),
+			want: 730,
+		},
+		{
+			// The ceiling also caps Governance retention requested straight over the S3 API,
+			// which the S3Bucket mode gate never sees, so mode must not suppress it.
+			name: "a ceiling applies even when the mode is Disabled",
+			spec: &s3v1alpha1.S3ObjectLockTenantSpec{Mode: s3v1alpha1.S3ObjectLockModeDisabled, MaxRetentionInDays: 30},
+			sg:   gridWithDefault(365),
+			want: 30,
+		},
+		{
+			name: "an unconfigured grid falls back to one year",
+			spec: nil,
+			sg:   gridWithDefault(0),
+			want: s3v1alpha1.DefaultMaxRetentionInDays,
+		},
+		{
+			name: "a nil grid still resolves",
+			spec: &s3v1alpha1.S3ObjectLockTenantSpec{},
+			sg:   nil,
+			want: s3v1alpha1.DefaultMaxRetentionInDays,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := EffectiveMaxRetentionInDays(tt.spec, tt.sg)
+			if got != tt.want {
+				t.Errorf("got %d, want %d", got, tt.want)
+			}
+			if got <= 0 {
+				t.Errorf("resolution must never yield a non-positive ceiling, got %d", got)
+			}
+			if d := desiredMaxRetentionDays(tt.spec, tt.sg); d != int(tt.want) {
+				t.Errorf("desiredMaxRetentionDays: got %d, want %d", d, tt.want)
+			}
+		})
+	}
+}

internal/controller/s3tenantaccount_controller.go

@@ -1139,7 +1139,7 @@ func (r *S3TenantAccountReconciler) reconcileCreate(ctx context.Context, rctx *a
 	// initial description will include some details about the account in case the reconcileDescription fails later.
 	initialDescription := fmt.Sprintf("Created by storagegrid-operator for S3TenantAccount %s in namespace %s at %s", rctx.Account.Name, rctx.Account.Namespace, time.Now().Format(time.RFC3339))
 
-	tenantID, password, err := grid.CreateTenant(ctx, *rctx.Account.Status.DesiredTenantBackendName, initialDescription, rctx.Account.Spec.StorageQuota.Value(), desiredAllowComplianceMode(rctx.Account.Spec.S3ObjectLock), desiredMaxRetentionDays(rctx.Account.Spec.S3ObjectLock), rctx.GridClient)
+	tenantID, password, err := grid.CreateTenant(ctx, *rctx.Account.Status.DesiredTenantBackendName, initialDescription, rctx.Account.Spec.StorageQuota.Value(), desiredAllowComplianceMode(rctx.Account.Spec.S3ObjectLock), desiredMaxRetentionDays(rctx.Account.Spec.S3ObjectLock, rctx.SG), rctx.GridClient)
 	if err != nil {
 		r.emitEvent(rctx, corev1.EventTypeWarning, EventTenantCreateFailed,
 			fmt.Sprintf("Failed to create tenant: %v", err))
@@ -1417,48 +1417,58 @@ func desiredAllowComplianceMode(spec *s3v1alpha1.S3ObjectLockTenantSpec) bool {
 	return spec.Mode == s3v1alpha1.S3ObjectLockModeCompliance
 }
 
-// desiredMaxRetentionDays maps the spec MaxRetentionInDays to the backend tenant's
-// MaxRetentionDays. Returns nil when object lock is Disabled (no per-tenant cap).
-func desiredMaxRetentionDays(spec *s3v1alpha1.S3ObjectLockTenantSpec) *int {
-	if spec == nil || spec.Mode == "" || spec.Mode == s3v1alpha1.S3ObjectLockModeDisabled {
-		return nil
+// EffectiveMaxRetentionInDays resolves the S3 Object Lock retention ceiling for a tenant:
+// its own MaxRetentionInDays when set, otherwise the grid-wide default.
+//
+// Deliberately independent of Mode. Mode governs whether an S3Bucket may enable object lock at
+// all, but the ceiling also binds Governance retention a tenant can request directly over the S3
+// API, where the bucket-level gate never applies.
+//
+// Never returns zero: StorageGrid rejects an empty ceiling once S3 Object Lock is enabled
+// grid-wide, and silently substitutes 100 years for a request that carries no ceiling at all.
+func EffectiveMaxRetentionInDays(spec *s3v1alpha1.S3ObjectLockTenantSpec, sg *s3v1alpha1.StorageGrid) int32 {
+	if spec != nil && spec.MaxRetentionInDays > 0 {
+		return spec.MaxRetentionInDays
+	}
+	if sg != nil && sg.Spec.DefaultMaxRetentionInDays > 0 {
+		return sg.Spec.DefaultMaxRetentionInDays
 	}
-	v := int(spec.MaxRetentionInDays)
-	return &v
+	return s3v1alpha1.DefaultMaxRetentionInDays
 }
 
-// intPtrEqual compares two *int values for equality, treating nil == nil as equal.
-func intPtrEqual(a, b *int) bool {
-	if a == nil && b == nil {
-		return true
-	}
-	if a == nil || b == nil {
-		return false
-	}
-	return *a == *b
+// desiredMaxRetentionDays adapts the resolved ceiling to the backend tenant's MaxRetentionDays.
+func desiredMaxRetentionDays(spec *s3v1alpha1.S3ObjectLockTenantSpec, sg *s3v1alpha1.StorageGrid) int {
+	return int(EffectiveMaxRetentionInDays(spec, sg))
 }
 
 // reconcileObjectLockPolicy syncs the backend tenant's S3 Object Lock policy fields
-// (AllowComplianceMode, MaxRetentionDays) with the spec. Issues a single full PUT on drift.
+// (AllowComplianceMode, MaxRetentionDays, MaxRetentionYears) with the spec.
+// Issues a single full PUT on drift.
+//
+// MaxRetentionYears participates in the comparison even though the operator never sets it:
+// StorageGrid stamps 100 years onto any tenant created without an explicit ceiling, and a
+// non-nil value there means the tenant is not yet expressed in the operator's terms.
 func (r *S3TenantAccountReconciler) reconcileObjectLockPolicy(ctx context.Context, rctx *accountReconcileContext) error {
 	log := log.FromContext(ctx)
 
 	desiredAllow := desiredAllowComplianceMode(rctx.Account.Spec.S3ObjectLock)
-	desiredMax := desiredMaxRetentionDays(rctx.Account.Spec.S3ObjectLock)
+	desiredMax := desiredMaxRetentionDays(rctx.Account.Spec.S3ObjectLock, rctx.SG)
 
 	currentAllow := grid.GetConfiguredAllowComplianceMode(rctx.BackendTenant)
 	currentMax := grid.GetConfiguredMaxRetentionDays(rctx.BackendTenant)
+	currentYears := grid.GetConfiguredMaxRetentionYears(rctx.BackendTenant)
 
-	if currentAllow == desiredAllow && intPtrEqual(currentMax, desiredMax) {
+	if currentAllow == desiredAllow && currentMax != nil && *currentMax == desiredMax && currentYears == nil {
 		log.V(1).Info("Object lock policy already in sync")
 		return nil
 	}
 
 	log.V(1).Info("Object lock policy drift detected, updating tenant",
 		"currentAllowComplianceMode", currentAllow, "desiredAllowComplianceMode", desiredAllow,
-		"currentMaxRetentionDays", currentMax, "desiredMaxRetentionDays", desiredMax)
+		"currentMaxRetentionDays", currentMax, "desiredMaxRetentionDays", desiredMax,
+		"currentMaxRetentionYears", currentYears)
 	r.emitEvent(rctx, corev1.EventTypeNormal, EventTenantUpdating,
-		fmt.Sprintf("Updating S3 Object Lock policy (allowComplianceMode=%v, maxRetentionDays=%v)", desiredAllow, desiredMax))
+		fmt.Sprintf("Updating S3 Object Lock policy (allowComplianceMode=%v, maxRetentionDays=%d)", desiredAllow, desiredMax))
 
 	if err := grid.UpdateTenantObjectLockPolicy(ctx, desiredAllow, desiredMax, rctx.BackendTenant, rctx.GridClient); err != nil {
 		r.emitEvent(rctx, corev1.EventTypeWarning, EventTenantUpdateFailed,

internal/controller/storagegrid_controller.go

@@ -185,6 +185,9 @@ func (r *StorageGridReconciler) doReconcile(ctx context.Context, rctx *sgReconci
 	// probe grid-wide S3 Object Lock capability (transient failures must not flip Ready).
 	r.reconcileS3ObjectLockCapability(ctx, rctx)
 
+	// mirror the grid-wide S3 Object Lock retention default into the status.
+	r.reconcileDefaultMaxRetention(ctx, rctx)
+
 	// set the condition to true, as we successfully reconciled the storageGrid.
 	r.setCondition(rctx.SG, s3v1alpha1.ConditionTypeReconcileSucceeded, metav1.ConditionTrue, "ReconcileSucceeded", "StorageGrid reconciled successfully")
 
@@ -393,6 +396,23 @@ func (r *StorageGridReconciler) reconcileDeletionPolicy(ctx context.Context, sg
 	}
 }
 
+// reconcileDefaultMaxRetention mirrors the grid-wide S3 Object Lock retention default into the
+// status so it is visible via kubectl. The S3TenantAccount controller resolves against the spec
+// directly, so this mirror is purely informational and never gates a backend write.
+func (r *StorageGridReconciler) reconcileDefaultMaxRetention(ctx context.Context, rctx *sgReconcileContext) {
+	log := log.FromContext(ctx)
+
+	desired := rctx.SG.Spec.DefaultMaxRetentionInDays
+	if desired <= 0 {
+		desired = s3v1alpha1.DefaultMaxRetentionInDays
+	}
+
+	if rctx.SG.Status.DefaultMaxRetentionInDays != desired {
+		log.V(1).Info(fmt.Sprintf("Updating default max retention from %d to %d days", rctx.SG.Status.DefaultMaxRetentionInDays, desired))
+		rctx.SG.Status.DefaultMaxRetentionInDays = desired
+	}
+}
+
 func (r *StorageGridReconciler) initGridClient(ctx context.Context, rctx *sgReconcileContext) error {
 	log := log.FromContext(ctx)