The OpenStack Blog

Author Archive

Announcing the O’Reilly OpenStack Operations Guide

Er, what’s this? An O’Reilly OpenStack Operations Guide offered side-by-side with the continuously-published OpenStack Operations Guide? Yes, your eyes do not deceive you, O’Reilly has completed the production of the OpenStack Operations Guide: Set Up and Manage Your OpenStack Cloud. You can get your bits-n-bytes copy at http://docs.openstack.org/ops/ or order a dead-tree version on the O’Reilly site.

oreilly-openstack-ops-guide

This book was a complete community effort with a bit of a twist: we held a five-day book sprint back in February 2013 with the seven original authors and one book sprint facilitator, Adam Hyde. We wrote and wrote and wrote some more, then edited and glued it all together so that we had a 240 page book by Friday afternoon. The book got quite a bit of love and attention for the next year or so, and in February 2014 we held a mini-sprint with the original authors to update the book for the Havana release and to address developmental edits from our O’Reilly editors, led by Brian Anderson and first introduced by Andy Oram. In the developmental edit, we added a new architecture with RedHat using OpenStack Networking (neutron) as an alternative to Ubuntu with legacy networking, nova-network. We tested a process for upgrading from Grizzly to Havana in a new upgrades chapter. We also added a lot of network troubleshooting information. There’s a new “Havana Haunted by the Dead” tale from the crypt/cloud. We included an expanded glossary as well. Also an exciting addition to a book nerd like myself is the index.

As mentioned in the book itself, we appreciate the 50-plus contributors who support this book and the tool chains around it. Reviews, continuous builds, output, and translations are all an important part of this book’s surrounding systems.

The following people are contributors in the many methods it takes to create a book in the community: Akihiro Motoki, Alejandro Avella, Alexandra Settle, Andreas Jaeger, Andy McCallum, Benjamin Stassart, Beth Cohen, Chandan Kumar, Chris Ricker, David Cramer, David Wittman, Denny Zhang, Emilien Macchi, Gauvain Pocentek, Ignacio Barrio, James E. Blair, Jay Clark, Jeff White, Jeremy Stanley, K Jonathan Harker, KATO Tomoyuki, Lana Brindley, Laura Alves, Lee Li, Lukasz Jernas, Mario B. Codeniera, Matthew Kassawara, Michael Still, Monty Taylor, Nermina Miller, Nigel Williams, Phil Hopkins, Russell Bryant, Sahid Orentino Ferdjaoui, Sandy Walsh, Sascha Peilicke, Sean M. Collins, Sergey Lukjanov, Shilla Saebi, Stephen Gordon, Steven Deaton, Summer Long, Uwe Stuehler, Vaibhav Bhatkar, Veronica Musso, Ying Chun “Daisy” Guo, Zhengguang Ou, and ZhiQiang Fan.

We want to be sure you read this book and log bugs and perhaps even fix some yourself if you’re so inclined! You can read how to on the OpenStack wiki. We also have the OpenStack Security Guide, written in a five day book sprint in June 2013. And we won’t stop there! Plans are underway for a third book to be written with a five day book sprint to help people design OpenStack clouds for many use cases.

We’ll continue to update these books using our community tool chain. We greatly appreciate the support from the OpenStack Foundation and O’Reilly to give the OpenStack Operations Guide that professional polish it deserves.

OpenStack Documentation Wrap Up for 2013

