Tag: documentation

How to Use Ask OpenStack

September 23rd, 2013 — 5:41pm

We’re continuously building together “The best place on the Internet to find answers to common OpenStack problems”: our Question&Answers site Ask OpenStack is such place and needs everybody’s help. Ask OpenStack is a collaborative effort, think of it like a wiki where pages are made only of questions and answers. Anybody with more than 100 karma points can fix a question or an answer and anybody can gain karma points by getting votes on answers and/or questions.

We have collected some suggestions to use for those that ask questions and those that answer in our wiki. The sum of it is:

If you’ve used Ask OpenStack to ask questions or to give answers, please let us know what you think and how you would see it improved in the comments below.


Remember to vote good questions and answers on Ask OpenStack!

Comment » | community, Documentation

Bring on the Crazy: Zero to Book in Five Days

February 21st, 2013 — 4:29pm

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!
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.

Comment » | Communication, Documentation

OpenStack Community Weekly Newsletter (Oct 12-19)

October 19th, 2012 — 4:45pm

Highlights of the week

Coverage of OpenStack Summit

This was a busy week for all of OpenStack members. A few reports from the community:

Collaboration in Action: Weaving Proven Tech Into OpenStack’s Fabric

The story of OpenStack community’s collaboration at the Design Summit to make better clouds as told by Alex Glikson, leading a research group at IBM Haifa Research Lab.

OpenStack Document Translation Guide

OpenStack uses Transifex to manage translations. OpenStack Manuals are in DocBook format. We slice the documents into short statements, then use Transifex to manage the translation process, and finally converge the translated content into a new copy of DocBook, which will used to generate HTML and PDF versions. The easiest way to contribute to OpenStack is to start by translating the manuals. Getting started is super easy.

Tips and tricks

Upcoming Events

Other news

Soundtrack of the week

‘Cloud Anthem’ by Dope’n’Stack

The weekly newsletter is a way for the community to learn about all the various activities occurring on a weekly basis. If you would like to add content to a weekly update or have an idea about this newsletter, please leave a comment.

Comment » | Communication, community, Newsletter

Starter docs and articles

May 21st, 2012 — 1:44pm

I wanted to send a note out to discuss the growth of all the starter docs and “articles” on a particular topic. Thanks all who are sending these as links to the mailing list or tweeting ‘em. We are listening.

The doc team has been discussing ways to ensure we help people find what they seek while still getting high-quality content into the “official” documentation. Here are some ideas. I’d like to get input from our wider community as well.

What we’re doing:

  • Add a “Where do I start?” section to the docs landing page. Let us know what you think of this approach by taking a look at the pending review. We discussed quite a bit a more friendly approach to the docs site but I haven’t identified a web dev and designer to do the re-do, contact me if you’re interested.
  • Reach out to writers and where licensing allows and something “official” is not already documented, bring the content into the official docs. We’ve done this a few times now, an example is how to custom brand the OpenStack Dashboard.
  • Add link to helpful blog entries to a “BloggersTips” wiki page.
  • Expand the install/deploy guide to include more distros so the “single distro” guides can standalone. This effort is still a work in progress.
  • Hastexo has offered to write a separate high availability (HA) guide, so we won’t bring in their 12.04 “all in one” install guide after all, since the CSS OSS Starter Guide covers a similar scenario.
  • Remove “articles” from RST docs. (Currently nova only, in further discussion with the Project Technical Leads, QA and CI team leads.)
  • Add blog URLs to the Google Custom Search Engine at http://docs.openstack.org. I took this as an action item from our last doc team meeting.

What we’ve discussed:

  • Removing redundant docs. At the Design Summit, members of the nova core team asked for removal of “article” style RST documents from the nova source repo, creating a more doc-string based nova.openstack.org. Members of the swift core team, when asked, did not want to go to this architecture. I haven’t specifically asked all the PTLs on this particular item. So there’s still a potential problem here of consistency, where to write what, and having all the project.openstack.org sites that aren’t really tied together. I don’t have a good solution to suggest just yet but know we’re thinking about this particular problem. One idea was to have devs who want to write compose WordPress “articles” and that would aggregate together, but we haven’t found an ideal implementation (design is fine, working code, not so much).
  • Setting up a separate WordPress blog for documentation only. Apparently the aggregation tools just don’t give us all the requirements for version labels, bringing in one blog entry at a time (RSS feeds are needed), and so on.
  • Setting up a “support knowledge base” article site such as http://support.mozilla.org. We discussed this at the last doc team meeting. It seems to solve a lot of problems we have, but my current thinking (which of course can change) is that a support KB is for troubleshooting articles, while the “official” docs should create a happy path. These are two different scenarios, and I’m pretty sure the docs team cannot take on the support scenario with our current resources. A support knowledge base with translation built-in will go a long way in supporting our growing base, so this is important to me, but not in the Folsom plans currently.

