From ab83caeba014e56668e21601a903e8e6c6a8d205 Mon Sep 17 00:00:00 2001 From: Paul Bourke Date: Thu, 26 Jan 2017 15:59:19 +0000 Subject: [PATCH] Remove image building related docs from kolla-ansible Add links to refer to the main Kolla documentation. Also fix minor formatting errors that were preventing the docs from building. Change-Id: I8759b9e995097d221900441bd001a1234ae007fd Depends-On: Ia7959c71a241b9d7139ec50b34e36b24fbcf76e6 Co-Authored-By: Mauricio Lima --- doc/CONTRIBUTING.rst | 57 ---------------------------------- doc/advanced-configuration.rst | 2 +- doc/index.rst | 29 +++++++---------- doc/multinode.rst | 6 ++-- doc/networking-guide.rst | 2 +- 5 files changed, 16 insertions(+), 80 deletions(-) diff --git a/doc/CONTRIBUTING.rst b/doc/CONTRIBUTING.rst index 2a8f1f1d12..4fd3627176 100644 --- a/doc/CONTRIBUTING.rst +++ b/doc/CONTRIBUTING.rst @@ -48,63 +48,6 @@ Kolla aims to both containerise and deploy all services within the OpenStack "big tent". This is a constantly moving target as the ecosystem grows, so these guidelines aim to help make adding a new service to Kolla a smooth experience. -The image ---------- -Kolla follows Docker best practices -(https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/) -when designing and implementing services where at all possible. - -We use ``jinja2`` templating syntax to help manage the volume and complexity -that comes with maintaining multiple Dockerfiles for multiple different base -operating systems. - -Images should be created under the ``docker`` directory. OpenStack services -should inherit from the provided ``openstack-base`` image, while supporting and -infrastructure services (e.g. mongodb) should inherit from ``base``. - -Services consisting of only one service should be placed in an image named the -same as that service, e.g. ``horizon``. Services that consist of multiple -processes generally use a base image and child images, e.g. ``glance-base``, -``glance-api``, and ``glance-registry``. - -Jinja2 'blocks' are employed throughout the Dockerfile's to help operators -customise various stages of the build (refer to -http://docs.openstack.org/developer/kolla/image-building.html?highlight=override#dockerfile-customisation) - -Some of these blocks are free form however, there are a subset that should be -common to every Dockerfile. The overall structure for a multi container service -is as follows:: - - FROM {{ namespace }}/{{ image_prefix }}openstack-base:{{ tag }} - MAINTAINER {{ maintainer }} - - {% block << service >>_header %}{% endblock %} - - {% import "macros.j2" as macros with context %} - - << binary specific steps >> - - << source specific steps >> - - << common steps >> - - {% block << service >>_footer %}{% endblock %} - {% block footer %}{% endblock %} - {{ include_footer }} - -.. NOTE:: - The generic footer block ``{% block footer %}{% endblock %}`` should not be - included in base images (e.g. glance-base). - - {{ include_footer }} is legacy and should not be included in new services, it - is superseded by {% block footer %}{% endblock %} - -Orchestration -------------- -As of the Newton release there are two main orchestration methods in existence -for Kolla, Ansible and Kubernetes. Ansible is the most mature and generally -regarded as the reference implementation. - When adding a role for a new service in Ansible, there are couple of patterns that Kolla uses throughout that should be followed. diff --git a/doc/advanced-configuration.rst b/doc/advanced-configuration.rst index 933d14e82e..5de784ceca 100644 --- a/doc/advanced-configuration.rst +++ b/doc/advanced-configuration.rst @@ -135,7 +135,7 @@ It is not always practical to get a certificate signed by a well-known trust CA, for example a development or internal test kolla deployment. In these cases it can be useful to have a self-signed certificate to use. -For convenience, the kolla-ansible command will generate the necessary +For convenience, the ``kolla-ansible`` command will generate the necessary certificate files based on the information in the ``globals.yml`` configuration file: diff --git a/doc/index.rst b/doc/index.rst index c9685547cf..a89aab172e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -14,35 +14,28 @@ License for the specific language governing permissions and limitations under the License. -================================= -Welcome to Kolla's documentation! -================================= +========================================= +Welcome to Kolla-Ansible's documentation! +========================================= Kolla's Mission =============== -Kolla provides Docker containers and Ansible playbooks to meet Kolla's mission. Kolla's mission is to provide production-ready containers and deployment tools for operating OpenStack clouds. -Kolla is highly opinionated out of the box, but allows for complete +Kolla-Ansible is highly opinionated out of the box, but allows for complete customization. This permits operators with minimal experience to deploy OpenStack quickly and as experience grows modify the OpenStack configuration to suit the operator's exact requirements. -Site Notes -========== - -This documentation is continually updated and may not represent the state of -the project at any specific prior release. To access documentation for a -previous release of kolla, append the OpenStack release name to the URL, for -example: - - http://docs.openstack.org/developer/kolla/mitaka/ +For information on building container images for use with Kolla-Ansible, please +refer to the `Kolla image documentation +`_. -Kolla Overview -============== +Overview +======== .. toctree:: :maxdepth: 1 @@ -56,8 +49,8 @@ Kolla Overview security troubleshooting -Kolla Services -============== +Services +======== .. toctree:: :maxdepth: 1 diff --git a/doc/multinode.rst b/doc/multinode.rst index 4d675a5d3d..f590c97a16 100644 --- a/doc/multinode.rst +++ b/doc/multinode.rst @@ -106,9 +106,9 @@ Edit the Inventory File ======================= The ansible inventory file contains all the information needed to determine -what services will land on which hosts. Edit the inventory file in the kolla -directory ``ansible/inventory/multinode``. If kolla was installed with pip, -the inventory file can be found in ``/usr/share/kolla``. +what services will land on which hosts. Edit the inventory file in the +Kolla-Ansible directory ``ansible/inventory/multinode``. If Kolla-Ansible +was installed with pip, it can be found in ``/usr/share/kolla-ansible``. Add the ip addresses or hostnames to a group and the services associated with that group will land on that host: diff --git a/doc/networking-guide.rst b/doc/networking-guide.rst index 75be1be46e..e9542725f3 100644 --- a/doc/networking-guide.rst +++ b/doc/networking-guide.rst @@ -122,7 +122,7 @@ and versioning may differ depending on deploy configuration): "kolla_start" 44 minutes ago Up 44 minutes neutron_vpnaas_agent -kolla-ansible includes a small script that can be used in tandem with +Kolla-Ansible includes a small script that can be used in tandem with ``tools/init-runonce`` to verify the VPN using two routers and two Nova VMs: ::