It’s that time of the new year to reflect and look for ways to keep improving the OpenStack docs. Here’s a list of major events from 2013 in OpenStack doc-land. Let’s look at the year in review.

  • Operator Guide book sprint was in February 2013 and I still remember it fondly. The before post and the after post tell the tale, as does this video.
  • Diane Fleming added a sidebar for navigating the every growing API reference site at http://api.openstack.org/api-ref.html. I’d like to see more improvements to the design for that page with more responsiveness for different devices.
  • We have improved the DocImpact commit message flag, where developers can add DocImpact to a commit message, and some automation happens in the background to automatically log a doc bug, setting it to New until the patch actually merges, eliminating a lot of manual steps. Props to Tom Fifield and Steven Deaton for this accomplishment in 2013.
  • We also were able to simultaneously release the docs with the code for the Havana release in the fall for the first time. A large part of this accomplishment is thanks to automation of the Configuration Reference, where the auto doc tool scrapes the docstrings and collects them into meaningful tables per feature per project.
  • This year included a complete reorganization of the docs.openstack.org site landing page. We also added new titles to try to accommodate new audiences. We have a new user guide and admin user guide, which walk through both the Dashboard and command-line interface procedures to accomplish common tasks like launching an instance. As I mentioned above, we’re also maintaining a new Configuration Reference which lists all possible configuration options across multiple OpenStack projects.
  • This year after the Summit in Portland, I worked with Lew Tucker’s finely tuned organization at Cisco to hire a contract writer dedicated to the upstream vanilla OpenStack install guide. There were still hiccups and delays despite having a dedicated resource, but the resulting install guide has been well-received.
  • We held a mid-release OpenStack Docs Boot Camp in sunny California at the Mirantis office. We learned a lot from each other and got to know contributors we hadn’t met in person.
  • In July 2013, the OpenStack security team put together a fantastic OpenStack Security Guide with a book sprint in an undisclosed location in Maryland. At least I think that’s where it was.They’re security conscious.
  • The High Availability Guide got some refreshing as well, thanks to Emilien Macchi and Enovance test labs.
  • We have Japanese fonts now supported in our tool chain, with Japanese translations now available on docs.openstack.org/ja/. Much appreciation to the translation team, especially the Japanese team lead Masanori Itoh, I18N team lead Daisy Guo, and David Cramer for the doc tooling for the font support.
  • Also in 2013 we have been incubating the open source training manuals team within the OpenStack Documentation program. They’ve produced an Associate Training Guide, with outlines and schedules for an Operator Training Guide, a Developer Training Guide, and an Architect Training Guide. All guides and outlines are available at http://docs.openstack.org/training-guides/content/.
  • At the Summit in Hong Kong we announced that the OpenStack Operations Guide became an O’Reilly edition and we are working on the edits coming back from our developmental editor.
  • Most recently we had a Doc Bug Day on 12/20/13 squashing over 80 bugs, following the sun from Australia to the US west coast and then some.

This past year OpenStack Documentation became an official program with me, Anne Gentle, elected as the Program Technical Lead. I hope to continue to serve and promote the Documentation efforts as we go into the new year. Yes, I do read the feedback from the user survey and I know we have work ahead of us. But for the docs to be second-most complained about instead of first-most was a moment to be celebrated in 2013. Thanks to the many contributors who make these incremental improvements happen.

It’s Summer Internship Time in the Southern Hemisphere!

After a brisk walk in Austin Texas in mid-30 degree Fahrenheit weather, I welcome the idea that it’s summertime somewhere. Since it’s summertime in the southern hemisphere, we can now announce our next round of Outreach Program for Women internships!

I’m excited that we have four interns and four mentors this time around. Many thanks to HP, the OpenStack Foundation, and Rackspace for funding our four. HP also stepped in this round and made it possible for more of the nine participating organizations to select interns, including OpenStack. Plus, RedHat developers are mentoring our interns. I asked each intern, what do you see when you look above your screen?

Annapoornima Koppad is known as akoppad on IRC. She lives in Bangalore, Karnataka, India. She’ll be working on surfacing the instance actions in the OpenStack dashboard through the Horizon project with our second-time mentor, Julie Pichon. Anna says, “It’s a wintry December in Bangalore, India. There is a gloomy, cold, and yet pleasant atmosphere. There is a small window in front of me, and I think it’s most likely to rain after sometime. I see my neighbours are scurrying up to renovate their house. I sip up my warm tea, and I have some books on my right shelf.”

Sayali Lunkad will be working on adding sparklines to the Dashboard, mentored by Ladislav Smola. Sayali goes by sayalilunkad on IRC and is located in Pune, Maharashtra, India. Sayali says, “I read this mail just as I woke up. I am in my room from where I see the sun up in the sky and parrots and crows in my terrace garden which is connected to my room. It is a pleasant morning, hope everyone has a good day!”

In Dallas Texas we find Cindy Pallares-Quezada (cpallares on IRC) She’ll be working on the Queues API Spec for the Marconi project with Flavio Percoco. Cindy says, “As for what’s above my screen, I see my window. Outside my window there’s lots of leafless branches that belong to a big tree (I’m on the second floor of a two story building). The branches are all covered in melting ice. Past the trees there’s a street and a lawn that’s full of lots of fallen trees and is covered in yellow, orange, and green leaves.”

Miranda Zhang (MirandaZhang on IRC) is in Canberra, Australia and will work with Diane Fleming to enhance the API Complete Reference pages and create a comprehensive OpenStack API Guide. She was kind enough to send pictures of her workstation. Miranda says, “Unfortunately, I’m in a room with no window (otherwise I may be able to tell you about the cuddly rabbits running around the campus, it’s hot sunny summer in Australia now), and above the computer screen I’m looking at, there are just walls, so I look around my workstation, they say a picture is worth a thousand words:”
Workstation