I’ll follow up with each PTL for the docstring discussion, and welcome all input. Thanks for reading this far, and thanks for the docs. Now get started!

Starting line

Comment » | community, Development, Documentation

Under the hood of Swift: the Ring

February 15th, 2012 — 3:45am

This is the first post in series that summarizes our analysis of Swift architecture. We’ve tried to highlight some points that are not clear enough in the official documentation. Our primary base was an in-depth look into the source code.

The following material applies to version 1.4.6 of Swift.

The Ring is the vital part of Swift architecture. This half database, half configuration file keeps track of where all data resides in the cluster. For each possible path to any stored entity in the cluster, the Ring points to the particular device on the particular physical node.

There are three types of entities that Swift recognizes: accounts, containers and objects. Each type has the ring of its own, but all three rings are put up the same way. Swift services use the same source code to create and query all three rings. Two Swift classes are responsible for this tasks: RingBuilder and Ring respectively.

Ring data structure

Every Ring of three in Swift is the structure that consists of 3 elements:

  • a list of devices in the cluster, also known as devs in the Ring class;
  • a list of lists of devices ids indicating partition to data assignments, stored in variable named _replica2part2dev_id;
  • an integer number of bits to shift an MD5-hashed path to the account/container/object to calculate the partition index for the hash (partition shift value, part_shift).
List of devices

A list of devices includes all storage devices (disks) known to the ring. Each element of this list is a dictionary of the following structure:

Key Type Value
id integer Index of the devices list
zone integer Zone the device resides in
weight float The relative weight of the device to the other devices in the ring
ip string IP address of server containing the device
port integer TCP port the server uses to serve requests for the device
device string Disk name of the device in the host system, e.g. sda1. It is used to identify disk mount point under /srv/node on the host system
meta string General-use field for storing arbitrary information about the device. Not used by servers directly

Some device management can be performed using values in the list. First, for the removed devices, the 'id' value is set to 'None'. Device IDs are generally not reused. Second, setting 'weight' to 0.0 disables the device temporarily, as no partitions will be assigned to that device.

Partitions assignment list

This data structure is a list of N elements, where N is the replica count for the cluster. The default replica count is 3. Each element of partitions assignment list is an array('H'), or Python compact efficient array of short unsigned integer values. These values are actually index into a list of devices (see previous section). So, each array('H') in the partitions assignment list represents mapping partitions to devices ID.

The ring takes a configurable number of bits from a path’s MD5 hash and converts it to the long integer number. This number is used as an index into the array('H'). This index points to the array element that designates an ID of the device to which the partition is mapped. Number of bits kept from the hash is known as the partition power, and 2 to the partition power indicates the partition count.

For a given partition number, each replica’s device will not be in the same zone as any other replica’s device. Zones can be used to group devices based on physical locations, power separations, network separations, or any other attribute that could make multiple replicas unavailable at the same time.

Partition Shift Value

This is the number of bits taken from MD5 hash of '/account/[container/[object]]' path to calculate partition index for the path. Partition index is calculated by translating binary portion of hash into integer number.

Ring operation

The structure described above is stored as pickled (see Python pickle) and gzipped (see Python gzip.GzipFile) file. There are three files, one per ring, and usually their names are:


These files must exist in /etc/swift directory on every Swift cluster node, both Proxy and Storage, as services on all these nodes use it to locate entities in cluster. Moreover, ring files on all nodes in the cluster must have the same contents, so cluster can function properly.

There are no internal Swift mechanisms that can guarantee that the ring is consistent, i.e. gzip file is not corrupt and can be read. Swift services have no way to tell if all nodes have the same version of rings. Maintenance of ring files is administrator’s responsibility. These tasks can be automated by means external to the Swift itself, of course.

