You are browsing a read-only backup copy of Wikitech. The live site can be found at wikitech.wikimedia.org

Difference between revisions of "User:SRodlund/Runbooks planning"

From Wikitech-static
Jump to navigation Jump to search
imported>SRodlund
imported>SRodlund
 
Line 1: Line 1:
== Overview ==
== Overview ==
This is a planning page for improving resources for authoring and publishing runbooks on Wikitech
This is a planning page for improving resources for authoring and publishing runbooks on Wikitech. Please see below for page content.
 
<!--


=== Audience ===
=== Audience ===
Line 72: Line 74:
* https://prometheus.io/docs/introduction/overview/ (nice section about wikis)
* https://prometheus.io/docs/introduction/overview/ (nice section about wikis)
* https://prometheus.io/docs/introduction/overview/ (automated runbooks w/Azure)
* https://prometheus.io/docs/introduction/overview/ (automated runbooks w/Azure)
-->


= PAGE CONTENT =
PAGE URL: [[Portal:Cloud_VPS/Admin/Runbooks/]]


= Runbooks for Cloud VPS =


= PAGE CONTENT =
This page contains basic resources for developers who want to author and publish runbooks for Cloud VPS on Wikitech.
Title: Runbooks for Cloud VPS


''You may repeat the overview sentence here''
<!--Make sure to update the cloud vps navigation box w/runbooks-->


{{Cloud VPS nav}}
{{Cloud VPS nav}}
Line 100: Line 105:
*'''Keep them up-to-date.''' Revisit the instructions after each incident to make sure they are clear and accurate.
*'''Keep them up-to-date.''' Revisit the instructions after each incident to make sure they are clear and accurate.
* '''Keep them simple.''' These are sets of detailed instructions, and they do not require extra history or context.
* '''Keep them simple.''' These are sets of detailed instructions, and they do not require extra history or context.
** Publish a separate runbook for each issue or incident
*'''Test them.''' Make sure the instructions are repeatable by others by asking others to follow them and provide feedback.
*'''Test them.''' Make sure the instructions are repeatable by others by asking others to follow them and provide feedback.
* '''Follow a template.''' Make sure your runbooks follow a template, so that people can find and update information easily.
* '''Follow a template.''' Make sure your runbooks follow a template, so that people can find and update information easily.
Line 107: Line 113:
Instructions for each issue or alert should have its own page in order to reduce unnecessary information. You can see an example here with the issue [[Portal:Cloud_VPS/Admin/Runbooks/Check_for_VMs_leaked_by_the_nova-fullstack_test|Check for VMs leaked by the nova-fullstack test]]. Note that the page addresses one issue only.
Instructions for each issue or alert should have its own page in order to reduce unnecessary information. You can see an example here with the issue [[Portal:Cloud_VPS/Admin/Runbooks/Check_for_VMs_leaked_by_the_nova-fullstack_test|Check for VMs leaked by the nova-fullstack test]]. Note that the page addresses one issue only.


You can find a template for creating runbooks here: https://wikitech.wikimedia.org/wiki/User:SRodlund/Runbooks_planning/runbook_template
You can find a template/outline for creating runbooks here: https://wikitech.wikimedia.org/wiki/User:SRodlund/Runbooks_planning/runbook_template


== Where to publish runbooks for Cloud VPS (Option 1)==
== Where to publish runbooks for Cloud VPS (Option 1)==
Line 113: Line 119:
You'll want to make sure that you are publishing your runbook in the correct place. Runbooks intended for admins only should be published in a different space than runbooks that are intended for general users of Cloud VPS.
You'll want to make sure that you are publishing your runbook in the correct place. Runbooks intended for admins only should be published in a different space than runbooks that are intended for general users of Cloud VPS.


When runbooks include information for general users and special instructions for admins, mark any instructions for admins with the following template:
'''Note:''' Many runbooks for Cloud VPS will include procedures that can only be followed by individuals with admin access. In order to avoid confusion and frustration for general users, you should note at the content level when a procedure will require admin permissions.
 
When an entire runbook requires admin permissions to complete procedures, mark it with the following template:
 
{{Remark|The procedures in this runbook require admin permissions to complete.|reminder}}
 
When runbooks include information for general users and special instructions for admins, mark any instructions (inline) for admins with the following template:


{{Topic|Requires admin permissions|#fc3}}  
{{Topic|Requires admin permissions|#fc3}}  
Line 132: Line 144:


== Where to publish runbooks for Cloud VPS (Option 2)==
== Where to publish runbooks for Cloud VPS (Option 2)==
{| class="wikitable"
|+
!Where to publish Cloud VPS runbooks
|-
|[[Portal:Cloud_VPS/Admin/Runbooks/]]
|-
|''Note: This is a subpage of admin documentation. Some procedures may require advanced admin permissions to complete.''
|}
'''Note:''' Many runbooks for Cloud VPS will include procedures that can only be followed by individuals with admin access. In order to avoid confusion and frustration for general users, you should note at the content level when a procedure will require admin permissions.


Cloud VPS runbooks should be published here: [[Portal:Cloud_VPS/Admin/Runbooks/
When an entire runbook requires admin permissions to complete procedures, mark it with the following template:
 
'''Note:''' Many runbooks for Cloud VPS will include tasks and processes that can only be followed by individuals with admin access. In order to avoid confusion and frustration for general users, you should note at the content level when a task or process would require admin permissions.
 
When an entire runbook requires admin permissions to complete tasks, mark it with the following template:


{{Notice|The instructions in this runbook require admin permissions to complete.}}
{{Remark|The procedures in this runbook require admin permissions to complete.|reminder}}
{{Remark|The instructions in this runbook require admin permissions to complete.|gotcha}}
{{Remark|The instructions in this runbook require admin permissions to complete.|reminder}}


When runbooks include information for general users and special instructions for admins, mark any instructions (inline) for admins with the following template:
When runbooks include information for general users and special instructions for admins, mark any instructions (inline) for admins with the following template:

Latest revision as of 19:30, 11 June 2021

Overview

This is a planning page for improving resources for authoring and publishing runbooks on Wikitech. Please see below for page content.


PAGE CONTENT

PAGE URL: Portal:Cloud_VPS/Admin/Runbooks/

Runbooks for Cloud VPS

This page contains basic resources for developers who want to author and publish runbooks for Cloud VPS on Wikitech.


Overview

This page contains basic resources for developers who want to author and publish runbooks for Cloud VPS on Wikitech.

Before you begin

Permissions: Some processes documented in runbooks for Cloud VPS will need varying levels of permission to perform. Make sure you have appropriate permissions to complete your task.

What is a runbook?

A runbook is a detailed set of instructions that explain how to perform a common task or procedure, so it can be easily and accurately repeated by others. Runbooks are particularly useful for incident response operations. Creating runbooks in response to specific incidents, makes it possible for people to repeat the steps in response to similar incidents. Because they are often used to help people respond to incidents quickly, they should be easy to read and follow, consistent, and accurate.

When should you use a runbook?

A runbook should be used whenever a common task or procedure may need to be repeated by mulitple people.

Tips for building useful runbooks

  • Keep them up-to-date. Revisit the instructions after each incident to make sure they are clear and accurate.
  • Keep them simple. These are sets of detailed instructions, and they do not require extra history or context.
    • Publish a separate runbook for each issue or incident
  • Test them. Make sure the instructions are repeatable by others by asking others to follow them and provide feedback.
  • Follow a template. Make sure your runbooks follow a template, so that people can find and update information easily.

Cloud VPS runbook templates

Instructions for each issue or alert should have its own page in order to reduce unnecessary information. You can see an example here with the issue Check for VMs leaked by the nova-fullstack test. Note that the page addresses one issue only.

You can find a template/outline for creating runbooks here: https://wikitech.wikimedia.org/wiki/User:SRodlund/Runbooks_planning/runbook_template

Where to publish runbooks for Cloud VPS (Option 1)

You'll want to make sure that you are publishing your runbook in the correct place. Runbooks intended for admins only should be published in a different space than runbooks that are intended for general users of Cloud VPS.

Note: Many runbooks for Cloud VPS will include procedures that can only be followed by individuals with admin access. In order to avoid confusion and frustration for general users, you should note at the content level when a procedure will require admin permissions.

When an entire runbook requires admin permissions to complete procedures, mark it with the following template:

The procedures in this runbook require admin permissions to complete.

When runbooks include information for general users and special instructions for admins, mark any instructions (inline) for admins with the following template:

Requires admin permissions

Where to publish runbooks for Cloud VPS
Runbooks intended for Cloud VPS Administrators Runbooks intended for general users of Cloud VPS
https://wikitech.wikimedia.org/wiki/Portal:Cloud_VPS/Runbooks/Admin/ https://wikitech.wikimedia.org/wiki/Portal:Cloud_VPS/Runbooks/General/
Note: These tasks and processes in these notebooks require admin permissions to complete. Note: The tasks and processes in these notebooks can typically be run by general users. However, some steps may require admin permissions.

Make sure to add Category:Runbooks to your runbook pages, so they are included with other documentation in this category.

Where to publish runbooks for Cloud VPS (Option 2)

Where to publish Cloud VPS runbooks
Portal:Cloud_VPS/Admin/Runbooks/
Note: This is a subpage of admin documentation. Some procedures may require advanced admin permissions to complete.

Note: Many runbooks for Cloud VPS will include procedures that can only be followed by individuals with admin access. In order to avoid confusion and frustration for general users, you should note at the content level when a procedure will require admin permissions.

When an entire runbook requires admin permissions to complete procedures, mark it with the following template:

The procedures in this runbook require admin permissions to complete.

When runbooks include information for general users and special instructions for admins, mark any instructions (inline) for admins with the following template:

Requires admin permissions

Communication and support

We communicate and provide support through several primary channels. Please reach out with questions and to join the conversation.

Communicate with us
Connect Best for
Phabricator Workboard #Cloud-Services Task tracking and bug reporting
IRC Channel #wikimedia-cloud connect
Telegram bridge
mattermost bridge
General discussion and support
Mailing List cloud@ Information about ongoing initiatives, general discussion and support
Announcement emails cloud-announce@ Information about critical changes (all messages mirrored to cloud@)
News wiki page News Information about major near-term plans
Cloud Services Blog Clouds & Unicorns Learning more details about some of our work
Wikimedia Technical Blog techblog.wikimedia.org News and stories from the Wikimedia technical movement

See Also

Category:Runbooks