While the interns are super important, I have to emphasize how much we should appreciate the mentoring and project identification work that goes into this program. Our mentors are extremely valuable to OpenStack as are the ideas for 3-month projects. Thanks to everyone who worked together to get these ideas ready and thanks in advance to the mentors and interns who make this project so worthwhile.

Women of OpenStack, Why?

Why do we get together in person each Summit? Let me tell you. A picture is worth a thousand words, so here are some pics from our Women of OpenStack boat outing Monday night on the harbor. The grey fog was everywhere and we couldn’t go on deck because it was just too wet. The buildings lighting up are an amazing sight, you can hardly capture the lights in photos. And I can hardly capture the value of getting together with other women in OpenStack at the Summit, but here goes.

Untitled

We had a great time on the boat, and at happy hour afterwards I had an awesome chat with a woman from IBM who is pretty much my neighbor! It’s a small world with tight connections in Austin for high-tech women. It seems impossible with the numbers game we’d know each other’s schools, streets, neighborhoods, and so on, but in reality we’re rare enough birds of a feather that it is natural for us to get together and know each other well.

Why do we get together apart from the rest of the conference? We have a couple of themes for our meetups, we talk about outreach to more women, especially in education as early as elementary school and definitely through college. Also, I got to meet our GNOME Outreach Program for Women intern, Terri Yu, in person! That’s a huge part of these in-person gatherings, getting to know each other personally. But we also want to find concrete ways to make our meetings meaningful. We talk about a few tracks for our goals – outreach, education, career planning and mentoring. We came up with some ideas for our goals, and we keep discussing each Summit. It’s like a design summit session for women of OpenStack. In between Summits we stay in touch on LinkedIn though I also serve as an API, ha ha.

We look for speaking opportunities for women in the cloud. We have held workshops geared towards outreach to women, introducing lots of technical women to OpenStack. For example, this past year Iccha Sethi, Jessica Lucci and I ran a workshop at the Grace Hopper Open Source Day, and Anita Kuno, Lyz Krumbach Joseph and Ryan Lane ran a CodeChix workshop. We generally forge the bonds that hold together a common minority by talking about schools, parenting, gin as a vegetable, shoes, traveling, and how does this OpenStack Neutron plug-in work, anyway?

There are so few of us that we need to be diligent about our outreach and staying connected. I blogged about a question related to under representation of minorities in the Technical Committee on my Reflecting on the OpenStack Summit in Hong Kong. We need to be hyper-vigilant about imposter syndrome, uncovered by researchers who found that many high-achieving females tended to believe they were not intelligent, and that they were over-evaluated by others. Believe me, I have to fake it to make it daily.

Our culture as a community may reward the most confidence, but in reality as we grow as a community it’s important to understand that some cultures don’t view confidence in the same way, and some people will not naturally exude confidence. We’re also looking at English-as-a-second-language increasing in prevalence in our community, and a former OPW (Outreach Program for Women) intern Anita Kuno recently edited our Technical Committee charter to be gender-neutral. All of this matters, all of these actions answer the valid question, “Why?” I hope you’ll join us in outreach efforts, together we make OpenStack better for all contributors.

OpenStack Operations Guide now an O’Reilly Early Edition

You remember the crazy feat we’ve pulled off twice now, writing a book in five days? Well, the Operations Guide is now available from O’Reilly as an Early Release. Get a free downloadable copy at docs.openstack.org/ops/.

9781491947685_ER

What does this mean, you ask? You can download a copy now that shows you the state it’s in today, and then stay tuned for the next few months while the authors and editors update it, making it more polished, more clear, and more accurate for the Havana release. Plus, glory be, it’ll have an index. We should be able to release a few fully edited chapters at a time as we work, and our goal is to continually publish our HTML and PDF version by sharing the content across Gerrit and Github.

O’Reilly’s collaborative authoring system is called Atlas, and it is backed by Github. Our authoring system is backed by Gerrit with our review process in place managed by the docs core team. We’re working through the workflow that will enable synchronization between Git and Gerrit so that you too can be a part of this book. Get your writing hats on and typing fingers nimble.

On Twitter last night in Hong Kong, I tweeted out the link to the book and asked the question, what is the animal on the cover? My next tweet then hinted that it’s a distant relative of the animal on the cover of Deploying OpenStack. Do you know what it is?

