Tuesday, April 2, 2013 12:23 PMFinding the Corners: The Making of the Puppet Enterprise Deployment GuidePuppet Labs
Like many things at Puppet Labs, the idea for a Deployment Guide for Puppet Enterprise came from our users. By the time I joined the Puppet Labs docs team, most of the heavy lifting of documenting the features and functions of Puppet Enterprise had already been done by documentation wunderkind, Nick Fagerlund. But we were still hearing from users that they needed something to help them start the job of incorporating Puppet Enterprise into their IT ecosystems. A manual is all fine and good when you have a task you're trying to complete, they told us, but what if you don't know what tasks you need to do and when you should do them?
It's a little bit like when you rent a beach house and the kids immediately find a 1,000 piece puzzle in the closet, but there's no box to show you what the puzzle looks like when it's done. With a puzzle, you know what to do next: you dump out all the pieces on the coffee table and start looking for the edges and the corners. To a new user, Puppet Enterprise can be a bit of a puzzle without a box. The manual can tell you the procedures and show you the shape of the pieces, but the Deployment Guide is there to show you what it looks like when it's all put together by helping you find the edges and the corners.
To create the Guide, I started by brainstorming a rough outline, dividing the project of deployment into logical chunks. But to get that outline filled in, I had to turn to the brain-trust that is our Professional Services and Support departments. I was lucky to have folks with collective decades of experience deploying Puppet Enterprise in all sorts of different enterprises right there in the northern half of our offices. With the assistance of Nigel Kersten, our CTO, I identified subject-matter experts in various aspects of a Puppet Enterprise deployment. And then I started in on the task that defines much of a tech writer's day: hounding people until they give up their knowledge. After 12 years or so in this game, my nagging skills are — dare I say — fairly advanced since I understand the stick and I understand the carrot. Especially the carrot (in Portland, this is usually beer or coffee, but sometimes an actual carrot; there are lots of vegetarians here). In fairly short order, I had amassed a very large pile of information, tips, tricks and advice.
This led to a new problem: our Professional Service Engineers and Support staff are opinionated people, and now I had a big pile of opinions, not all of which necessarily agreed with one another. How would I choose what to put in the Guide as the best practice? Admittedly, I flailed about on this question for some time. Like any good piece of software, Puppet Enterprise gives you a number of different ways to complete a given task. Add to that the varying skills and knowledge of Puppet Enterprise users, and the incredible variety of enterprises where it gets deployed, and I found myself neck-deep in some pretty murky water.
Fortunately, a man with a cape and stretchy pants swooped me up in the nick of time — enter long-time PSE Eric Shamow, our Methodologies Lead. With his encyclopedic knowledge of all things Puppet and mad skills forged in the crucible of many deployments, Eric was able to help me sort out all of the information I'd gathered into an authoritative set of best practices and proven procedures.
With that set in hand, I could start filling in my outline and organizing all the info into logical steps. You can see the first results of that in the first two chapters of the Deployment, which cover installing Puppet Enterprise and setting up your work environment. The next chapter to be released will follow a fictional sysadmin as she assumes responsibility for a marketing department's IT infrastructure and brings it under Puppet Enterprise management. After that, I plan to have a chapter on how a sysadmin can get information about the performance and functioning of their deployment using the many reporting tools available in Puppet Enterprise.
There are some exciting new developments around reporting in Puppet Enterprise, so hopefully this chapter will serve as an illustration of powerful new capabilities in Puppet Enterprise that are just being developed. The final planned chapter of the Guide will help you keep things humming along with information about maintenance and troubleshooting a deployment. Look for these chapters to be released in the next month or two.
It's my hope that the Guide will constantly evolve as a living document and that it will grow and improve as new practices come to light and as new features are developed. In particular, I hope that community members outside the walls of Puppet Labs will weigh in with their experience and real-world knowledge. With many hands, we can find all the corners, build the edges, and get the whole picture puzzled together. Then we can get that coffee table cleared off so we can put our beers on it. And maybe some carrots and dip.
No comments:
Post a Comment