From 73984dd47a1e5ddf60c54eedbb68289e3ad00d50 Mon Sep 17 00:00:00 2001 From: houseme Date: Fri, 24 Jul 2026 15:20:56 +0800 Subject: [PATCH] docs(ilm): document manual transition run limits Document the enqueue_only manual transition contract, secret-handling guidance, and best-effort duration budget while pinning the new duration flag in the e2e response model. Co-Authored-By: heihutu --- crates/e2e_test/src/reliant/tiering.rs | 4 ++++ docs/operations/tier-ilm-debugging.md | 25 +++++++++++++++++++++++++ 2 files changed, 29 insertions(+) diff --git a/crates/e2e_test/src/reliant/tiering.rs b/crates/e2e_test/src/reliant/tiering.rs index 97931389c..3011e8199 100644 --- a/crates/e2e_test/src/reliant/tiering.rs +++ b/crates/e2e_test/src/reliant/tiering.rs @@ -345,6 +345,7 @@ struct ManualTransitionRunReport { skipped_queue_closed: u64, skipped_queue_timeout: u64, truncated_by_limit: bool, + truncated_by_duration: bool, } async fn manual_transition_run( @@ -590,6 +591,7 @@ async fn test_manual_transition_run_black_box_semantics() -> TestResult { assert_eq!(due.report.skipped_directory, 0); assert_eq!(due.report.skipped_replication, 0); assert!(!due.report.truncated_by_limit); + assert!(!due.report.truncated_by_duration); wait_for_transition(&hot_client, MANUAL_DUE_BUCKET, MANUAL_DUE_KEY, StdDuration::from_secs(90)).await?; let remote_count_after_due = cold_tier_object_count(&cold_client).await?; @@ -615,6 +617,7 @@ async fn test_manual_transition_run_black_box_semantics() -> TestResult { assert_eq!(dry.report.dry_run_eligible, 1, "dry-run report: {:#?}", dry.report); assert_eq!(dry.report.enqueued, 0, "dry-run report: {:#?}", dry.report); assert_eq!(dry.report.skipped_not_transition, 1, "dry-run report: {:#?}", dry.report); + assert!(!dry.report.truncated_by_duration); assert_eq!( cold_tier_object_count(&cold_client).await?, before_dry_run_remote_count, @@ -639,6 +642,7 @@ async fn test_manual_transition_run_black_box_semantics() -> TestResult { assert_eq!(not_due.report.skipped_queue_full, 0); assert_eq!(not_due.report.skipped_queue_closed, 0); assert_eq!(not_due.report.skipped_queue_timeout, 0); + assert!(!not_due.report.truncated_by_duration); assert_remains_not_transitioned(&hot_client, MANUAL_NOT_DUE_BUCKET, MANUAL_NOT_DUE_KEY, StdDuration::from_secs(2)).await?; Ok(()) diff --git a/docs/operations/tier-ilm-debugging.md b/docs/operations/tier-ilm-debugging.md index 897cf1dc3..9c8407b49 100644 --- a/docs/operations/tier-ilm-debugging.md +++ b/docs/operations/tier-ilm-debugging.md @@ -73,6 +73,31 @@ If both `x-rustfs-internal-transitioned-versionID` and `x-minio-internal-transitioned-versionID` are the **empty string**, the object was transitioned to a non-versioned tier bucket and no versionId must be sent. +## Manual transition run + +Manual transition run is an operator trigger for the existing lifecycle transition evaluator. It does not force objects that are not due under the bucket lifecycle rule, and it does not bypass versioning, replication, delete-marker, directory-marker, tier, or in-flight transition checks. + +The admin endpoint is: + +```text +POST /rustfs/admin/v3/ilm/transition/run?bucket=&prefix=&tier=&dryRun=true&maxObjects=10000&maxDurationSeconds=30 +``` + +Only `bucket` is required. `prefix`, `tier`, `dryRun`, `maxObjects`, and `maxDurationSeconds` narrow or bound the run. `maxObjects` defaults to `10000` and is capped at `100000`. `maxDurationSeconds` is optional, capped at `3600`, and enforced as a best-effort budget checked between listed object versions and pages; an in-flight listing call is not cancelled. + +The current contract is `enqueue_only`: the response reports what this bounded scan evaluated and enqueued into the in-memory transition queue. `state=completed` means the bounded scan reached the end of its current scope without queue pressure or configured budget truncation. It does not mean every remote tier PUT has completed. `state=partial` means the run stopped early because it hit `maxObjects`, `maxDurationSeconds`, or queue pressure (`skipped_queue_full`, `skipped_queue_closed`, or `skipped_queue_timeout`). + +`job_id` and `status_endpoint` are currently `null`. There is no durable background job, no restart recovery cursor, no cluster-wide single-flight admission, no status polling endpoint, and no cancel endpoint for this trigger yet. Re-running the command is safe only in the normal lifecycle sense: already in-flight object versions are deduplicated in the local process, but separate nodes do not yet share a durable manual-run admission record. + +Recommended operator flow: + +```bash +rc admin ilm transition run local/mybucket --prefix logs/ --tier cold --dry-run --max-objects 1000 --max-duration-seconds 30 +rc admin ilm transition run local/mybucket --prefix logs/ --tier cold --max-objects 1000 --max-duration-seconds 30 +``` + +Inspect the aggregate counters before widening scope. Full object-key lists are intentionally not returned by the admin response. If `RUSTFS_RPC_SECRET` or other credentials were pasted into an issue, chat, log, or ticket while debugging tiering, rotate them on every node, restart the cluster with the new value, and redact the exposed copy before sharing more diagnostics. + ## Historical fixes (for context, already merged) - Expire/GET race (`NoSuchVersion` during expiry of a tiered object):