This is an automated email from the ASF dual-hosted git repository.
jojochuang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ozone-site.git
The following commit(s) were added to refs/heads/master by this push:
new e586295e2 HDDS-15611. [Docs] Explain key deletion workflow with Ozone
Snapshots. (#467)
e586295e2 is described below
commit e586295e27288d83a39a8afdbc117582cb25cab5
Author: Wei-Chiu Chuang <[email protected]>
AuthorDate: Thu Jun 25 15:57:40 2026 -0700
HDDS-15611. [Docs] Explain key deletion workflow with Ozone Snapshots.
(#467)
Co-authored-by: Cursor <[email protected]>
---
cspell.yaml | 1 +
.../02-data-operations/03-delete.md | 61 ++++++++++++++++++++++
2 files changed, 62 insertions(+)
diff --git a/cspell.yaml b/cspell.yaml
index b7264e3d3..5ca1ef939 100644
--- a/cspell.yaml
+++ b/cspell.yaml
@@ -91,6 +91,7 @@ words:
- mis-replicated
- unreplicated
- untampered
+- checkpointed
- BCSID
- EC
- reconfig
diff --git a/docs/07-system-internals/02-data-operations/03-delete.md
b/docs/07-system-internals/02-data-operations/03-delete.md
index 88d95768e..a9dc29ac2 100644
--- a/docs/07-system-internals/02-data-operations/03-delete.md
+++ b/docs/07-system-internals/02-data-operations/03-delete.md
@@ -94,6 +94,67 @@ Deleting a directory does **not** instantly move every
descendant. The service:
+## Interaction with Ozone Snapshots
+
+When Ozone Snapshots are enabled on a bucket, the deletion process differs to
guarantee that historical snapshot read integrity is preserved and blocks are
only reclaimed when no longer referenced.
+
+```mermaid
+sequenceDiagram
+ autonumber
+ actor Client
+ participant ActiveDB as Active DB (AOS)
+ participant SnapDB as Snapshot DB (Read-Only)
+ participant KDS as KeyDeletingService
+
+ Client->>ActiveDB: Delete Key (OMKeyDeleteRequest)
+ ActiveDB->>ActiveDB: Move Key to deletedTable
+ Note over ActiveDB: Key is now in Active DB deletedTable
+
+ Note over ActiveDB: User takes Snapshot S1
+ ActiveDB->>SnapDB: 1. Clone DB Checkpoint (includes deletedTable)
+ ActiveDB->>ActiveDB: 2. Clear target bucket keys from active deletedTable
+ Note over SnapDB,ActiveDB: Key is now ONLY in S1 deletedTable, removed
from Active DB
+
+ KDS->>SnapDB: Scan S1 deletedTable
+ SnapDB->>KDS: Found Key
+ KDS->>KDS: Check ReclaimableKeyFilter (Is key in S0 keyTable?)
+ alt Key not referenced by older snapshots
+ KDS->>SCM: Register Block Deletion Command
+ KDS->>SnapDB: Purge Key (OMKeyPurgeRequest)
+ else Key still referenced by older snapshots
+ Note over KDS: Keep Key in S1 deletedTable
+ end
+```
+
+### 1. Deleted Key Partitioning (Snapshot Creation)
+To prevent double-counting and key duplication across databases, deleted keys
are cleanly partitioned during snapshot creation:
+1. **DB Checkpoint**: When a snapshot is taken, the active DB is checkpointed
to create a frozen, read-only snapshot DB. At this point, the snapshot DB's
`deletedTable` and `deletedDirTable` contain all keys that were deleted in the
active namespace prior to the snapshot's creation.
+2. **Active DB Purge**: Immediately following checkpoint creation, the active
DB transaction deletes all keys matching the bucket's prefix from the **active
DB's** `deletedTable` and `deletedDirTable`.
+3. **Partition Effect**:
+ * Keys deleted **before** snapshot creation reside **only in the snapshot
DB's deleted tables**.
+ * Keys deleted **after** snapshot creation reside **only in the active DB's
deleted tables**.
+ * Consequently, a specific deleted key (identified by its path and unique
`objectId`) resides in at most one deleted table at any time.
+
+### 2. Reclaimable Key Filtering
+The `KeyDeletingService` runs background tasks against both the active DB and
the snapshot DBs. To determine if a deleted key's block space can be safely
reclaimed, it uses a `ReclaimableKeyFilter`:
+* When scanning a `deletedTable` entry in snapshot `S_n`, the filter checks if
the key exists in the `keyTable` or `fileTable` of the previous snapshot
`S_{n-1}` in the bucket's snapshot chain.
+* If the key is present in `S_{n-1}`, it means the key is still referenced by
an older snapshot. The key is **not reclaimable** and remains in the
`deletedTable`.
+* If the key is not referenced by any older snapshot, the filter marks it
reclaimable. The block delete commands are registered with SCM, and an
`OMKeyPurgeRequest` removes the metadata entry.
+
+### 3. Snapshot Reclamation (Snapshot Deletion)
+When a snapshot is deleted, its keys must be reconciled with the rest of the
chain:
+* The Snapshot Deleting Service (`SDS`) executes an
`OMSnapshotMoveDeletedKeysRequest`.
+* It scans the deleted snapshot's local `deletedTable`.
+* Any keys that are still referenced by the next snapshot in the chain are
**moved** from the deleted snapshot's `deletedTable` to the next snapshot's
`deletedTable`.
+* If there is no next snapshot, the keys are moved back to the active DB's
`deletedTable`.
+* This ensures that as snapshots are deleted, block deletion intent is safely
passed forward until the blocks are no longer protected by any snapshot.
+
+### 4. Quota Accounting for Snapshots
+* When a key is logically deleted, if snapshots exist, its size is subtracted
from `usedBytes` and added to `snapshotUsedBytes` (the pending deletion bucket).
+* When a key is permanently reclaimed (via `KeyDeletingService` or snapshot
delete), `purgeSnapshotUsedBytes` is called to decrement the
`snapshotUsedBytes` metric.
+
+---
+
## OBS and LEGACY buckets
OBS / legacy layouts use a **flat key namespace** (paths with slashes are
still **one key**). There is **no** directory tree in **`directoryTable`**, so
there is **no** **`DirectoryDeletingService`** expansion step.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
