[openstack-dev] [Ironic] call for operator-focused docs

Vinay B S (vinbs) vinbs at cisco.com
Thu Aug 7 10:19:56 UTC 2014

Hi Devananda,

I have been working on the documentation of some of the areas you listed. I have updated the bug https://bugs.launchpad.net/ironic/+bug/1323589 by including the other requirements which I haven't documented yet.


-----Original Message-----
From: Devananda van der Veen [mailto:devananda.vdv at gmail.com] 
Sent: Thursday, August 07, 2014 2:02 AM
To: OpenStack Development Mailing List
Subject: [openstack-dev] [Ironic] call for operator-focused docs

Hi all!

Short version: if you have operational knowledge setting up Ironic (either the Icehouse release or current trunk), you can help out a lot right now by sharing that knowledge.

Long version...

I've seen an influx of folks interested in deploying Ironic over the past few months, which is fantastic and awesome and also somewhat scary -- there are clearly people using Ironic who are not also part of its developer community! It has also become increasingly apparent that, while our developer docs are good (or at least "good enough"), our operational docs leave a lot to be desired. Some folks even went back to the old Nova Baremetal wiki, which is a terrible thing because most of what that says is almost similar to Ironic but wrong. (I have updated that to have more bold text about its deprecated status, and will archive the page once that driver is actually removed from Nova.)

During the Icehouse cycle, the core review team waited until close to the release to write docs. While we were focused on developer docs, we also put together some operational docs (kudos to the folks who contributed!). That process worked well since it was our first release, and as developers, it's easy for us to iterate on the developer docs. However, hindsight being what it is, I don't think we knew enough about what users and operators would need, and now I think we will be doing our community a disservice if we don't provide more operator-focused docs soon.

The areas where I'm currently seeing a lot of questions from operators are:

- building the deploy kernel & ramdisk pair // configuring ironic to use them
- how to enroll nodes // what information needs to be supplied
- relationship between ironic and nova scheduler (flavors, capabilities, etc)
- example/suggested neutron configuration for provisioning physical machines
- recommended deployment topology and rationale (service co-location or isolation)
- how to run the nova.virt.ironic driver alongside a traditional hypervisor driver

A lot of this is done by the automation tooling we use every day (devstack and tripleo). However, neither of these are a replacement for a human-readable set of instructions to help a smart person figure out what they're supposed to do, especially if they just want to start using Ironic with their existing OpenStack deployment.

So -- if you're runnig Ironic (outside of devstack or tripleo) or are in the process of figuring that out (and maybe already asking questions in IRC), please consider proposing something to the in-tree doc pages, found here:


Thanks in advance,

OpenStack-dev mailing list
OpenStack-dev at lists.openstack.org

More information about the OpenStack-dev mailing list