From a86834e01be46dae3abe21386f44943ee8e51718 Mon Sep 17 00:00:00 2001
From: Eduardo Gonzalez <dabarren@gmail.com>
Date: Wed, 21 Nov 2018 11:25:50 +0100
Subject: [PATCH] Document glance service
Add documentation about glance backends,
upgrades and futher configuration.
Change-Id: Ibb15804fa3f38abab855084dd7d7b83fd4a54b8f
---
doc/source/reference/glance-guide.rst | 147 ++++++++++++++++++++++++++
doc/source/reference/index.rst | 1 +
2 files changed, 148 insertions(+)
create mode 100644 doc/source/reference/glance-guide.rst
diff --git a/doc/source/reference/glance-guide.rst b/doc/source/reference/glance-guide.rst
new file mode 100644
index 0000000000..ce1d52b9f8
--- /dev/null
+++ b/doc/source/reference/glance-guide.rst
@@ -0,0 +1,147 @@
+.. _glance-guide:
+
+===============
+Glance in Kolla
+===============
+
+Glance backends
+---------------
+
+Overview
+~~~~~~~~
+
+Glance can be deployed using Kolla and supports the following
+backends:
+
+* file
+* ceph
+* vmware
+* swift
+
+File backend
+~~~~~~~~~~~~
+
+When using the ``file`` backend, images will be stored locally
+under the value of the ``glance_file_datadir_volume`` variable, which defaults
+to a docker volume called ``glance``. By default when using ``file`` backend
+only one ``glance-api`` container can be running.
+
+For better reliability and performance, ``glance_file_datadir_volume`` should
+be mounted under a shared filesystem such as NFS.
+
+Usage of glance file backend under shared filesystem:
+
+.. code-block:: yaml
+
+ glance_backend_file: "yes"
+ glance_file_datadir_volume: "/path/to/shared/storage/"
+
+Ceph backend
+~~~~~~~~~~~~
+
+To make use of ``ceph`` backend in glance, simply enable ceph or external ceph.
+By default will enable backend ceph automatically.
+Please refer to :doc:`ceph-guide` or :doc:`external-ceph-guide` on how to
+configure this backend.
+
+To enable the ceph backend manually:
+
+.. code-block:: yaml
+
+ glance_backend_ceph: "yes"
+
+VMware backend
+~~~~~~~~~~~~~~
+
+To make use of VMware datastores as a glance backend,
+enable `glance_backend_vmware` and refer to :doc:`vmware-guide` for
+further VMware configuration.
+
+To enable the vmware backend manually:
+
+.. code-block:: yaml
+
+ glance_backend_vmware: "yes"
+
+Swift backend
+~~~~~~~~~~~~~
+
+To store glance images in a swift cluster, the ``swift`` backend should
+be enabled. Refer to :doc:`swift-guide` on how to configure swift in kolla.
+If ceph is enabled, will have higher precedence over swift as glance backend.
+
+To enable the swift backend manually:
+
+.. code-block:: yaml
+
+ glance_backend_swift: "yes"
+
+Upgrading glance
+----------------
+
+Overview
+~~~~~~~~
+
+Glance can be upgraded with the following methods:
+
+* Rolling upgrade
+* Legacy upgrade
+
+Rolling upgrade
+~~~~~~~~~~~~~~~
+
+As of the Rocky release, glance can be upgraded in a rolling upgrade mode.
+This mode will reduce the API downtime during upgrade to a minimum of
+a container restart, aiming for zero downtime in future releases.
+
+By default it is disabled, so if you want to upgrade using this mode it will
+need to be enabled.
+
+.. code-block:: yaml
+
+ glance_enable_rolling_upgrade: "yes"
+
+.. warning::
+
+ When using glance backend ``file`` without a shared filesytem, this method cannot
+ be used or will end up with a corrupt state of glance services.
+ Reasoning behind is because glance api is only running in one host, blocking the
+ orchestration of a rolling upgrade.
+
+Legacy upgrade
+~~~~~~~~~~~~~~
+
+This upgrade method will stop APIs during database schema migrations,
+and container restarts.
+
+It is the default mode, ensure rolling upgrade method is not enabled.
+
+.. code-block:: yaml
+
+ glance_enable_rolling_upgrade: "no"
+
+
+Other configuration
+-------------------
+
+Glance cache
+~~~~~~~~~~~~
+
+Glance cache is disabled by default, it can be enabled by:
+
+.. code-block:: yaml
+
+ enable_glance_image_cache: "yes"
+ glance_cache_max_size: "10737418240" # 10GB by default
+
+.. warning::
+
+ When using the ceph backend, is recommended to not use glance cache, since
+ nova already has a cached version of the image, and the image is directly
+ copied from ceph instead of glance api hosts. Enabling glance cache will
+ lead to unnecessary storage consumption.
+
+Glance caches are not cleaned up automatically, the glance team recommends to
+use a cron service to regularly clean cached images. In the future kolla will
+deploy a cron container to manage such clean ups. Please refer to `Glance
+image cache <https://docs.openstack.org/glance/latest/admin/cache.html>`__.
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
index 61da4607b0..71feacc8ab 100644
--- a/doc/source/reference/index.rst
+++ b/doc/source/reference/index.rst
@@ -29,3 +29,4 @@ Projects Deployment References
xenserver-guide
horizon-guide
resource-constraints
+ glance-guide