It’s an agouti! They can jump straight up six feet in the air! With those feet I believe it. Agouti’s are related to guinea pigs. Everett Toews and I just call it the “big butt rat.” Heh. I hope you’ll get behind our guinea pig experiment with book making while we all work hard to bring you best practices and hard-earned lessons learned about operating OpenStack clouds.

OpenStack at the Grace Hopper Conference

I love reporting back from events where we grow our inclusive contributor base! On the Saturday after the Grace Hopper Conference, four of us ran a workshop to onboard future OpenStack contributors. Grace Hopper is a celebration of women in computing and over 4500 women attended the conference this year, showing great growth over the years. Iccha Sethi came up with the idea way back in April and we organized our workshop in the months leading up to the event. This year is the first year I’ve ever attended such a conference and I really enjoyed the experience, writing about it on the Rackspace developer blog.

Here is a photo of our group of merry patch-makers:


There were a dozen open source projects there for 200 participants total. For OpenStack, Rackers Iccha Sethi, Jessica Lucci, Ashwini Shukla and I all served as technical support to the ten people who participated. For starters, Iccha presented about OpenStack, using the great decks from openstack.org/marketing. Next, we ran through introductions and a short icebreaker activity where we did a cloud simulation activity. Everyone enjoyed acting like cloud servers passing red Rackspace squishy balls like they were files on a network.

Then we settled into our laptops for the main workshop, getting DevStack running on a bunch of Rackspace Cloud Servers and working on a first patch! By the end of the day, we had two new patches up for Glance, the Image Service project. We would have had a few more patches in if mid-afternoon flights hadn’t got in the way. Here are two of our happy patchers:

We also had Susan Lauber in our group, who is one of the first OpenStack trainers ready to give OpenStack training through RedHat. The Foundation sent OpenStack stickers and the newest OpenStack t-shirts which flew off the tables! It was so great to see so many women working together on OpenStack. I’m looking forward to the OpenStack Summit where we can see even more people in person. If you’re attending the Summit in Hong Kong please save the date for the next Women of OpenStack gathering – Monday, November 4, 5pm-7pm. Details will be shared soon to all Summit registrants.

The conference and open source day was full of recruiting opportunities for the GNOME Outreach Program for Women. I’ve been inviting OpenStack organizations to sponsor an intern, and I wanted to also ask through this blog. If you’d like to get involved with the Outreach Program for Women, there are two opportunities that come to mind immediately. We have some mentors in mind but always want good ideas from mentors for projects that an intern could complete in 3 months. Also, each internship spot is sponsored at $5750 twice a year. If you’d like to donate, please go to http://gnome.org/opw/ and click on Become a sponsor! Let the admins know by October 10th if you are interested in joining the program.

OpenStack Security Guide now available!

The legendary book sprint method has come through again! This past week in a bunker, I mean, secure location near Annapolis, a team of security experts got together to write the OpenStack Security Guide. I’m pleased as can be to have the privilege of sharing the epub with you here and now, the evening of the fifth day!

Download the epub file and start reading. One of the goals for this book is to bring together interested members to capture their collective knowledge and give it back to the OpenStack community.

This cover gives you a glimpse of the amazing feat this team pulled off. We’ll have HTML and PDF in the next couple of weeks to fulfill your multi-output consumption wants and needs. For now, fire up your ereader, and start reading! The team wants your input.

Lessons, Learning, and Long Views for Internship Programs

In January 2013 the OpenStack project welcomed aboard three interns and excitedly assigned them to work on fairly complex projects in our first attempt at an organized project-level internship program. The OpenStack Foundation participated as one of the organizations with the GNOME Outreach Program for Women and learned quite a few lessons during the six months internship period.

By February, two of the interns had learned the tough lesson of what happens when coordinated work efforts move at a fast pace. For example, Laura Alves, an API documentation intern had a patch with a manually created WADL for the Networking project nearly completed. She started requesting reviews from the core developers. We soon discovered that the devs were working on an automated method for creating the WADL. It certainly took some quick communication and coordination to make sure her work wasn’t wasted. Her efforts certainly weren’t wasted but it also hasn’t landed quite yet either. Lesson learned: internship projects are difficult to scope and it’s nearly impossible to set aside tasks in a reserve area just for interns.

Still more lessons learned were that the timing of code freeze dates landing prior to the internship’s completion made for a steep on ramp for new interns with early deadlines. We also found that interns can contribute so much right away with their fresh perspective — and they created such valuable blog entries for newcomers, like Logging and debugging in OpenStack by Victoria Martínez de la Cruz,  so they’ll be helping more newcomers for months.  We pulled all our lessons learned together for a “What Everyone Should Know About OpenStack Internships” panel session at the Summit in Portland.

