[kolla] Reorganization of kolla-ansible documentation

Klemen Pogacnik klemen at psi-net.si
Fri May 14 20:26:31 UTC 2021


I promised to prepare my view as a user of kolla-ansible on its
documentation. In my opinion the division between admin guides and user
guides is artificial, as the user of kolla-ansible is actually the cloud

Maybe it would be good to think about reorganizing the structure of
documentation. Many good chapters are already written, they only have to be
positioned in the right place to be found more easily.

So here is my proposal of kolla-ansible doc's structure:

1. Introduction
1.1. mission
1.2. benefits
1.3. support matrix
2. Architecture
2.1. basic architecture
2.2. HA architecture
2.3. network architecture
2.4. storage architecture
3. Workflows
3.1. preparing the surroundings (networking, docker registry, ...)
3.2. preparing servers (packages installation)
3.3. configuration (of kolla-ansible and description of basic logic for
configuration of Openstack modules)
3.4. 1st day procedures (bootstrap, deploy, destroy)
3.5. 2nd day procedures (reconfigure, upgrade, add, remove nodes ...)
3.6. multiple regions
3.7. multiple cloud
3.8. security
3.9. troubleshooting (how to check, if cloud works, what to do, if it
4. Use Cases
4.1. all-in-one
4.2. basic vm multinode
4.3. some production use cases
5. Reference guide
Mostly the same structure as already is. Except it would be desirable that
description of each module has:
- purpose of the module
- configuration of the module
- how to use it with links to module docs
- basic troubleshooting
6. Contributor guide

The documentation also needs figures, pictures, diagrams to be more
understandable.  So at least in the first chapters some of them shall be

I'm also thinking about convergence of documentation of kayobe, kolla and
kolla-ansible projects. It's true that there's no strict connection between
kayobe and other two and kolla containers can be used without kolla-ansible
playbooks. But the real benefit the user can get is to use all three
projects together. But let's leave that for the second phase.

So please comment on this proposal. Do you think it's going in the right
direction? If yes, I can refine it.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20210514/8583e76a/attachment.html>

More information about the openstack-discuss mailing list