Skip to content

ops.md

Latest commit

 

History

History
93 lines (60 loc) · 5.29 KB

ops.md

File metadata and controls

93 lines (60 loc) · 5.29 KB
Raw

rc operational utilities

Purpose

rc ping, rc ready, and rc du provide lightweight service checks and storage-usage reporting. The health commands use public RustFS endpoints. rc du prefers the RustFS background-scanner snapshot and can run a portable but potentially expensive S3 scan only when the user explicitly permits it.

Syntax

rc [GLOBAL OPTIONS] ping <ALIAS> [--timeout <SECONDS>]
rc [GLOBAL OPTIONS] ready <ALIAS> [--timeout <SECONDS>]
rc [GLOBAL OPTIONS] du <ALIAS[/BUCKET[/PREFIX]]> [OPTIONS]

Health commands

rc ping sends an unsigned request to the documented RustFS liveness endpoint, GET /health. It reports the configured endpoint identity, server-provided service and version fields when present, and round-trip latency.

rc ready sends an unsigned request to GET /health/ready. RustFS 1.0.0-beta.10 returns HTTP 200 when required dependencies are ready, HTTP 503 when readiness is degraded, and may return HTTP 429 with Retry-After when the compatibility busy check is enabled. Both 429 and 503 produce retryable network exit code 3 rather than a false success.

Both commands default to a five-second timeout. --timeout accepts an integer from 1 through 300 seconds. Connection, response-body, and total request time remain bounded by the configured alias transport settings and the command timeout.

Examples:

rc ping local
rc ready local --timeout 2
rc ready local --json

Usage command

RustFS 1.0.0-beta.10 exposes a signed data-usage snapshot at GET /rustfs/admin/v3/datausageinfo. Capability discovery advertises this fast path as admin.data-usage. The snapshot is generated by the server's background scanner, so it can be older than the command invocation.

rc du includes source in JSON and prints it in human output:

  • server_snapshot means the RustFS data-usage snapshot was used;
  • client_scan means the user permitted and the client performed paginated S3 requests.

When a server snapshot includes last_update, output includes snapshot_at and snapshot_age_seconds. A snapshot older than one hour is marked stale; the command still reports the actual timestamp and age rather than presenting the statistics as current.

Options

Option Description
--fallback Permit a slower client-side S3 scan when capability discovery, the admin route, or authorization prevents use of the snapshot.
--versions During a client scan, use paginated object-version listing and include version and delete-marker counts. A server snapshot reports the counts already supplied by RustFS.
--incomplete During a client scan, paginate incomplete multipart uploads and each upload's parts; include upload counts and uploaded part bytes.

Prefix totals and incomplete multipart totals are not available in the RustFS server snapshot. Those requests require --fallback; the command never starts the scan implicitly. An admin permission denial also preserves exit code 4 unless --fallback was supplied.

Examples:

# Fast cluster snapshot on supported RustFS versions
rc du local

# Bucket snapshot, with explicit portable fallback if the route cannot be used
rc du local/photos --fallback

# Prefix scan including every version and delete marker
rc du local/photos/2026/ --fallback --versions

# Include uploaded bytes from incomplete multipart uploads
rc du local/photos --fallback --incomplete

Client-scan semantics

The fallback uses S3 pagination until completion:

  • ListBuckets determines cluster scope;
  • ListObjectsV2 counts current objects and bytes by default;
  • ListObjectVersions replaces current-object byte enumeration when --versions is selected;
  • ListMultipartUploads and ListParts supply incomplete-upload counts and bytes when --incomplete is selected.

With --versions, object_count counts current non-delete objects, version_count counts non-delete versions, and delete_marker_count counts delete markers. Incomplete uploaded-part bytes are included in total_bytes when --incomplete is selected and are also exposed separately as incomplete_upload_bytes.

For an alias-wide scan, a bucket-specific failure does not discard successfully collected buckets. Output is marked partial, includes sorted failure records, and the process exits with retryable network code 3. A bucket- or prefix-scoped failure returns its mapped authentication, not-found, or network exit directly.

JSON output

All three commands use output schema v3. Health records use the health family; usage records use the usage family. Human output escapes control and bidirectional formatting characters from server-controlled identity, bucket, and failure strings.

Compatibility

Backend ping / ready du fast path du --fallback
RustFS 1.0.0-beta.10 /health, /health/ready Supported Supported through S3 APIs
Other RustFS versions Supported when documented health routes exist Used only when capability discovery advertises it Supported through S3 APIs
AWS S3, MinIO, other S3-compatible services RustFS health routes are not assumed Not used Best effort, subject to the service's list/version/multipart support and permissions

Prometheus scraping and control of the RustFS background scanner are intentionally outside these commands.