One of the takeaways from the Summit was to learn more about mentoring from Katy Dickinson, and the blog at MentorCloud where she is Vice President has been very valuable to learn from as we continue to shape our plans for interns wanting to learn and contribute to OpenStack. Katy attended our brainstorming session at the Summit and gave us very useful suggestions. We surveyed outgoing interns and are working on a plan to coordinate early and often to identify and promote natural mentors in the OpenStack community.

The more you look for internships and mentors in OpenStack, the more you’ll find. Cisco has interns working on OpenStack projects each summer. One OpenStack intern, Emilien Macchi, at StackOps went on to do a graduate part-time internship at eNovance. Rackspace has interns working on multiple OpenStack projects.

The Foundation is continuing the involvement in the Outreach Program for Women also in the northern hemisphere’s summer edition: Terri Yu started working on the Ceilometer project with Juilan Danjou at the end of May: be sure to welcome her! Look for more opportunities to connect the dots with interns and mentors in the coming months. If you have funds for travel so interns and mentors can meet each other in person, let Stefano Maffuli know. If you have a great intern story to tell, please let us all know.

We Did It: Zero to Book in Five Days

OpenStack Operations Guide Call me crazy, call me maybe, but we did it! We have a 50,000 word book, 230 pages long, now available for download in your favorite ebook format, or purchase a printed copy if you like the no-batteries-required version. Go to http://docs.openstack.org/ops/ to get a copy and watch a video we made on day four.

We started the week off with a cookout at Everett Toews’s house. I transposed the house numbers and walked up to the wrong house, rang the bell and everything! A nice Texan lady told us we looked like we were going to have fun but the party wasn’t at her house. Woops! We found the right house on the same street and had a great time. The evening was complete with peach cobbler as we nervously awaited our fate: Could we complete a book in a week?

On Monday we assembled to find out. In a room with an entire wall of white board, our facilitator Adam Hyde unwrapped packs and packs of sticky notes with fresh markers. He introduced the book sprint process and said that he has done about 55 of these. He also said we may not get the book we thought we would going in, but by the end we will get the book we need. Sure enough, we collectively wrote about 10,000 words a day, bringing in all the content we could, revising, reshaping, rewriting, until it all hung together as a real book.

Our hope is that it is the book we all need, that it fills a gap for an under-served audience, the operators of clouds. We want your input, so start reading!

 

 

Bring on the Crazy: Zero to Book in Five Days

Well, since my team mate Everett has outed me as crazy (yes, it’s true), I think I’ve got some ‘splaining to do! It’s true, we’re crazy, but we’ve got to write that operator’s guide — for operators by operators. And if you know ops folks like I do, you realize quickly that these guys have hardly any time to write down their notes! We’re going to pluck them from their day jobs, fuel them with coffee, BBQ, and TexMex, and get to writing.

I’ve run doc sprints for OpenStack at various times on different scales, but this one is highly focused. So highly focused in fact that I’ve turned down people who wanted to attend but hadn’t run clouds day-to-day. Sorry guys! Super hyper focus, blinders on.

I had originally put the proposal together for the Google Summer of Code Doc Summit, which I attended in 2011, but out of 30+ applying organizations, we weren’t selected. Undaunted, I revised the proposal for the OpenStack Foundation to consider, and they are funding it!
1-IMG_3304
We’re gathering in the Willie Nelson room at the Austin Rackspace office next week, and we’re going to try a tool called BookType, hosted by Source Fabric. It’s the same tool I’ve worked with for book sprints with FLOSS Manuals, and it’s made specifically for sprinting. We’re using a pre-installed instance of it at http://openstack.booktype.pro. If you look at it today, it’s empty except for a Test book sandbox. By next week it’ll be bursting with content! The outline we’re working with to start is at https://etherpad.openstack.org/EssexOperationsGuide. Thanks to everyone who has reviewed it and commented so far.

You all are welcome to watch our progress next week at at http://openstack.booktype.pro and offer editing and reviewing as we go. Please realize it’s a pressure cooker of a week, and a real challenge. I’m saying, be helpful and encouraging so we can be productive and accurate. Once we’re done, ship it! We’ll have copies of the book available (likely for a donation initially to cover costs) by the end of next week.

If you want to hear all the gory details, we have a few opportunities. Next week, if you’re in Austin, come see us at the Austin OpenStack Meetup on Wednesday night. Then, at the Summit, we want to bare our souls at a panel titled, On Writing the OpenStack Operations Manual in 5 Days. Come see if we are crazy, or driven there this week.

Back to top