The Ring allows any Swift service to identify which Storage node to query for the particular storage entity. Method Ring.get_nodes(account, container=None, obj=None) is used for identification of target Storage node for the given path (/account[/container[/object]]). It returns the tuple of partition and dictionary of nodes. The partition is used for constructing the local path to object file or account/container database. Nodes dictionary elements have the same structure as the devices in list of devices (see above).

Ring management

Swift services can not change the Ring. Ring is managed by swift-ring-builder script. When new Ring is created, first administrator should specify builder file and main parameter of the Ring: partition power (or partition shift value), number of replicas of each partition in cluster, and the time in hours before a specific partition can be moved in succession:

swift-ring-builder <builder_file> create <part_power> <replicas> <min_part_hours>

When the temporary builder file structure is created, administrator should add devices to the Ring. For each device, required values are zone number, IP address of the Storage node, port on which server is listening, device name (e.g. sdb1), optional device meta-data (e.g., model name, installation date or anything else) and device weight:

swift-ring-builder <builder_file> add z<zone>-<ip>:<port>/<device_name>_<meta> <weight>

Device weight is used to distribute partitions between the devices. More the device weight, more partitions are going to be assigned to that device. Recommended initial approach is to use the same size devices across the cluster and set weight 100.0 to each device. For devices added later, weight should be proportional to the capacity. At this point, all devices that will initially be in the cluster, should be added to the Ring. Consistency of the builder file can be verified before creating actual Ring file:

swift-ring-builder <builder_file>

In case of successful verification, the next step is to distribute partitions between devices and create actual Ring file. It is called ‘rebalance’ the Ring. This process is designed to move as few partitions as possible to minimize the data exchange between nodes, so it is important that all necessary changes to the Ring are made before rebalancing it:

swift-ring-builder <builder_file> rebalance

The whole procedure must be repeated for all three rings: account, container and object. The resulting .ring.gz files should be pushed to all nodes in cluster. Builder files are also needed for the future changes to rings, so they should be backed up and kept in safe place. One of approaches is to put them to the Swift storage as ordinary objects.

Physical disk usage

Partition is essentially the block of data stored in the cluster. This does not mean, however, that disk usage is constant for all partitions. Distribution of objects between the partitions is based on the object path hash, not the object size or other parameters. Objects are not partitioned, which means that an object is kept as a single file in storage node file system (except very large objects, greater than 5Gb, which can be uploaded in segments – see the Swift documentation).

The partition mapped to the storage device is actually a directory in structure under /srv/node/<dev_name>. The disk space used by this directory may vary from partition to partition, depending on size of objects that have been placed to this partition by mapping hash of object path to the Ring.

In conclusion it should be said that the Swift Ring is a beautiful structure, though it lacks a degree of automation and synchronization between nodes. I’m going to write about how to solve these problems in one of the following posts.

More information

More information about Swift Ring can be found in following sources:
Official Swift documentation – base source for description of data structure
Swift Ring source code on Github – code base of Ring and RingBuilder Swift classes.
Blog of Chmouel Boudjnah – contains useful Swift hints

Comment » | Documentation

Documentation Contributors Styling Ts

September 26th, 2011 — 2:38pm

Why give your time and efforts to an online community? Researchers like Peter Kollock have identified and studied reasons for people to contribute to online communities. I try to keep the basic principles of online participation in mind for documentation contributors all the time, and find ways to recognize the people making a difference with the docs. The motivating reasons for contributing to technical doc or offering technical support in a community include:

1. Reciprocity – Help out others who will help you later or already did help you out.
2. Reputation – Build your reputation as an expert in a given area.
3. Efficiency – Write it down so you save time later, either your own time or others’ time.
4. Attachment – Feel like you’re part of a bigger mission and vision.

It’s within these motivating reasons to find a place where you belong that prompted me to send some t-shirts out last month. I also want to recognize their efforts here on the blog! Here is the CSS Corp Open Source Service Team sporting their OpenStack t-shirts in a team photo, led by Murthyraju Manthena (far left). This team contributed the OpenStack Compute Starter Guide, which quickly jumped to the top ten list in the web stats. They’re working hard on revisions for Diablo, and this manual was a great addition to the OpenStack technical library for the Cactus release.

CSS Corp OSS Team led by Murthyraju Manthena






There’s also the sense of reciprocity – giving back your info since you got Volumes working in your environment. Here’s Razique Mahroua sporting his shiny new ringer T as well, after re-vising the entire Volume Management section of the Compute Administration Manual.

