From e2528139566bb7677eca99806e73816c642e03b0 Mon Sep 17 00:00:00 2001
From: Dhia Ayachi <dhia.ayachi@gmail.com>
Date: Tue, 15 Oct 2024 16:09:42 -0400
Subject: [PATCH] add details on how to migrate to wal from boltdb

---
 .../docs/agent/wal-logstore/enable.mdx        |  2 +
 .../agent/wal-logstore/migrate-to-wal.mdx     | 76 +++++++++++++++++++
 .../agent/wal-logstore/revert-to-boltdb.mdx   |  4 +-
 3 files changed, 80 insertions(+), 2 deletions(-)
 create mode 100644 website/content/docs/agent/wal-logstore/migrate-to-wal.mdx

diff --git a/website/content/docs/agent/wal-logstore/enable.mdx b/website/content/docs/agent/wal-logstore/enable.mdx
index f8bc983415..5dc4459fa9 100644
--- a/website/content/docs/agent/wal-logstore/enable.mdx
+++ b/website/content/docs/agent/wal-logstore/enable.mdx
@@ -8,6 +8,8 @@ description: >-
 # Enable the WAL LogStore backend
 
 WAL LogStore is now enabled by default unless a BoltDB database already exist.
+See [migrate to WAL with an existing boltDB database](/consul/docs/agent/wal-logstore/migrate-to-wal)
+for more details on how to migrate to WAL when you already have a boltDB database.
 
 ## Known issues
 
diff --git a/website/content/docs/agent/wal-logstore/migrate-to-wal.mdx b/website/content/docs/agent/wal-logstore/migrate-to-wal.mdx
new file mode 100644
index 0000000000..66aa7797b5
--- /dev/null
+++ b/website/content/docs/agent/wal-logstore/migrate-to-wal.mdx
@@ -0,0 +1,76 @@
+---
+layout: docs
+page_title: Migrate to WAL with an existing BoltDB database
+description: >-
+Learn how to migrate from boltDB to WAL with an existing boltDB database.
+---
+
+# Migrate to WAL with an existing BoltDB database
+
+This topic describes how to migrate to WAL with an existing boltDB database.
+
+The overall process for migrating to WAL with an existing BoltDB database, this take assume that you have a cluster of at least 3 servers:
+
+1. Stop target server gracefully.
+1. Remove data directory from target server.
+1. Update target server's configuration to set wal as raft_logstore backend.
+1. Start target server.
+
+## Stop target server gracefully
+
+Stop the target server gracefully. For example, if you are using `systemd`,
+run the following command:
+
+```shell-session
+$ systemctl stop consul
+```
+
+If your environment uses configuration management automation that might interfere with this process, such as Chef or Puppet, you must disable them until you have completely reverted the storage backend.
+
+## Remove data directory from target server
+
+Temporarily moving the data directory to a different location is less destructive than deleting it. We recommend moving the data directory instead of deleted it in cases where you unsuccessfully enable WAL. Do not use the old data directory (`/data-dir/raft.bak`) for recovery after restarting the server. We recommend eventually deleting the old directory.
+
+The following example assumes the `data_dir` in the server's configuration is `/data-dir` and renames it to `/data-dir.bolt.bak`.
+
+```shell-session
+$ mv /data-dir/raft /data-dir/raft.bolt.bak
+```
+
+When switching backend, you must always remove _the entire raft directory_ not just the `raft.db` file or `wal` directory. This is because the log must always be consistent with the snapshots to avoid undefined behavior or data loss.
+
+## Update target server's configuration
+
+Modify the `backend` in the target server's configuration file:
+
+```hcl
+raft_logstore {
+  backend = "wal"
+  verification {
+    enabled = true
+    interval = "60s"
+  }
+}
+```
+
+## Start target server
+
+Start the target server. For example, if you are using `systemd`, run the following command:
+
+```shell-session
+$ systemctl start consul
+```
+
+Watch for the server to become a healthy voter again.
+
+```shell-session
+$ consul operator raft list-peers
+```
+
+### Clean up old data directories
+
+If necessary, clean up any `raft.bolt.bak` directories. Replace `/data-dir` with the value you specified in your configuration file.
+
+```shell-session
+$ rm /data-dir/raft.bak
+```
diff --git a/website/content/docs/agent/wal-logstore/revert-to-boltdb.mdx b/website/content/docs/agent/wal-logstore/revert-to-boltdb.mdx
index 9ba6923b42..a500a43127 100644
--- a/website/content/docs/agent/wal-logstore/revert-to-boltdb.mdx
+++ b/website/content/docs/agent/wal-logstore/revert-to-boltdb.mdx
@@ -7,13 +7,13 @@ description: >-
 
 # Revert storage backend to BoltDB from WAL
 
-This topic describes how to revert your Consul storage backend from the experimental WAL LogStore backend to the default BoltDB.
+This topic describes how to revert your Consul storage backend from the WAL LogStore backend to the default BoltDB.
 
 The overall process for reverting to BoltDB consists of the following steps. Repeat the steps for all Consul servers that you need to revert.
 
 1. Stop target server gracefully.
 1. Remove data directory from target server.
-1. Update target server's configuration.
+1. Update target server's configuration to set boltdb as raft_logstore backend.
 1. Start target server.
 
 ## Stop target server gracefully