Runbooks

Complete guide for creating and managing runbooks

This feature is yet to be implemented in the newer version. Please be patient, you will get this feature in future updates.

Runbookss are a sequence of steps designed to handle Kubernetes operations and gain insights into incidents within the cluster. They can be defined through YAML configuration or managed via the Agentkube dashboard. This documentation explains the structure and components of a Runbooks YAML file.

Quickstart

Here’s a quick sample of a Runbooks that you can import into your Agentkube dashboard to get started. Use this as a foundation to create your own custom protocol based on your cluster’s needs: Kubernetes Resource Health Check Protocol

Runbookss can be created in two ways:

1. YAML File Import: Create and import YAML files following the structure defined in this documentation
2. Agentkube Dashboard: Use the intuitive web interface in the Agentkube dashboard to create and manage protocols without writing YAML manually

This guide focuses on the YAML file structure for users who prefer to create or manage protocols programmatically.

File Structure

Root Level Properties

name · string · required

The name of the Runbooks

description · string · required

A detailed description of the protocol’s purpose

steps · array · required

An array of step objects defining the protocol workflow

Step Object Properties

Each step in the steps array has the following properties:

title · string · required

The title of the step

number · integer · required

The step number (must be unique and sequential)

details · string

Detailed description of the step

commands · array · required

Array of command objects to be executed

nextSteps · array

Array of next step objects defining workflow transitions

Command Object Properties

Each command in the commands array has the following properties:

format · string · required

The actual command to be executed

docString · string

Documentation describing the command’s purpose

example · string

Example usage of the command

readOnly · boolean

If true, command cannot be modified (default: false)

NextStep Object Properties

Each object in the nextSteps array has the following properties:

referenceType · string · required

Type of reference: “STEP”, “FINAL”, or “STOP”

targetStepNumber · integer

Required when referenceType is “STEP”

conditions · array

Array of condition strings

isUnconditional · boolean

If true, conditions are ignored (default: false)

Reference Types

The referenceType field can have one of three values:

• STEP: Proceed to another step (requires targetStepNumber)
• FINAL: End the protocol successfully
• STOP: Terminate the protocol

Conditions

Conditions are expressions that determine when a next step should be taken. In the Kubernetes example, conditions are written in natural language for clarity:

• “If any pods are in CrashLoopBackOff status, investigate pod logs”
• “If LoadBalancer services show pending external IPs, check cloud provider integration”
• “If all resources are healthy and properly configured”

Example Usage

Example Protocol

name: Kubernetes Resource Health Check Protocol
description: A comprehensive protocol to check the health and status of Kubernetes resources across namespaces
steps:
  - title: List All Namespaces
    number: 1
    details: Get an overview of all namespaces in the cluster to identify the scope of investigation
    commands:
      - docString: Lists all namespaces in the cluster with their status and age
        example: kubectl get ns --sort-by=.metadata.creationTimestamp
        format: kubectl get namespaces
        readOnly: false
    nextSteps: []

  - title: Check Pods Across All Namespaces
    number: 2
    details: Inspect pod status across all namespaces to identify any issues
    commands:
      - docString: Displays all pods across namespaces with their status, restarts, and age
        example: kubectl get pods -A --sort-by='.status.containerStatuses[0].restartCount'
        format: kubectl get pods -A
        readOnly: false

Best Practices

Step Numbers

1. Sequential Numbering

   Use sequential numbers starting from 1, as shown in the Kubernetes example (1 through 4)

2. Uniqueness

   Ensure numbers are unique within the protocol

Commands

1. Documentation

   Use clear, descriptive docStrings that explain the command’s purpose

2. Examples

   Provide practical examples with useful flags, like sorting and output formatting:

   kubectl get pods -A --sort-by='.status.containerStatuses[0].restartCount'
   

3. Access Control

   Use readOnly flag appropriately to control command modification

Next Steps

1. Flow Definition

   Define clear transitions between steps using conditions

2. Conditions

   Use clear, actionable conditions that guide the operator

3. Terminal States

   Include both FINAL (success) and STOP (critical issues) states

Common Workflow Patterns

Linear Workflow

Linear Flow

nextSteps:
  - referenceType: STEP
    targetStepNumber: 2
    isUnconditional: true

Conditional Branching

Conditional Flow

nextSteps:
  - referenceType: STEP
    targetStepNumber: 3
    conditions:
      - If all pods are Running and healthy, proceed to check services
  - referenceType: STOP
    conditions:
      - Critical issues found requiring immediate attention

Terminal Step

Terminal Step

nextSteps:
  - referenceType: FINAL
    conditions:
      - All resources are healthy and properly configured
    isUnconditional: false

Error Handling

YAML Parser Validation

The YAML parser validates:

• Required fields are present
• Field types are correct
• Step numbers are unique
• Referenced steps exist
• Reference types are valid

Common errors to watch for:

1. Missing required fields
2. Invalid reference types
3. Missing target step numbers for STEP references
4. Duplicate step numbers
5. Invalid YAML syntax

Testing

1. Syntax Validation

   Validate YAML syntax

2. Path Testing

   Test all possible paths through the workflow:

   • Normal flow (all healthy)
   • Error conditions (pod crashes, service issues)
   • Terminal conditions (both FINAL and STOP)
3. Command Testing

   Verify all kubectl commands work as expected

4. Error Handling

   Test error scenarios and condition handling

Assistant

Responses are generated using AI and may contain mistakes.