Wearing your OpenStack t-shirt is a great way to show you are a Stacker. I realize that sending t-shirts to contributors can seem like a small token of appreciation for the sweat poured into docs, but I like to send them any way when I’m especially impressed with the dedication. These guys are also building a great reputation as OpenStack knowledge experts. They are also a huge reason why the number of doc contributors has jumped from six to nearly twenty in six months’ time!

Comment » | community, Documentation

OpenStack Documentation Blitz

September 12th, 2011 — 5:20pm

I had a great idea come across my radar this week – a Documentation Blitz! I’ve been working on case studies for a second edition of my book, Conversation and Community: The Social Web for Documentation, and in one of the case studies from Sarah Maddox at Atlassian, I uncovered a gem of an idea. From Sarah:

We have also held a couple of documentation blitz tests. This is a very successful way of involving the development and support teams in testing the documentation just before the release date. The technical writers set up a plan, including a list of the documents to focus on and a couple of ways people can give us feedback. We usually include an IRC channel, as well as wiki pages and comments, so that the engineers can choose the way that suits them best. We allocate a time period, usually just an hour, and everyone dives into the documentation. The chat session goes wild, comments fly, and we end up with a lot of useful feedback.

I love this idea and want to experiment with it for OpenStack. Fortunately the timing is just right, with the Diablo release ready for a September 22nd release. So, here’s the plan.

On Monday September 19th, from 2:00-3:00 CST (Monday, September 19, 2011 at 17:00:00):

To get coverage on the other side of the globe, we’ll run the Doc Blitz for a second hour at 11:00 pm – 12:00 midnight CST (Tuesday, September 20, 2011 at 04:00:00).

Let’s go find some doc bugs!


2 comments » | Documentation

Documentation Wrangling and Statistics Sharing

August 31st, 2011 — 11:18am

I’ve been tracking web analytics on the documentation site since we put it up in February, and I thought I’d share some of the more interesting nuggets of data I’ve mined. I believe the documentation statistics offer a crystal ball, a window showing the future of what’s up-and-coming for OpenStack. Let’s gaze together.

Flickr: pasukaru76

The docs.openstack.org site regularly tops 1,700 visits a day which is about 40,000 a month. Nearly 10% of visitors are site regulars, with 9-14 visits in a month, and new visitors account for over a third of the traffic. I find search and content analytics much more interesting than just site traffic, though.

At the top of the docs.openstack.org site is a custom search engine that searches the docs site, the wiki, and each developer doc sites (such as nova.openstack.org). The engine is fine-tuned to only show results for the Cactus release documents in docs.openstack.org/cactus so that there aren’t a lot of duplicates with docs.openstack.org/trunk. Yesterday I further expanded the custom search engine to include the documentation for projects in docs.openstack.org/incubation, namely Keystone, the Identity Service for OpenStack. As a result, you can more easily find Keystone API documentation and Keystone developer documentation. Hopefully it means those of you tweeting that you can’t find the Keystone docs while you’re out shopping with your family can now find them no matter your mobile circumstances!

Last month, the top search term for the docs.openstack.org site was Quantum, which revealed the need for our newly incubated project Quantum to add more documentation. Fortunately Dan Wendlandt is on the case and working on developer and administrator documentation now. Also, the custom search engine gives results on the OpenStack wiki for Quantum.

We also have a rather fancy implementation of custom Event Tracking so I can track search data when a reader searches within a particular manual. We have data starting with mid-June. Popular searches once someone’s within a manual are glance, dashboard, vlan, floating, and zone. Interestingly, terms like accounting and billing show up in both the individual guides search and on the main search. I can extrapolate a couple of items from this type of data:

  1. People recognize project names, and the Image Service (glance) docs are embedded within the Compute book for the Cactus release. For Diablo, the Image Service will have its own set of books.
  2. The Dashboard had been trending for a while, so I put the docs in the Compute books prior to its incubation. That looks to be a good decision still.
  3. Accounting or billing solutions don’t exist in the OpenStack ecosystem yet, but people are certainly searching for them.

Our custom event tracking tells us that we’re also getting about 100 comments a month using the Disqus tool, and users are answering other users, which is excellent, keep it up!

