Skip to content
RunWhen

CodeBundle Basics

Please see Getting Started before referencing this page.

Types of CodeBundles

There are two primary CodeBundles:

  • Service Level Indicator (SLI)
  • TaskSet (Runbook)

Each of these CodeBundles is represented in a single .robot file, which consists of Tasks to perform, along with user-provided Variables and dependent Libraries that are used to support the execution of each Task.

Service Level Indicator CodeBundles

The Service Level Indicator CodeBundle can be described as follows:

  • written in the sli.robot file
  • runs on a scheduled basis, for example, every 30 or 60 seconds
  • is primarily responsible for fetching or generating a metric that is pushed to the RunWhen Platform
  • these metrics can be used to trigger alerts or assist in SLO calculations

For example, a simple SLI CodeBundle might have a task that counts the number of unready pods in a namespace, and then pushes that total value to the RunWhen Platform. That number can then be used to trigger an alert if more than 1 pod is unready.

TaskSet CodeBundles

The TaskSet CodeBundle can be described as follows:

  • written in the runbook.robot file, typically with multiple Tasks
  • runs on-demand, for example, when manually executed by a user, or automatically executed from an Engineering Assistant or workflow (triggered from an alert, webhook, or some other event)
  • is primarily responsible for fetching information, adding details to a report, generating high-quality Issues and Next Steps for handoff to an Engineering Assistant or human escalation

For example, related to the previous SLI use case, the TaskSet CodeBundle would have 1 Task that identifies which deployments have unready pods in the namespace, another Task might fetch a list of events related to each specific unready pod, which can then raise an Issue about the deployment (e.g. Deployment ‘cartservice’ has unready pods) with some Next Steps that are related to the identified events.

CodeBundle Structure

This section looks at a basic CodeBundle to review each core component.

Settings

The Settings section specifies the documentation, metadata, and required libraries.

  • Documentation: Provides a brief summary of the taskset.
  • Metadata: Author, Display Name, Supports (platforms/technologies).
  • Library: BuiltIn, RW.Core, RW.CLI, RW.platform.
  • Suite Setup: Defines a suite-wide setup step to initialize variables and configurations used across tasks.

Keywords — Suite Initialization

Initializes the suite by importing and setting up the necessary user-defined variables (e.g. URL, TARGET_LATENCY, DESIRED_RESPONSE_CODE) via RW.Core.Import User Variable.

Tasks

A list of tasks to execute. Each task should be able to execute independent of each other. Example: “Checking HTTP URL Is Available And Timely” — uses cURL to validate response and latency, then RW.Core.Push Metric to send the score to the platform.

RunWhen Development Tools

The devtools container image contains development tools that help with local testing and replicate platform functionality. For example, you can pull an Environment Variable as a Secret for use with the CodeBundle.

Environment Variables

RW_FROM_FILE — Map secrets to files (e.g. kubeconfig in /~/auth/). Example: export RW_FROM_FILE='{"kubeconfig":"/home/runwhen/auth/kubeconfig"}'

RW_SECRET_REMAP — Remap secret names so the CodeBundle imports a secret by one name but the environment provides it under another. Example: RW_SECRET_REMAP='{"kubeconfig":"MY_KUBECONFIG"}'

RW_ENV_REMAP — Remap environment variable names. Example: RW_ENV_REMAP='{"PROMETHEUS_HOSTNAME":"PROM_HOSTNAME"}'