From 610c8a9566e73524f59cf781c09108fb90a0c3bd Mon Sep 17 00:00:00 2001
From: Mark Goddard <mark@stackhpc.com>
Date: Thu, 23 Nov 2017 09:54:17 +0000
Subject: [PATCH] Update documentation for container-image-builders group

---
 doc/source/architecture.rst  |  4 ++--
 doc/source/deployment.rst    | 16 ++++++++++++----
 doc/source/release-notes.rst |  5 +++++
 3 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/doc/source/architecture.rst b/doc/source/architecture.rst
index 87559ee00..ea17070da 100644
--- a/doc/source/architecture.rst
+++ b/doc/source/architecture.rst
@@ -12,8 +12,8 @@ Control host
     be installed, and is typically where the cloud will be managed from.
 Seed host
     The seed host runs the bifrost deploy container and is used to provision
-    the cloud hosts.  Typically the seed host is deployed as a VM but this is
-    not mandatory.
+    the cloud hosts.  By default, container images are built on the seed.
+    Typically the seed host is deployed as a VM but this is not mandatory.
 Cloud hosts
     The cloud hosts run the OpenStack control plane, network, monitoring,
     storage, and virtualised compute services.  Typically the cloud hosts run
diff --git a/doc/source/deployment.rst b/doc/source/deployment.rst
index 99b489189..228b60014 100644
--- a/doc/source/deployment.rst
+++ b/doc/source/deployment.rst
@@ -117,8 +117,11 @@ Building Container Images
 
 It is possible to use prebuilt container images from an image registry such as
 Dockerhub.  In some cases it may be necessary to build images locally either to
-apply local image customisation or to use a downstream version of kolla.  To
-build images locally::
+apply local image customisation or to use a downstream version of kolla.
+Images are built by hosts in the ``container-image-builders`` group, which by
+default includes the ``seed``.
+
+To build container images::
 
     (kayobe) $ kayobe seed container image build
 
@@ -289,8 +292,13 @@ Building Container Images
    as Dockerhub.  In this case, this step can be skipped.
 
 In some cases it may be necessary to build images locally either to apply local
-image customisation or to use a downstream version of kolla.  To build images
-locally::
+image customisation or to use a downstream version of kolla.  Images are built
+by hosts in the ``container-image-builders`` group, which by default includes
+the ``seed``. If no seed host is in use, for example in an all-in-one
+controller development environment, this group may be modified to cause
+containers to be built on the controllers.
+
+To build container images::
 
     (kayobe) $ kayobe overcloud container image build
 
diff --git a/doc/source/release-notes.rst b/doc/source/release-notes.rst
index e75b34faa..04a69e68f 100644
--- a/doc/source/release-notes.rst
+++ b/doc/source/release-notes.rst
@@ -46,6 +46,11 @@ Upgrade Notes
   from ``kolla_config_path`` to ``kolla_build_config_path``.  This provides a
   cleaner separation of kolla and kolla-ansible configuration options. The
   default value is ``{{ config_path }}/kolla``.
+* Adds a group ``container-image-builders``, which defaults to containing the
+  seed.  Hosts in this group will build container images. Previously, container
+  images for the seed were built on the seed, and container images for the
+  overcloud were built on the controllers.  The new design is intended to
+  encourage a build, push, pull workflow.
 
 Kayobe 3.0.0
 ============