From 30c6ec7c08cdf975de94df29bac0410f133b8fb1 Mon Sep 17 00:00:00 2001
From: Benjamin Schimke <benjamin.schimke@canonical.com>
Date: Thu, 29 Feb 2024 12:33:53 +0100
Subject: [PATCH] Add storage how-to documentation (#164)

* add storage how-to documenation

Provides a step by step guide on how to enable, configure and disable
the storage component.
---
 docs/src/howto/index.md   |  1 +
 docs/src/howto/storage.md | 65 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+)
 create mode 100644 docs/src/howto/storage.md

diff --git a/docs/src/howto/index.md b/docs/src/howto/index.md
index 191117d0d..54566609b 100644
--- a/docs/src/howto/index.md
+++ b/docs/src/howto/index.md
@@ -13,6 +13,7 @@ Overview <self>
 :titlesonly:
 
 install/index
+/howto/storage
 /howto/contribute
 /howto/support
 /howto/networking/default-dns
diff --git a/docs/src/howto/storage.md b/docs/src/howto/storage.md
new file mode 100644
index 000000000..60e3c20e1
--- /dev/null
+++ b/docs/src/howto/storage.md
@@ -0,0 +1,65 @@
+# Use default storage in Canonical Kubernetes
+
+Canonical Kubernetes offers a local storage option to quickly set up and run a
+cluster, especially for single-node support. This guide walks you through
+enabling and configuring this feature.
+
+## What you'll need
+
+This guide assumes the following:
+
+- You have root or sudo access to the machine
+- You have a bootstraped Canonical Kubernetes cluster (see the
+  [getting-started-guide]).
+
+
+## Enable Storage
+When bootstrapping the snap, the storage functionality is not enabled by
+default. To enable it, execute the following command:
+
+```sh
+sudo k8s enable storage
+```
+
+## Configure Storage
+While the storage option comes with sensible defaults, you can customise it to
+meet your requirements. Obtain the current configuration by running:
+
+```sh
+sudo k8s get storage
+```
+
+You can modify the configuration using the `set` command. For example, to
+change the local storage path:
+
+```sh
+sudo k8s set storage.local-path=/path/to/new/folder
+```
+
+The storage functionality provides the following configuration options:
+
+- **local-path**: path where the local files will be created.
+- **reclaim-policy**: set the reclaim policy of the persistent volumes
+  provisioned. It should be one of "Retain", "Recycle", or "Delete".
+- **set-default**: set the local-storage storage class to be the default. If
+  this flag is not set and the cluster has already a default storage class it
+  is not changed. If this flag is not set and the cluster does not have a
+  default class set then the class from the local-storage becomes the default
+  one.
+
+## Disable Storage
+The local storage option is suitable for single-node clusters and development
+environments, but it has inherent limitations. For a production environment you
+typically want a more sophisticated storage solution. To disable the storage
+functionality, run:
+
+```
+sudo k8s disable storage
+```
+
+Note that this will only remove the CSI driver. The persististent volume claim
+will still be there and your data remain on disk.
+
+
+<!-- LINKS -->
+[getting-started-guide]: ../tutorial/getting-started.md
\ No newline at end of file