One additional tracking item that I find interesting is that downloading the PDF of the OpenStack Compute Admin Manual is in the top 10 exit pages. I think people get in, download what they need, and get out. PDF output is considerably more popular than I had realized. I guess a lot of people hop on a plane and read docs or want the manual at their bedside table to go to sleep with?

Hopefully this tracking doesn’t creep you out, because the data really can help me shape the future for OpenStack documentation. You can always opt out of these tracking devices, and I’m sure some of you do. Let me know if there are any other documentation insights you would like to know.

Comment » | Documentation, Measurement, Website

Dedicated Doc Day

April 4th, 2011 — 11:13am

Rather than having a doc sprint session at the upcoming Summit, I’ve decided to do a push for docs for Cactus with a single two dedicated doc days this Wednesday, April 6th, and Wednesday, April 13th. I’d like to get us all on the same page with this post. (Ha, page.)

I track my doc tasks with a bunch of Post-it notes on my white board, and I’ve moved a lot from In Progress to Done this release. But I want to have a day dedicated to OpenStack docs to keep adding supporting documentation to the project.

OpenStack doc task board


The priorities for Cactus were clearly on reference documentation for flags and the API for Compute, and for Object Storage, logging information. We’ve had great efforts here which are rolled into the openstack-manuals Launchpad project and automation surrounding flags is available in Nova.

I’ve published a draft for the Compute Admin Guide for Cactus and plan to place a new home page so that readers can peruse either Bexar or Cactus (trunk) documentation. For the dedicated doc day, the scope is narrowed to these topics:

Target Audience

As you well know, OpenStack provides documentation for developers and system administrators both. The RST-sourced documentation is for developers and the DocBook-sourced docs are for system and cloud administrators. This dedicated doc day invites writers for both audiences, with a focus on the topics above.


I’ll be in San Francisco at the headquarters-formerly-known-as-Anso HQ on Wednesday (update: 4/13). We don’t have room for additional writers right now, though, but contact me if you’re up for a group dinner that evening.

After a long day of writing and diagramming, we’ll need libations. I’ll post a place for a meetup in the Mission area of San Francisco once we determine a location.

Closing Haiku

And lastly, a haiku from Daniel Green, who wrote a Doc Sprint haiku for Atlassian and won their doc sprint haiku contest:

No time to eat now.
Should be writing more content.
Too late, never mind.

Comment » | Documentation, Event

Latest Tips for Using OpenStack

December 20th, 2010 — 4:16pm

We’ve seen a lot of development activity in the last couple of weeks for the OpenStack Compute project. It’s a flurry of activity, though no snow flurries appear on the horizon here in Texas. It’s tough to keep up with such an active development community, so I thought I’d write up a blog post with some highlights. Hopefully you won’t think these are early release notes, but there are enough changes afoot that I wanted to get a head start.

Shiny New Bytes for OpenStack Compute

Ah, OpenStack Compute, the land of the free software cloud and the home of the brave cloud pioneers. We’ve seen many improvements lately. The previous preview release of Compute (also known as Nova) had a config file for each service. The latest and greatest code base has consolidated all configuration information into a single nova.conf file. This consolidation makes configuration much simpler, and you don’t have to wonder which config file “won” in a head-to-head matchup.

The install script for developers that Vish Ishaya composed has been folded into the source code base itself in the contrib directory. I was able to walk through it myself, as narrated in this screencast.

We’ve also had a Racker, Wayne Walls, test and contribute an installation script for OpenStack that is available in the contrib directory as well. With it, you can install a cloud controller on Ubuntu 10.04 LTS with prompts for creating the configuration needed for the database, network, and so on, ready for production environments. I’ve walked through it and it is handy.

New Tricks for OpenStack Object Storage

For OpenStack Object Storage, a freshly-landed new feature removes limits on object size – you can retrieve objects larger than 5 GB now. On upload, you still upload in smaller-than-5 GB chunks, but the system “glues” them together to make larger objects for download. You can still use chunks if it makes more sense for your system, and download them in parallel if you don’t want to stream a ton of data in one chunk. This large object support is available in the trunk only, not as a package yet, so we’ll keep testing and cooking it in order to prepare it for the Bexar release in February. There’s a great story of how this feature came into being at The Story of an OpenStack Feature at Programmer Thoughts, John Dickinson’s blog.

Exciting times for OpenStack!

2 comments » | Development, Documentation

Back to top