HDDS-14982. [Docs] Snapshot deletion lifecycle (#373)

Author: jojochuang

docs/03-core-concepts/03-namespace/02-buckets/04-layouts/02-file-system-optimized.md

@@ -72,5 +72,5 @@ To update the default layout when creating buckets, configure these properties i
 | `ozone.s3g.default.bucket.layout` | `OBJECT_STORE` | Defines the default layout for buckets created through the S3 API |
 
 <!--
-For detailed technical information about the internal metadata structure and implementation, see the [File System Optimization System Internals](../../../../07-system-internals/07-features/01-filesystem-optimization.md) documentation.
--->
+For detailed technical information about the internal metadata structure and implementation, see the [File System Optimization System Internals](../../../../system-internals/features/filesystem-optimization) documentation.
+-->

docs/05-administrator-guide/02-configuration/03-security/05-encryption/02-transparent-data-encryption.md

@@ -152,7 +152,7 @@ However, in buckets with `FILE_SYSTEM_OPTIMIZED` layout, some irregular S3 key
 names may be rejected or normalized, which can be undesired.
 
 <!--
-See [Prefix based File System Optimization](../../../../07-system-internals/07-features/01-filesystem-optimization.md) for more information.
+See [Prefix based File System Optimization](../../../../system-internals/features/filesystem-optimization) for more information.
 -->
 
 When accessing an S3G-enabled encrypted bucket:

docs/07-system-internals/01-components/01-ozone-manager/02-rocksdb-schema.md

@@ -12,7 +12,7 @@ The exact column families and key encodings can evolve between Ozone releases; t
 
 | Property | Value |
 | -------- | ----- |
-| Database directory | Configured by [`ozone.om.db.dirs`](../../../05-administrator-guide/02-configuration/99-appendix) (falls back to `ozone.metadata.dirs` if unset) |
+| Database directory | Configured by [`ozone.om.db.dirs`](../../../administrator-guide/configuration/appendix) (falls back to `ozone.metadata.dirs` if unset) |
 | On-disk name | `om.db` |
 | Engine | RocksDB with multiple column families |
 
@@ -42,7 +42,7 @@ Used for buckets with **LEGACY** or **OBJECT_STORE** layout. Keys are stored und
 
 ### 3. File system optimized (FSO) layout
 
-Used for buckets with **FILE_SYSTEM_OPTIMIZED** layout. Keys use volume ID, bucket ID, and parent object ID so directory operations (for example `ls`, rename) can avoid scanning full string paths. See also [Filesystem optimization](../../07-features/01-filesystem-optimization).
+Used for buckets with **FILE_SYSTEM_OPTIMIZED** layout. Keys use volume ID, bucket ID, and parent object ID so directory operations (for example `ls`, rename) can avoid scanning full string paths. See also [File System Optimized buckets](../../../core-concepts/namespace/buckets/layouts/file-system-optimized).
 
 | Table name | Key format | Value type | Description |
 | ---------- | ---------- | ---------- | ----------- |

docs/07-system-internals/07-features/03-bucket-snapshot-deletion-lifecycle.md

@@ -0,0 +1,53 @@
+---
+sidebar_label: Snapshot Deletion Lifecycle
+---
+
+# Snapshot Deletion Lifecycle
+
+This document describes the internal lifecycle of snapshot deletion in Apache Ozone, from the initial user request to the final physical removal of data and metadata.
+
+The snapshot deletion process is divided into four main phases:
+
+## 1. Request Phase: `OMSnapshotDeleteRequest`
+
+*   **Trigger:** User executes the command `ozone sh snapshot delete <bucket> <snapshot>`.
+*   **Operation:** 
+    *   The Ozone Manager (OM) receives the request and validates it.
+    *   The snapshot's status is updated to `SNAPSHOT_DELETED` in the `SnapshotInfoTable`.
+    *   The `deletionTime` is set to the current timestamp.
+*   **Result:** This phase only "labels" the snapshot for deletion. It does not yet adjust the snapshot chain or reclaim any data. The snapshot remains in the system but is now a candidate for the background reclamation service.
+
+## 2. Reclamation Phase: `SnapshotDeletingService`
+
+*   **Trigger:** A background service that runs periodically.
+*   **Operation:** 
+    *   The service identifies snapshots with the `SNAPSHOT_DELETED` status.
+    *   It processes the deleted snapshot's internal tracking tables: `deletedTable`, `deletedDirTable`, and `renamedTable`.
+    *   **Data Moving:** It moves entries from these tables to either:
+        1.  The **next active snapshot** in the chain (if one exists).
+        2.  The **Active Object Store (AOS)** if no subsequent snapshot exists.
+*   **Settling:** Once all keys and directories for the snapshot have been successfully moved (i.e., the snapshot's deleted tables are empty), the service collects the snapshot's DB key into a "purge list".
+
+## 3. Finalization Phase: `OMSnapshotPurgeRequest`
+
+*   **Trigger:** Triggered by the `SnapshotDeletingService` once a snapshot is fully "empty" (all keys reclaimed).
+*   **Chain Adjustment (The Surgeon):** This is where the actual snapshot chain surgery occurs. The service updates the `previousSnapshotId` of the next snapshot in the chain to point to the deleted snapshot's predecessor, effectively "stitching" the chain back together.
+*   **Deep Clean Flag:** It sets `setDeepClean(false)` on the next snapshots. This signals the `KeyDeletingService` that it can now perform a "deeper" cleanup because a snapshot in the middle of the chain has been removed, potentially uncovering more keys that are no longer referenced by any snapshot.
+*   **Removal (The Janitor):** The snapshot record is removed from the `SnapshotInfoTable` cache, and the corresponding checkpoint directory on disk is deleted.
+
+## 4. Persistence: `OMSnapshotPurgeResponse`
+
+*   **Operation:** The Ozone Manager double-buffer flushes the transaction to disk.
+*   **Result:** The snapshot record is physically and permanently deleted from the RocksDB `snapshotInfoTable`.
+
+---
+
+## Summary of Roles
+
+| Component | Role | Description |
+| :--- | :--- | :--- |
+| **`OMSnapshotDeleteRequest`** | The Labeler | Marks the snapshot for death by updating its status. |
+| **`SnapshotDeletingService`** | The Reclaimer | Moves the data references to the next snapshot or AOS. |
+| **`OMSnapshotPurgeRequest`** | The Surgeon & Janitor | Re-links the snapshot chain and deletes the physical records. |
+
+![Apache Ozone Snapshot Deletion Lifecycle](snapshot_delete.png)

docs/07-system-internals/07-features/03-bucket-snapshots.md

@@ -1,8 +1,8 @@
 ---
-draft: true
 sidebar_label: Bucket Snapshot
 ---
 
 # Bucket Snapshot System Internals
 
-**TODO:** File a subtask under [HDDS-9862](https://issues.apache.org/jira/browse/HDDS-9862) and complete this page or section.
+For detailed information on how snapshots are deleted internally, see the [Snapshot Deletion Lifecycle](./bucket-snapshot-deletion-lifecycle) page.
+

docs/07-system-internals/07-features/snapshot_delete.png

@@ -0,0 +1,51 @@
+---
+sidebar_label: Snapshot Deletion Lifecycle
+---
+
+# Snapshot Deletion Lifecycle
+
+This document describes the internal lifecycle of snapshot deletion in Apache Ozone, from the initial user request to the final physical removal of data and metadata.
+
+The snapshot deletion process is divided into four main phases:
+
+## 1. Request Phase: `OMSnapshotDeleteRequest`
+
+*   **Trigger:** User executes the command `ozone sh snapshot delete <bucket> <snapshot>`.
+*   **Operation:** 
+    *   The Ozone Manager (OM) receives the request and validates it.
+    *   The snapshot's status is updated to `SNAPSHOT_DELETED` in the `SnapshotInfoTable`.
+    *   The `deletionTime` is set to the current timestamp.
+*   **Result:** This phase only "labels" the snapshot for deletion. It does not yet adjust the snapshot chain or reclaim any data. The snapshot remains in the system but is now a candidate for the background reclamation service.
+
+## 2. Reclamation Phase: `SnapshotDeletingService`
+
+*   **Trigger:** A background service that runs periodically.
+*   **Operation:** 
+    *   The service identifies snapshots with the `SNAPSHOT_DELETED` status.
+    *   It processes the deleted snapshot's internal tracking tables: `deletedTable`, `deletedDirTable`, and `renamedTable`.
+    *   **Data Moving:** It moves entries from these tables to either:
+        1.  The **next active snapshot** in the chain (if one exists).
+        2.  The **Active Object Store (AOS)** (the main bucket) if no subsequent snapshot exists.
+*   **Settling:** Once all keys and directories for the snapshot have been successfully moved (i.e., the snapshot's deleted tables are empty), the service collects the snapshot's DB key into a "purge list".
+
+## 3. Finalization Phase: `OMSnapshotPurgeRequest`
+
+*   **Trigger:** Triggered by the `SnapshotDeletingService` once a snapshot is fully "empty" (all keys reclaimed).
+*   **Chain Adjustment (The Surgeon):** This is where the actual snapshot chain surgery occurs. The service updates the `previousSnapshotId` of the next snapshot in the chain to point to the deleted snapshot's predecessor, effectively "stitching" the chain back together.
+*   **Deep Clean Flag:** It sets `setDeepClean(false)` on the next snapshots. This signals the `KeyDeletingService` that it can now perform a "deeper" cleanup because a snapshot in the middle of the chain has been removed, potentially uncovering more keys that are no longer referenced by any snapshot.
+*   **Removal (The Janitor):** The snapshot record is removed from the `SnapshotInfoTable` cache, and the corresponding checkpoint directory on disk is deleted.
+
+## 4. Persistence: `OMSnapshotPurgeResponse`
+
+*   **Operation:** The Ozone Manager double-buffer flushes the transaction to disk.
+*   **Result:** The snapshot record is physically and permanently deleted from the RocksDB `snapshotInfoTable`.
+
+---
+
+## Summary of Roles
+
+| Component | Role | Description |
+| :--- | :--- | :--- |
+| **`OMSnapshotDeleteRequest`** | The Labeler | Marks the snapshot for death by updating its status. |
+| **`SnapshotDeletingService`** | The Reclaimer | Moves the data references to the next snapshot or AOS. |
+| **`OMSnapshotPurgeRequest`** | The Surgeon & Janitor | Re-links the snapshot chain and deletes the physical records. |