Batch jobs

Batch jobs are long-running, cluster-driven operations defined by a YAML/JSON spec and executed by the server. They cover bulk replication, key rotation, and lifecycle expiration.

Purpose

• Run bulk operations (replicate-existing, key-rotate, expire) without scripting them client-side.
• Track progress, restart, and report status via mc admin batch.

Layout

cmd/
├── batch-handlers.go             # HTTP entry points and job lifecycle (huge file)
├── batch-handlers_gen.go         # msgp codec
├── batch-job-common-types.go     # Shared job types
├── batch-replicate.go            # "replicate" job
├── batch-replicate_gen.go
├── batch-expire.go               # "expire" job
├── batch-expire_gen.go
├── batch-rotate.go               # "keyrotate" job
├── batch-rotate_gen.go
└── batchjobmetric_string.go      # Metric enum

Key abstractions

Symbol	File	What it is
BatchJobRequest	cmd/batch-job-common-types.go	The parsed YAML/JSON spec.
BatchJobReplicate	cmd/batch-replicate.go	Replicate existing objects to one or more targets.
BatchJobExpire	cmd/batch-expire.go	Expire / delete objects matching filter.
BatchJobKeyRotate	cmd/batch-rotate.go	Re-wrap object DEKs with a new KEK.

How it works

graph LR
    SUB[POST /minio/admin/v3/start-job] --> PARSE[Parse YAML]
    PARSE --> PERSIST[Persist job spec on object store]
    PERSIST --> WORKER[Per-server worker]
    WORKER --> WALK[List bucket]
    WALK --> APPLY[Per-object action]
    APPLY --> REPORT[Update status + metrics]
    REPORT --> POLL[GET /describe-job]

• Specs are uploaded to the cluster via mc admin batch start <spec.yaml>.
• The server picks a coordinator and persists the spec under .minio.sys/batch-jobs/.
• Workers walk the bucket using the metacache walker and apply the action.
• Progress checkpoints survive restarts — the job resumes from its last checkpoint.
• Status is reported via mc admin batch status <job-id>.

Job types

Replicate

Re-replicates existing objects to one or more targets. Filter by prefix, suffix, or tags. Used when a new replication rule is added to a bucket that already has data.

Expire

Bulk delete by filter. Useful for one-off cleanups that don't fit into bucket lifecycle rules. Supports purge: true to bypass versioning.

KeyRotate

Re-wrap each object's DEK with a new KEK without re-uploading data bytes. Used after rotating the cluster KEK in KES.

Integration points

• HTTP entry points in cmd/admin-handlers.go and cmd/batch-handlers.go.
• Reads bucket data via the metacache walker.
• Replicate jobs reuse bucket replication.
• Expire jobs interact with lifecycle.
• Rotate jobs interact with KMS.
• Metrics in cmd/metrics-v2.go and the v3 collectors.

Entry points for modification

• New job type. Add a BatchJob<Name> struct in a new cmd/batch-<name>.go, implement Start(ctx, ...) and the YAML schema, register the type in cmd/batch-handlers.go.
• New filter dimension. Extend cmd/batch-job-common-types.go and update the per-job filtering.