Jira Server Runbook

[Elaine_Reece]

Hey does anyone use a Runbook for their server upgrades. I'm trying to convince my server admins that we should have one, but they are demanding an example. I can't seem to find on any Atlassian documentation even though at Summit this year they recommended we have one. 

[Bryan Robison]

We create runbooks for most of our technical technical tasks (installs, upgrades, migrations, merges, etc.)

Most runbooks are step-by-step instructions of the process to complete the task so it's important to document as you are testing the upgrade. If it's a complex task like a migration or merge we may even document the steps it takes to create and refresh the test environment.

We also refine the runbook as we go through our test iterations to make sure we haven't missed anything. We use Confluence which makes it easy to track changes as we go.

Once you have a runbook for a given task then you should be able to hand it off to anyone with the proper skills to execute the steps outlined in the runbook. Another advantage is that when it comes time to repeat the task (e.g. upgrade to a new version), you already have the list of steps to complete the work and can start testing and modifying the runbook if necessary. You're not constantly reinventing the wheel.

A typical runbook (ours anyway) follows this structure:

• Pre-flight Checklist - list of items you need to have ready before starting the task (urls, credentials, ssh keys, contact information, access levels (admin, sudo, etc.))
• Communication Plan - what to say, who to notify, when to tell them
• Steps to Complete - in Confluence we format each step with a heading so you can use the table of contents macro to organize and link them. Then we use screenshots, code block and info macros, and detailed descriptions of the work that needs to be done for each step
• Validation - steps to take to validate the task is complete
• Rollback Instructions - steps to take to reverse the task in the event of an issue