From 2da448b43f3427700e5f59e8f16f507aa2e1f372 Mon Sep 17 00:00:00 2001
From: Alex Auvolat <alex@adnab.me>
Date: Tue, 24 May 2022 15:28:37 +0200
Subject: Add documentation for new Admin API and a few infos on K2V

---
 doc/book/reference-manual/k2v.md | 58 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 doc/book/reference-manual/k2v.md

(limited to 'doc/book/reference-manual/k2v.md')

diff --git a/doc/book/reference-manual/k2v.md b/doc/book/reference-manual/k2v.md
new file mode 100644
index 00000000..742e4309
--- /dev/null
+++ b/doc/book/reference-manual/k2v.md
@@ -0,0 +1,58 @@
++++
+title = "K2V"
+weight = 30
++++
+
+Starting with version 0.7.2, Garage introduces an optionnal feature, K2V,
+which is an alternative storage API designed to help efficiently store
+many small values in buckets (in opposition to S3 which is more designed
+to store large blobs).
+
+K2V is currently disabled at compile time in all builds, as the
+specification is still subject to changes. To build a Garage version with
+K2V, the Cargo feature flag `k2v` must be activated.  Special builds with
+the `k2v` feature flag enabled can be obtained from our download page under
+"Extra builds": such builds can be identified easily as their tag name ends
+with `-k2v` (example: `v0.7.2-k2v`).
+
+The specification of the K2V API can be found
+[here](https://git.deuxfleurs.fr/Deuxfleurs/garage/src/branch/k2v/doc/drafts/k2v-spec.md).
+This document also includes a high-level overview of K2V's design.
+
+The K2V API uses AWSv4 signatures for authentification, same as the S3 API.
+The AWS region used for signature calculation is always the same as the one
+defined for the S3 API in the config file.
+
+## Enabling and using K2V
+
+To enable K2V, download and run a build that has the `k2v` feature flag
+enabled, or produce one yourself. Then, add the following section to your
+configuration file:
+
+```toml
+[k2v_api]
+api_bind_addr = "<ip>:<port>"
+```
+
+Please select a port number that is not already in use by another API
+endpoint (S3 api, admin API) or by the RPC server.
+
+We provide an early-stage K2V client library for Rust which can be imported by adding the following to your `Cargo.toml` file:
+
+```toml
+k2v-client = { git = "https://git.deuxfleurs.fr/Deuxfleurs/garage.git" }
+```
+
+There is also a simple CLI utility which can be built from source in the
+following way:
+
+```sh
+git clone https://git.deuxfleurs.fr/Deuxfleurs/garage.git
+cd garage/src/k2v-client
+cargo build --features cli --bin k2v-cli
+```
+
+The CLI utility is self-documented, run `k2v-cli --help` to learn how to use
+it. There is also a short README.md in the `src/k2v-client` folder with some
+instructions.
+
-- 
cgit v1.2.3


From f6aebefcc9747bf5afad3767e9ae6f9f3aba30ae Mon Sep 17 00:00:00 2001
From: Alex Auvolat <alex@adnab.me>
Date: Wed, 14 Sep 2022 19:31:13 +0200
Subject: Some work on documentation towards v0.8

---
 doc/book/reference-manual/k2v.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/book/reference-manual/k2v.md')

diff --git a/doc/book/reference-manual/k2v.md b/doc/book/reference-manual/k2v.md
index 742e4309..207d056a 100644
--- a/doc/book/reference-manual/k2v.md
+++ b/doc/book/reference-manual/k2v.md
@@ -1,6 +1,6 @@
 +++
 title = "K2V"
-weight = 30
+weight = 70
 +++
 
 Starting with version 0.7.2, Garage introduces an optionnal feature, K2V,
-- 
cgit v1.2.3