From 0fd36a63c1930aacea4902177dc5e412dd6b8eb1 Mon Sep 17 00:00:00 2001
From: Steven Dake <stdake@cisco.com>
Date: Mon, 22 Feb 2016 08:31:34 -0700
Subject: [PATCH] Add docs about failures during evaluation
The operators aren't mindreaders. Lets throw them a bone about
how to properly evaluate Kolla. This can probably be expanded
on.
TrivialFix
Change-Id: I70d0f6a63417dc9f361d8c14bbb512e1dcc44ed0
---
doc/quickstart.rst | 40 ++++++++++++++++++++++++++++++++++++++++
1 file changed, 40 insertions(+)
diff --git a/doc/quickstart.rst b/doc/quickstart.rst
index 499112d1a9..9b21354019 100644
--- a/doc/quickstart.rst
+++ b/doc/quickstart.rst
@@ -503,6 +503,46 @@ environment with a glance image and neutron networks:
source /etc/kolla/admin-openrc.sh
kolla/tools/init-runonce
+Failures
+--------
+
+Nearly always when Kolla fails, it is caused by a CTRL-C during the
+deployment process or a problem in the globals.yml configuration.
+
+To correct the problem where Operators have a misconfigured
+environment, the Kolla developers have added a precheck feature which
+ensures the deployment targets are in a state where Kolla may deploy
+to them. To run the prechecks, execute:
+
+::
+ kolla-ansible prechecks
+
+If a failure during deployment occurs it nearly always occurs during
+evaluation of the software. Once the Operator learns the few
+configuration options required, it is highly unlikely they will experience
+a failure in deployment.
+
+Deployment may be run as many times as desired, but if a failure in a
+bootstrap task occurs, a further deploy action will not correct the problem.
+In this scenario, Kolla's behavior is undefined.
+
+The fastest way during evaluation to recover from a deployment failure is to
+remove the failed deployment:
+
+On each node where OpenStack is deployed run:
+
+::
+
+ tools/cleanup-containers
+ tools/cleanup-host
+
+The Operator will have to copy via scp or some other means the cleanup
+scripts to the various nodes where the failed containers are located.
+
+The kolla community has separate commands planned for Mitaka for
+reconfiguring the services and upgrading them. These should be used when
+they are available instead of the deploy operation.
+
Debugging Kolla
---------------