📖Runbook Hub

Runbook Hub acts as a central repository within GitHub for organizing and storing runbook definitions, essential for automated troubleshooting and documentation in IT and development operations. A .gp.yaml file at the root of the repository specifies the hub and its runbooks, detailing their purpose, associated selectors for identifying relevant resources or events, and documentation paths. Users can create this file directly on GitHub or via the gopaddle UI, though the latter requires a linked GitHub account. Each runbook, identified by a unique name, links to specific resources or events through JSONPath or Label selectors, guiding towards relevant troubleshooting documentation stored as Markdown files within the repository.

Runbook Hub Illustration

Runbook Hub

A hub is a GitHub repository that holds one or more runbook definitions. A .gp.yaml file in the root directory of the repository in the default branch (Eg. main) defines a runbook hub. Format of the .gp.yaml definition looks like below:

{
   "name":"Runbook Hub for BackOff failures",
   "desc":"Runbooks for container backoff related issues",
   "runbooks":[
      {
         "name":"Pod-Pending",
         "desc":"Runbook for Pod level CrashLoopBackOff and ImagePullBackOff",
         "selectors":[
            {
               "type":"labelSelector",
               "selector":"app=image-pull-failure-pod"
            },
            {
               "type":"jsonPathSelector",
               "selector":"{.status.phase}=Pending"
            }
         ],
         "doc":"backoff/pod-crash-runbook.md"
      },
      {
         "name":"Event-Pulling",
         "desc":"Runbook for ImagePullBackOff event",
         "selectors":[
            {
               "type":"jsonPathSelector",
               "selector":"{.involvedObject.kind}=Pod"
            },
            {
               "type":"jsonPathSelector",
               "selector":"{.reason}=BackOff"
            },
            {
               "type":"jsonPathSelector",
               "selector":"{.type}=Normal"
            }
         ],
         "doc":"backoff/pod-image-runbook.md"
      }
   ]
}

Users can create a .gp.yaml file in the repository directly or create it through the gopaddle UI. In order to create the .gp.yaml file from the gopaddle UI, the GitHub account must be registered in gopaddle.

Runbook

A runbook is documentation that is attached to a Kubernetes resource or an event based on a set of selectors. A runbook name acts as a unique identifier and cannot have spaces.

Selectors

A set of selectors when applied, filters one or more Kubernetes resources or events. Runbooks supports 2 types of selectors:

a. JSONPathSelector: JSON path in a resource specification. Eg.{.reason}=BackOff (or) {.status.phase}=Pending

b. LabelSelector: A key / value pair that matches the labels in the resource metadata. Eg. app=image-pull-failure-pod

Doc

Contains the troubleshooting documentation or knowledgebase associated with the Kubernetes resources or events. Has a .md extension and exists in a folder path relative to the repository root directory.