Response Protocols 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 Response Protocol YAML file.

​
Quickstart

Here’s a quick sample of a Response Protocol 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

Response Protocols 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 response protocol

​
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

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

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

​
Conditional Branching

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

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

DevelopmentInvestigation