From 8691aa63522b1adf68cf7e11d50729d92ae98c2a Mon Sep 17 00:00:00 2001
From: Luka Peschke <luka.peschke@objectif-libre.com>
Date: Mon, 25 Mar 2019 16:32:38 +0100
Subject: [PATCH] Add storage backend documentation

This adds some documentation about storage backend configuration and
available backends.

Change-Id: I7e526b21c4ca409c554e89ed50fc179a61c707ba
---
 doc/source/admin/architecture.rst          |  9 +--
 doc/source/admin/configuration/index.rst   |  1 +
 doc/source/admin/configuration/storage.rst | 75 ++++++++++++++++++++++
 doc/source/admin/index.rst                 |  1 +
 4 files changed, 82 insertions(+), 4 deletions(-)
 create mode 100644 doc/source/admin/configuration/storage.rst

diff --git a/doc/source/admin/architecture.rst b/doc/source/admin/architecture.rst
index 2bf50174..4a71b25d 100644
--- a/doc/source/admin/architecture.rst
+++ b/doc/source/admin/architecture.rst
@@ -110,11 +110,12 @@ Storage
 
 **Loaded with stevedore**
 
-The storage module is responsible of storing the data in a backend. It
-implements an API on top of the storage to be able to query the data without
-the need of knowing the type of backend used.
+The storage module is responsible for storing and retrieving data in a
+backend. It implements two interfaces (v1 and v2), each providing one or more
+drivers. For more information about the storage backend, see the
+`configuration section`_.
 
-You can use the API to create reports on the fly for example.
+.. _configuration section: configuration/storage.html
 
 Writer
 ======
diff --git a/doc/source/admin/configuration/index.rst b/doc/source/admin/configuration/index.rst
index f74fa92b..b581f80c 100644
--- a/doc/source/admin/configuration/index.rst
+++ b/doc/source/admin/configuration/index.rst
@@ -7,4 +7,5 @@ Configuration Guide
 
    configuration
    collector
+   storage
    policy
diff --git a/doc/source/admin/configuration/storage.rst b/doc/source/admin/configuration/storage.rst
new file mode 100644
index 00000000..a2174959
--- /dev/null
+++ b/doc/source/admin/configuration/storage.rst
@@ -0,0 +1,75 @@
+===============================
+ Storage backend configuration
+===============================
+
+Common options
+==============
+
+.. note::
+
+   Two storage backend interfaces are available: v1 and v2. Each supports one
+   or several drivers. The v2 storage interface is required to use
+   CloudKitty's v2 API. It is retrocompatible with the v1 API. However, it is
+   not possible to use the v2 API with the v1 storage interface.
+
+The main storage backend options are specified in the ``[storage]`` section of
+the configuration file. The following options are available:
+
+* ``version``: Defaults to 2. Version of the storage interface to use
+  (must be 1 or 2).
+
+* ``backend``: Defaults to ``influxdb``. Storage driver to use.
+  Supported v1 drivers are:
+
+  - ``sqlalchemy``
+
+  Supported v2 drivers are:
+
+  - ``influxdb``
+
+Driver-specific options
+=======================
+
+SQLAlchemy (v1)
+---------------
+
+This backend has no specific options. It uses the ``connection`` option of the
+``database`` section. Example of value for this option:
+
+.. code-block:: ini
+
+   [database]
+
+   connection = mysql+pymysql://cloudkitty_user:cloudkitty_password@mariadb_host/cloudkitty_database
+
+InfluxDB (v2)
+-------------
+
+Section: ``storage_influx``.
+
+* ``username``: InfluxDB username.
+
+* ``password``: InfluxDB password.
+
+* ``database``: InfluxDB database.
+
+* ``retention_policy``: Retention policy to use (defaults to ``autogen``)
+
+* ``host``: Defaults to ``localhost``. InfluxDB host.
+
+* ``port``: Default to 8086. InfluxDB port.
+
+* ``use_ssl``: Defaults to false. Set to true to use SSL for InfluxDB
+  connections.
+
+* ``insecure``: Defaults to false. Set to true to authorize insecure HTTPS
+  connections to InfluxDB.
+
+* ``cafile``: Path of the CA certificate to trust for HTTPS connections.
+
+
+.. note:: CloudKitty will push one point per collected metric per collect
+          period to InfluxDB. Depending on the size of your infra and the
+          capacities of your InfluxDB host / cluster, you might want to do
+          regular exports of your data and create a custom retention policy on
+          cloudkitty's database.
diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst
index 31f3b618..93cc7082 100644
--- a/doc/source/admin/index.rst
+++ b/doc/source/admin/index.rst
@@ -4,6 +4,7 @@ Administration Guide
 
 .. toctree::
    :glob:
+   :maxdepth: 2
 
    architecture
    devstack