Snapshots

Caution

This feature is experimental. The CRD design for snapshots has not been finalized yet, so the feature is currently enabled via an annotation rather than a dedicated CRD. The annotation and its behavior may change or be replaced in a future release.

Snapshots let Armory capture a topic’s data as distinct, numbered versions over time. Each snapshot is a self-contained version of the backup, so you can keep a clear history and restore from any point you choose. This helps the backup to automatically recover in case of out-of-band errors.

This capability enables the backup process to automatically recover from out-of-band errors. For example, if a Kafka topic is deleted and recreated, the backup’s stored offsets will no longer match the new topic. Without snapshots, this mismatch causes the backup to fail with an offset reset error that requires manual intervention. Snapshots allow Armory to automatically reconcile the state and resume backing up without downtime.

With snapshots enabled, Armory detects topic recreation automatically by tracking the topic’s unique ID (UUID). When a mismatch is detected, Armory archives the existing backup data as a numbered snapshot and starts a fresh backup for the new topic without manual intervention.

Prerequisites

• The Kafka cluster must support topic UUIDs ( KIP-516 ). If the cluster does not expose topic UUIDs, snapshots are disabled for that topic with a warning and the backup falls back to the default original layout.
• Snapshots only apply to topics that do not yet have any backup data in storage. Topics that were already backed up before enabling the annotation continue to use the original layout. See Compatibility with existing backups for details.

Enabling snapshots

Add the io.kannika/experimental-snapshots annotation to your Backup resource:

apiVersion: kannika.io/v1alpha
kind: Backup
metadata:
  name: my-backup
  annotations:
    io.kannika/experimental-snapshots: "true"
spec:
  source: "my-kafka-cluster"
  sink: "my-storage"
  streams:
    - topic: "my-topic"

Once a topic has been backed up with snapshots enabled, it will continue using the versioned layout regardless of whether the annotation is later removed.

Restoring from a specific snapshot

When restoring from a backup that has snapshots, Armory restores from the latest (active) snapshot version by default.

To restore from a specific snapshot version, set the snapshot field on a topic in the Restore resource:

apiVersion: kannika.io/v1alpha
kind: Restore
metadata:
  name: my-restore
spec:
  source: "my-storage"
  sink: "my-kafka-cluster"
  config:
    topics:
      - source: "my-topic"
        target: "my-topic"
        snapshot:
          version: 1

In this example, the restore will read data from snapshot v1 instead of the latest version.

The version field accepts a version number (e.g. 1), a v-prefixed string (e.g. "v1"), or "latest". When snapshot is omitted, Armory defaults to the latest version.

If the specified snapshot version does not exist, the restore will fail with an error that lists the available versions.

Viewing available snapshots

Use kannika-tools snapshot list on a running backup pod to see the available snapshot versions for a topic:

kubectl -n kannika-data exec my-backup-58a8f72c-0 -- kannika-tools snapshot list my-topic

Topic: my-topic (active: v2)

  VERSION  TOPIC ID                               CREATED
  v1       5a8f3b2c-1d4e-4f6a-9b7c-8e2d1f0a3b5c  2026-01-15 10:00:00 UTC
* v2       9c7e4d6f-2a3b-4c8d-1e5f-7g6h8i9j0k1l  2026-06-01 09:00:00 UTC

Use --all to list snapshots for all topics in storage, or -o yaml for machine-readable output.

To inspect the contents of a specific snapshot version, use kannika-tools index show with the --snapshot flag:

kubectl -n kannika-data exec my-backup-58a8f72c-0 -- kannika-tools index show --snapshot 1 my-topic

How it works

When snapshots are enabled, Armory fetches the topic’s UUID from the Kafka admin API each time the backup task for a topic starts or restarts (including after recovering from an error).

For new topics, Armory creates a manifest file and writes backup data under a versioned directory layout:

• Directoryprefix optional prefix when defining a Storage

  • Directorymy-topic

    • manifest tracks snapshot versions and topic UUIDs
    • __lease
    • __time
    • Directorysnapshots/

      • Directoryv1/

        • Directorymy-topic/

          • index index for this snapshot version
          • ULID_1.kan
          • ULID_2.kan
          • …
      • Directoryv2/ created after topic recreation

        • Directorymy-topic/

          • index
          • ULID_1.kan
          • …

See Storage layout for the full directory structure.

Topic recreation detection

Each time a topic’s backup task starts, Armory compares the live topic UUID against the one stored in the manifest. If they differ, the topic has been recreated.

When a mismatch is detected:

1. The current snapshot (e.g. v1) is archived.
2. A new snapshot version (e.g. v2) is created.
3. The backup resumes from the beginning of the new topic.

The archived snapshot remains in storage and can be used for restoring historical data.

Compacted topics

Compacted topics are not yet supported with snapshots. Snapshots currently rely on topic UUID changes, which only occur when a topic is deleted and recreated. Support for snapshotting compacted topics is planned for a future release. In the meantime, you can use scheduled snapshots to rotate backup storage at regular intervals.

Compatibility with existing backups

Enabling snapshots on an existing backup does not migrate or restructure the data already stored. Topics that were backed up before snapshots were enabled continue to use the original layout.

Only new topics (backed up for the first time after enabling the annotation) use the versioned layout with a manifest. If a pre-existing topic is later recreated, Armory detects the UUID mismatch but cannot archive it because the original layout does not support versioning. In that case, the backup will fail with an error, and you must clear the topic’s backup data manually.