Batch Key Rotation

The AIStor Batch Framework allows you to create, manage, monitor, and execute jobs using a YAML-formatted job definition file (a “batch file”). Batch jobs run directly on the AIStor deployment to take advantage of the server-side processing power without constraints of the local machine where you run the AIStor Client.

The keyrotate batch job type performs the following operations on objects in an AIStor deployment:

• Encrypts plaintext (unencrypted) objects using SSE-KMS.
• Rotates encryption keys for objects already encrypted with SSE-S3 or SSE-KMS using SSE-KMS.
• Rotates encryption keys for internal AIStor subsystems (IAM configuration, server configuration, tier configuration, and bucket metadata).

The YAML configuration supports filters to restrict key rotation to a specific set of objects by creation date, tags, metadata, KMS key, or encryption status. You can also define retry attempts or set a notification endpoint and token.

The batch key rotation job processes objects according to the following rules:

To rotate the KMS master key that protects SSE-S3 encrypted objects without converting to SSE-KMS, use mc admin kms key.

Objects protected by Object Lock or legal hold have special handling:

• Plaintext objects with lock or legal hold:

  Always skipped. These objects are protected from modification and cannot be encrypted.

• Encrypted objects with lock or legal hold:

  Skipped by default. Set forceEncryptLocked: true in the job configuration to allow key rotation on these objects.

When the batch job uses the cluster’s default KMS key, the job also re-encrypts internal AIStor subsystem data on AIStor Server RELEASE.2026-02-02T23-40-11Z and later:

• IAM configuration, including users, groups, policies, service accounts, and STS credentials
• Server configuration and configuration history
• Tier configuration
• Bucket metadata, including replication target credentials

Re-encryption with the rotated key ensures all sensitive internal data uses the most current KMS key.

Batch key rotation on any other KMS key(s) has no effect on internal subsystem encryption.

Key rotation batch jobs have no required filter fields. If you do not specify any filters, the job processes all objects in the specified bucket and prefix. When you specify multiple filters, an object must match all specified filter categories to be processed (AND logic between filter types). Within the tags: and metadata: fields, an object matches if any of the specified entries match (OR logic within each field).

Use these fields to send a webhook notification when the job completes. The endpoint receives a JSON POST with job results including job ID, start time, completion status, object counts, and bytes transferred.

If something interrupts the job, you can define a maximum number of retry attempts and how long to wait between retry attempts.

Use mc batch generate to create a basic keyrotate batch job for further customization:

keyrotate:
  apiVersion: v1
  bucket: BUCKET
  prefix: PREFIX
  encryption:
    key: <kms-key-id> # optional, defaults to the default KMS key
    context: <base64-encoded-kms-context> # optional KMS encryption context

  # optional flags based filtering criteria
  # for all objects
  flags:
    filter:
      newerThan: "7d" # match objects newer than this value (e.g. 7d10h31s)
      olderThan: "7d" # match objects older than this value (e.g. 7d10h31s)
      createdAfter: "date" # match objects created after "date"
      createdBefore: "date" # match objects created before "date"
      tags:
        - key: "name"
          value: "pick*" # match objects with tag 'name', with all values starting with 'pick'
      metadata:
        - key: "content-type"
          value: "image/*" # match objects with 'content-type', with all values starting with 'image/'
      kmskey: "key-id" # match objects encrypted with this KMS key-id
      plaintextOnly: false # set to true to only process unencrypted objects
      forceEncryptLocked: false # set to true to rotate keys on locked encrypted objects
    notify:
      endpoint: "https://notify.endpoint" # notification endpoint to receive job status events
      token: "Bearer xxxxx" # optional authentication token for the notification endpoint
    retry:
      attempts: 10 # number of retries for the job before giving up
      delay: "500ms" # least amount of delay between each retry

If you added KMS to an existing deployment and want to encrypt all previously uploaded plaintext objects:

keyrotate:
  apiVersion: v1
  bucket: my-bucket
  encryption: {}  # uses default KMS key
  flags:
    filter:
      plaintextOnly: true  # only encrypt unencrypted objects

To rotate encryption keys for all objects encrypted with the specified kmskey without affecting plaintext objects:

keyrotate:
  apiVersion: v1
  bucket: my-bucket
  encryption: {}
  flags:
    filter:
      kmskey: "old-key-id"  # only rotate objects encrypted with this key

Objects encrypted with another kmskey are left unchanged.

To encrypt all plaintext objects and rotate keys for all encrypted objects in a single job:

keyrotate:
  apiVersion: v1
  bucket: my-bucket
  encryption: {}  # uses default KMS key
  # no plaintextOnly filter means the job processes both plaintext and encrypted objects