Overview of the OpenStack Documentation

What Is OpenStack Documentation?

OpenStack Documentation is a comprehensive collection of guides, notes, and manuals that provide detailed information about the OpenStack cloud computing platform and its various projects. This documentation is critical for anyone who wants to install, configure, operate, or use OpenStack—from system administrators to developers.

OpenStack is an open-source platform, which means it is constantly being developed and refined by a global community of contributors. Its technical documentation is also contributed by the open source community, and so while it is extensive, there might be gaps here and there. You can be an OpenStack contributor too by sharing your knowledge and helping to update and expand the documentation. Here is info on how to contribute to the OpenStack docs.

Overview of the OpenStack Documentation

Let’s now take a closer look at the various components of OpenStack Documentation. Each section addresses a specific aspect of the platform, providing relevant information for different user roles and tasks.

Installation Guides

OpenStack provides two levels of installation guides:

OpenStack installation guide covering aspects like setting up the environment, installing OpenStack services, and how to launch an instance.
Project installation guides for each of the OpenStack projects, including Bare Metal service (Ironic), Block Storage service (Cinder), Clustering service (Senlin), and Compute service (Nova). Each of these includes information such as software setup, initial configuration, driver setup, and integration with other OpenStack services.

You can find the installation guides here: https://docs.openstack.org/2023.2/install/

Deployment Guides

OpenStack provides detailed guides for three types of deployments:

OpenStack Charms deployment guide explaining how to manually construct a cloud environment using Juju charms, or automatically with a Juju bundle.
OpenStack deployment using Ansible in Docker containers guide explaining how to use Kolla Ansible, which provides out-of-the-box tools and containers to deploy on OpenStack.
OpenStack-Ansible deployment guide providing instructions for the deployment team to set up OpenStack and Ansible in test and production environments.

You can find the deployment guides here: https://docs.openstack.org/2023.2/deploy/

Operations and Administration Guides

The operations and administration guides are designed for system administrators responsible for managing and maintaining an OpenStack environment. These guides provide detailed instructions for daily administrative tasks, troubleshooting, performance tuning, and system monitoring. They include:

Administrator guides explaining how to work with OpenStack services.
Operations guide detailing how to operate an OpenStack cloud.
Architecture design guide explaining how to plan a cloud in OpenStack.
Security guide providing best practices for securing the cloud.
Virtual machine image guide detailing how to create, maintain, and obtain OpenStack-compatible VM images.

You can find the administrator guides here: https://docs.openstack.org/2023.2/admin/

Configuration Guides

The configuration guides provide detailed information on how to configure various components and services in OpenStack, including Horizon, Manila, Ceilometer, and more. They are useful for tailoring the platform to meet specific needs, from setting up network configurations to customizing compute resources.

Currently there are 25 configuration guides. The first guide provides general configuration information for OpenStack, while the other guides relate to specific services. OpenStack also enables library-based configuration.

You can find the configuration guides here: https://docs.openstack.org/2023.2/configuration/

API Guides

The API guides section of OpenStack Documentation is aimed at developers who are building applications on top of OpenStack. These guides provide comprehensive information about the OpenStack APIs, including their structure, functions, and usage examples.

This section also offers a general API guide explaining how to do the following:

Launching server instances
Create images, objects, and storage containers
Assigning metadata to images and instances

You can find the API guides here: https://docs.openstack.org/2023.2/api/

User Guides

The user guides are useful for new users. The user guides help walk beginners through the initial stages of learning and using OpenStack. They provide detailed explanations of OpenStack’s features, along with step-by-step instructions for performing common tasks.

The end user guides include:

Service-specific guides explaining how to use services like horizon, manila, and more.
Deployment guides explaining how to use OpenStack deployment tools like kolla-ansible and openstack-ansible.

You can find the user guides here: https://docs.openstack.org/2023.2/user/

Project-Specific Guides

In addition to the general user guides, OpenStack Documentation also provides project-specific guides. These guides are created for specific OpenStack projects and go into detail about how to use and manage these projects.

These guides are divided into:

OpenStack services
Bare metal sub-projects
Networking sub-projects
Deployment projects

You can find the project guides here: https://docs.openstack.org/2023.2/projects.html

SIG-Specific Documentation

These documents are created by specific SIGs (Special Interest Groups) within the OpenStack community to share their knowledge and expertise on particular topics. There are three categories:

Extended maintenance SIG explaining how to manage stable branches.
Self-healing documentation for implementing and using self-healing SIGs.
Large-scale SIG documentation explaining how to run OpenStack at scale.

You can find the extended SIG-specific documentation here: https://docs.openstack.org/project-team-guide/stable-branches.html

Contributor Guides

If you’re interested in contributing to the OpenStack project, the contributor guides may be helpful. This section provides information on how to get involved in the OpenStack community, how to contribute code or documentation, and guidelines for community behavior. The contributor guides also help foster a welcoming and productive community.

In addition to the general contributor guide, there are specific guides for:

Documentation contributors
Project teams
Testers and collaborators
Joining the Open Infrastructure Foundation

You can find the OpenStack contributor guides here: https://docs.openstack.org/contributors/

Training Guides

The OpenStack Upstream Institute provides training guides with step-by-step instructions for common tasks. This section is particularly useful for users who learn best through practical experience. It offers information for trainers and trainees. Details include setup, how OpenStack is made, coding, and participation tools and workflows.

You can find information about the Upstream training program here: https://docs.openstack.org/upstream-training/

Best Practices for Using OpenStack Documentation

OpenStack Documentation is a comprehensive and detailed resource, but it can be overwhelming for new users. Here are some best practices to help you navigate the documentation effectively.

Identify the Relevant Documentation

The first step is to identify the relevant documentation for your needs. Are you a new user looking for a basic overview? Or are you an experienced developer looking for detailed information on a specific project? Once you’ve identified your needs, you can navigate to the relevant section of the documentation.

Utilize the Search Function Effectively

The search function is a powerful tool for finding specific information in the documentation. Be sure to use specific and relevant keywords to search for the information you need. Also, consider using the advanced search options to narrow down your search results.

Leverage Troubleshooting and FAQ Sections

The Troubleshooting and FAQ sections are often overlooked, but they are an important pool of valuable information. These sections contain solutions to common problems and answers to frequently asked questions. Before reaching out to the community for help, be sure to check these sections.

Participate in the OpenStack Community

Don’t forget to take advantage of the OpenStack community. The community is a useful resource for getting help and learning from others. You can ask questions, share your knowledge, and contribute to the community in many ways.

Conclusion

The OpenStack Documentation is a vital resource for anyone using or contributing to OpenStack. With its comprehensive guides and tutorials, it provides invaluable assistance to both beginners and experienced users alike. By utilizing these best practices, you can make the most of this resource and enhance your OpenStack experience.

Author
Recent Posts

Sagar Nangare

Director - Product Marketing and Growth at Coredge.io

Sagar Nangare is a technology blogger, focusing on data center technologies (Networking, Telecom, Cloud, Storage) and emerging domains like Open RAN, Edge Computing, IoT, Machine Learning, AI). Based in Pune, he is currently serving Coredge.io as Director - Product Marketing.