The OpenStack Blog Everything in & around OpenStack in written words.

Update: You can now download the OpenStack Architecture Design Guide here.

One thing about OpenStack is that you can find lots of information on how to do specific things, such as start an instance or install a test cloud on VirtualBox, but there isn’t much out there to give you the Big Picture, such as how to design a massively-scalable OpenStack cloud, or a cloud that’s optimized for delivering streaming content. That’s why this past week a dozen OpenStack experts and writers from companies across the OpenStack ecosystem gathered at VMware’s Palo Alto campus for the OpenStack Architecture Design Guide book sprint. The intent was to  deliver a completed book on designing OpenStack clouds — in just five days.

Now, I wrote my first book — a pretty straightforward introduction to Active Server Pages 3.0 — in seven weeks, and then it went through months of editing before arriving at the printer. I never wrote a more significant book that took less than six months.  So when I volunteered for the sprint, I confess that I didn’t expect much.  Oh, I knew that at the end of the week we’d have a book.  I just didn’t expect it to be the really great book that actually emerged.

How a book sprint works

The process of actually writing the book was pretty regimented, but because we felt like we had control over the direction, we didn’t feel stifled by it.  We started by discussing the audience — architects designing OpenStack systems or evaluating it for use — and brainstorming a likely structure.

After deciding that we’d basically cover groupings of use cases for OpenStack clouds, we brainstormed all the different types we might cover, putting them on Post-its and grouping them on the whiteboard. (Let’s just say that “CI/CD” and “dev/test” were on a lot of our minds.)  Before long it was clear that we had seven major categories, such as “compute focused” or “massively scalable”.

We then broke into two groups, each of which was to take half an hour and brainstorm a structure for these categories.  Interestingly, although we used different terms, the structures the two groups emerged with were virtually identical.  (Which meant there was no fight to the death, which is always nice.)

From there our group of 12 broke into 3 groups of 4, each diving into a section.  At the end of Monday, we had 15,000 words already written (of which we’re still sure 10,000 came from Beth Cohen).

I was stunned.

I wasn’t stunned because we had so much content; I was stunned because it was, well, actually pretty good content.

By Wednesday morning, the book was pretty much written, and it was on to editing.  Groups read through sections written by others to try and fill in any holes, and Beth and I began editing, to try and even out the tone.  After that came two more passes: copyediting (by Alexandra Settle, Scott Lowe, and Sean Winn) and fact checking.

Long before Friday, we had a book that we could be proud of.

What the OpenStack Architecture Design Guide covers

The OpenStack Architecture Design Guide is for architects and evaluators; deployment is covered in the OpenStack Operations Guide, so we didn’t cover that. The Design Guide covers the following types of OpenStack clouds:

• General Purpose
• Compute Focused
• Storage Focused
• Network Focused
• Multi-site
• Hybrid Cloud
• Massively Scalable
• Special cases (clouds that don’t fit into those categories, such as multi-hypervisor)

We talked about the different issues, such as user requirements, technical considerations, and operational considerations for each type of cloud, then talked about the actual architecture and provided some prescriptive examples to make things more concrete and easier to understand.

What community really means

Perhaps the most interesting thing about the book sprint is that it was, in many ways, a microcosm of OpenStack itself.  We all work for different companies, some of which don’t particularly get along, but in that room, it didn’t matter. We were just people getting a job done, and doing it in the best way we knew how, working long hours and joking about our evil overlords (sprint facilitators Adam Hyde and Faith Bosworth) and laughing about anything and everything to keep from going stir crazy.

We watched Alex learn that American Mountain Dew is very different from the stuff they have in Australia, and we saw her transform from a nervous newcomer to a confident writer and editor (though I’m still going to use two spaces after a period, sorry).  Anthony Veiga and Sean Collins consistently impressed us with their knowledge of networking.  Sebastian Gutierrez showed how passionate he is about storage, and especially the wonders of Ceph. Vinny Valedez produced more great diagrams in two days than I did all of last year. Maish Saidel-Keesing and Kevin Jackson continuously inspired us to be better with their hard work and good humor. I’m still laughing at Steve Gordon’s deadpan humor.  (And I apologize to anyone who still has the music from Doctor Who stuck in their head.)

Our goal was to provide a resource for the OpenStack community, to help adoption of a tool we’re all passionate about. Did we joke about it?  Of course we did.  But at the end of the day, we wouldn’t have been there if we didn’t believe in the future of OpenStack, and what it can do, when it’s done right.

The OpenStack Architecture Design Guide will be available electronically free of charge as part of the OpenStack documentation, and like the Operations Guide and the Security Guide before it, it will be available for anyone to submit patches to, a living document that will only get better.  It will also be available for purchase in hard copy through Lulu.  Watch this space for a link!