The first document that we will create is the design document. This may be named something different in your organization, but the goal of the design document is to explain the reasoning behind all of the choices that were made in the implementation of the platform. The format may vary from team to team, but we want to capture the following points:
- Background: This is the history behind the decision to start the project. If the document will only be consumed internally, this can be pretty short. If it's going to be consumed externally, this is an opportunity to provide organizational context for your vendors and partners.
- Summary: This is really just a detailed summary of the entire document. Typically, this part of the deliverable will be used by managers, technology, and business leaders to understand the business impact of the overall recommendation. Requirements and the resulting architecture should be summarized.
- Requirements: This is the meat of the document. Requirements can be in whatever format is acceptable for your project management team. We prefer the user story format and will use that in the examples in this book.
- Physical architecture: This is an explanation of roles and physical machines that take those roles. This should include a network diagram.
- Service architecture: This is a summary of available services and their relationships. This section should include a service diagram.
- Tenant architecture: A section should be included that describes the expected landscape inside the cloud. This includes things such as available compute flavors, images, identity management architecture, and IPAM or DDI.
- Roadmap: This section is optional and often lives in another document. It's an opportunity to identify areas for improvement in future releases of the platform.
The design document often goes through a number of revisions as the project is developed. An important step at the end of each iteration of the platform is to reconcile any changes made to the platform with the design document.
Note
Beware of scope creep in the design document. This artifact has a tendency to turn into documentation on how OpenStack works. Remember to focus on explaining the decisions you made instead of what all the available options at the time were.
Every implementation of OpenStack should start with a deployment plan. The design document describes what's being deployed and why, whereas the deployment plan describes how. Like the design document, the content of a deployment plan varies from organization to organization. It should at least include the following things:
- Hardware: This is a list of the compute, storage, and network hardware available for the deployment.
- Network addressing: This is a table of IP and MAC addresses for the network assets in the deployment. For deployments of hundreds of compute nodes, this should probably be limited to a set of VLANs and subnets available for the deployment.
- Deployment-specific configuration: We'll assume that the configuration of the OpenStack deployment is automated. These are any settings that an engineer would need to adjust before launching the automated deployment of the environment.
- Requirements: These are things that need to be in place before the deployment can proceed. Normally, this is hardware configuration, switch configuration, LUN masking, and so on.
A good deployment plan will document everything that an engineering team needs to know to take the design document and instantiate it in the physical world. One thing that we like to leave out of the deployment plan is step-by-step instructions on how to deploy OpenStack. That information typically lives in an Installation Guide, which may be provided by a vendor or written by the operations team.