Skip to content

Config Reference

Jump to bottom
Amirreza Nasiri edited this page Aug 25, 2023 · 1 revision

Welcome to the advanced configuration page. We recommend the following steps to read and understand the configs:

  1. Take a look at Usecase-based Configurations to learn the overall configuration structure.
  2. Read Top-Level Config Structure and Fluent Formats on this page.
  3. Take a look at Complete YAML Reference.
  4. Then take a look at detailed definition of Objects if needed.

Top-Level Config Structure

The Config struct represents the overall configuration options available for simulating specific conditions in a system. It allows users to optionally control the execution of the main process, simulate CPU load, induce memory leaks, configure web servers, and establish plans to avoid repetitive failure configurations.

Field Description Type Default Examples
process Controls the execution of the main process. Determines an initial delay and/or sudden exit of the process. Process - See Process
cpuLoad Simulates the CPU load of the machine. Specifies interval, duration, and load percentage. CpuLoader - See CpuLoader
memoryLeak Simulates the memory leak by consuming machine memory. Specifies interval, duration, and size of the leak. MemoryLeaker - See MemoryLeaker
webServers Array of web servers used to serve defined routes. Can be configured to fail at certain percentages over specific durations and intervals. Array of WebServer - See WebServer
plans Array of plans to avoid re-defining repetitive failure plans. Plans can be referred from webServer, route, cpuLoad, or memoryLeak. Array of Plan - See Plan

Fluent Formats

Fluent Formats are designed to make configuration more intuitive and human-friendly. These formats simplify the representation of common data types like durations, float values, and digital sizes. By offering different ways to define these values, Fluent Formats ensure flexibility and ease of use for users.

FluentDuration

The FluentDuration type is a human-friendly representation of duration, and it allows for a flexible definition using various formats. ou can use combinations like 1h (hour), 2m (minute), 5s (second), 100ms (millisecond), 500ns (nanosecond) and even combine them: "1m8s100ms".

Format Description Examples
Specific Duration A direct representation of a duration. 100ms
Ranged Duration A range between two durations. 200ms to 2s
Array of Durations A set of durations from which one can be picked. `1s, 200ms, 3m100ms`

FluentFloat

The FluentFloat type is designed for a user-friendly representation of floating-point values, like percentages.

Format Description Examples
Specific Float A direct representation of a float value. 20.8
Ranged Float A range between two float values. 5.2 to 40
Array of Floats A set of float values from which one can be chosen. 1.5, 20, 50, 0

FluentSize

FluentSize is used to easily describe digital sizes like memory capacities. You can specify sizes using standard notations like: 50 (bytes), 100Ki (kibibytes), 100K (kilobytes), 5Mi, 60M, 1G, 1Gi, etc.

Format Description Examples
Specific Size A direct representation of a size. 100Mi
Ranged Size A range between two sizes. 100Mi to 1Gi
Array of Sizes A set of sizes from which one can be picked. 20Mi, 150K, 100, 1G

Complete YAML Reference

Here is a YAML configuration that holds all of the possible configurations:

#
# The Process struct offers options for controlling the initial behavior of a process,
# such as introducing a startup delay or simulating a sudden process termination.
#
process:
  #
  # Specifies the initial startup delay for the process.
  # Duration examples: "1s", "500ms to 2s", or "1s, 2s500ms, 4s, 1m"
  #
  delay: 5s
  #
  # Configures the conditions for a simulated sudden process termination.
  #
  exit:
    #
    # Duration after which the process will be terminated.
    # Duration examples: "1s", "500ms to 2s", or "1s, 2s500ms, 4s, 1m"
    #
    after: 4s to 10s
    #
    # The exit code of the process once the specified time is met.
    # Code examples: 1, 20, 50
    #
    code: 20


#
# The WebServer struct describes a simulated web server's behavior, including its routes,
# listening interface, and port, along with potential fault conditions.
#
webServers:
- 
  #
  # Network interface for the server to listen on.
  # Examples: "0.0.0.0", "127.0.0.1", etc.
  #
  interface: 0.0.0.0
  #
  # Port number for the server to listen on.
  # Examples: 80, 8080, etc.
  #
  port: 80
  #
  # The WebServerFault struct is designed to dictate how and when a simulated web server 
  # should fail. This can range from the web server stopping its listening activity and 
  # terminating all connections, to subsequently restarting and listening once again.
  #
  fault:
    #
    # Specifies the probability of server failure. 0 means no failure and 100
    # ensures constant failure.
    # Percentage examples: "21.5", "60 to 90", or "10, 30, 50, 70, 90"
    #
    percentage: 50
    #
    # Duration each decision (to stay failed or to serve) should persist.
    # Ideally more than a second, but flexible.
    # Duration examples: "1s", "500ms to 2s", or "1s, 2s500ms, 4s, 1m"
    #
    interval: 1s
    #
    # Total duration of the web server fault simulation. If set, Duration/Interval
    # determines the number of cycles.
    # Duration examples: "1s", "500ms to 2s", or "1s, 2s500ms, 4s, 1m"
    #
    # duration: 10m
    #
    # List of plan names to sidestep repeated plan declarations. Overrides percentage,
    # interval, and duration fields.
    # When more than one plan is referenced, we'll do AND against the all plans states
    # to determine the final state of the web server.
    #
    # planRefs:
    # - disaster
  #
  # List of HTTP routes for the server with individual fault specifications and response types.
  # Default routes: "/", "/livez", "/readyz", "/healthz".
  #
  routes:
  -
    #
    # Specifies the route path.
    #
    path: "/livez"
    #
    # The RouteContent struct dictates the type of content that a specific HTTP route
    # will provide in its response. This structure can return either static content,
    # provide information about the server and its environment, or both.
    #
    content:
      #
      # Describes the content returned by the route, either static content or 
      # a whoami-style response.
      #
      static: "Hello World!"
      #
      # When set to true, the route returns a "whoami" response detailing info
      # about the application, environment, and incoming request.
      #
      # whoami: true
      #
      # If set to true and whoami is also true, the "whoami" response will include server-specific
      # information, which might be sensitive or undesired in some settings.
      #
      # server_info: false
    #
    # RouteFault dictates potential failure conditions for a given route. It can determine
    # how often and in what manner a route fails to respond accurately to incoming requests.
    #
    fault:
      #
      # Chance of the route failing, with 0 meaning no failure and 100 being constant failure.
      # Percentage examples: "21.5", "60 to 90", or "10, 30, 50, 70, 90"
      #
      percentage: 60
      #
      # The time duration for each decision to fail or succeed should last.
      # Duration examples: "1s", "500ms to 2s", or "1s, 2s500ms, 4s, 1m"
      #
      interval: 500ms
      #
      # Total duration for which the fault settings apply to the route.
      # Duration examples: "1s", "500ms to 2s", or "1s, 2s500ms, 4s, 1m"
      #
      # duration: 5m
      #
      # Adds a response delay regardless of the route's state (successful or failing).
      # Duration examples: "1s", "500ms to 2s", or "1s, 2s500ms, 4s, 1m"
      #
      responseDelay: 1s
      #
      # If the route is failing, it will return server side errors (5xx) as response
      # status code.
      #
      serverErrors: true
      #
      # If the route is failing, it will return client side errors (4xx) as response
      # status code.
      #
      # clientErrors: true


#
# The Plan struct provides configuration options for defining similar failure simulation plans.
# These plans can be referenced by various modules to induce specific conditions.
#
plans:
- 
  #
  # Unique name for the plan, used as a reference elsewhere.
  #
  name: heavy-computing
  #
  # Determines the percentage of failure. Acts as a chance of failing or can be used
  # as a graph of bars.
  # Percentage examples: "21.5", "60 to 90", or "10, 30, 50, 70, 90"
  #
  percentage: 50
  #
  # Specifies the digital storage size. Primarily used by the memory leak module.
  # Size examples: "50Mi", "100 to 20K", or "10Mi, 100Mi, 1Gi"
  #
  size: 100Mi to 500Mi
  #
  # Duration of each plan cycle. Values above one second are recommended.
  # Duration examples: "1s", "500ms to 2s", or "1s, 2s500ms, 4s, 1m"
  #
  interval: 1s
  #
  # Duration of the entire plan. Can be empty for continuous operation.
  # Duration examples: "1s", "500ms to 2s", or "1s, 2s500ms, 4s, 1m"
  #
  # duration: 10m
  #
  # List of detailed steps of the plan to define more complex steps. Runs in serial order.
  # When you specify subPlans, we'll ignore the plan-level specification including percentage,
  # size, interval, and duration.
  #
  # subPlans:
  # - 
    #
    # Determines the percentage of failure. Acts as a chance of failing or 
    # can be used as a graph of bars.
    # Percentage examples: "21.5", "60 to 90", or "10, 30, 50, 70, 90"
    #
    # percentage: "20"
    #
    # Specifies the digital storage size. Primarily used by the memory leak module.
    # Size examples: "50Mi", "100 to 20K", or "10Mi, 100Mi, 1Gi"
    # 
    # size: "100Mi to 200Mi"
    #
    # Duration of each sub-plan cycle. Values above one second are recommended.
    # Duration examples: "1s", "500ms to 2s", or "1s, 2s500ms, 4s, 1m"
    #
    # interval: 500ms
    # 
    # Duration of the sub-plan. Leaving the last sub-plan's duration empty will
    # make it run indefinitely. It can be a good idea to left the last sub-plan's
    # duration empty.
    # Duration examples: "1s", "500ms to 2s", or "1s, 2s500ms, 4s, 1m"
    #
    # duration: 10s
  # -  
    # percentage: "20, 30, 40"
    # size: "200Mi, 300Mi, 400Mi"
    # interval: 1s
    # duration: 10s
  # - 
    # percentage: "80 to 100"
    # size: "800Mi"
    # interval: 2s
    # 
    # The last step doesn't have any duration which directs it to
    # last forever.
    # 
    # duration: 10s


#
# The CpuLoader struct is tailored to simulate CPU load, specifying 
# the degree of load as a percentage, the interval of load cycles, and
# the overall duration of the loading.
#
cpuLoad:
  #
  # Define the percentage of CPU load.
  # Percentage examples: "21.5", "60 to 90", or "10, 30, 50, 70, 90"
  #
  percentage: 60 to 90
  #
  # Define the duration of each load cycle. 
  # Duration examples: "1s", "500ms to 2s", or "1s, 2s500ms, 4s, 1m"
  #
  interval: 5s
  #
  # Total duration of the entire CPU load module. Leave the durration empty to make 
  # the load module last forever.
  # Duration examples: "1s", "500ms to 2s", or "1s, 2s500ms, 4s, 1m"
  # 
  # durration: 10m
  #
  # You can also specify reference to a plan. It will be used instead of the
  # fields above.
  #
  # planRefs:
  # - heavy-computing

#
# The MemoryLeaker struct is designed to configure the simulation of memory leaks,
# specifying the size of memory consumption, the interval of leaks, and the overall duration.
#
memoryLeak:
  #
  # Define the size of the memory leak.
  # Size examples: "50Mi", "100 to 20K", or "10Mi, 100Mi, 1Gi"
  #
  size: 100Mi to 1Gi
  #
  # Define the duration of each leak cycle.
  # Duration examples: "1s", "500ms to 2s", or "1s, 2s500ms, 4s, 1m"
  #
  interval: 5s
  #
  # Total duration of the entire memory leak module. Leave the durration empty to make
  # the memory leaking last forever.
  # Duration examples: "1s", "500ms to 2s", or "1s, 2s500ms, 4s, 1m"
  #
  # durration: 10m
  #
  # You can also specify reference to a plan. It will be used instead of the
  # fields above.
  #
  # planRefs:
  # - heavy-computing

Objects

Plan

The Plan struct provides configuration options for defining similar failure simulation plans. These plans can be referenced by various modules to induce specific conditions.

Field Description Type Default Examples
percentage Determines the percentage of failure. Acts as a chance of failing or can be used as a graph of bars. FluentFloat - 10.5, 20 to 60, 0, 10, 20, 30
size Specifies the digital storage size. Primarily used by the memory leak module. FluentSize - 50Mi, 100 to 20K, 10Mi, 100Mi, 1Gi
interval Duration of each plan cycle. Values above one second are recommended. FluentDuration 1s (One second) 1s, 500ms to 2s 1s, 2s500ms, 4s, 1m
duration Duration of the entire plan. Can be empty for continuous operation. FluentDuration Endless (i.e., not set) 1s, 500ms to 2s 1s, 2s500ms, 4s, 1m
name Unique name for the plan, used as a reference elsewhere. string - disaster, unstable
subPlans List of detailed steps of the plan to define more complex steps. Runs in serial order. Array of SubPlan - See SubPlan

SubPlan

The SubPlan struct provides further granularity in defining failure simulations within a primary Plan.

Field Description Type Default Examples
percentage Determines the percentage of failure. Acts as a chance of failing or can be used as a graph of bars. FluentFloat - 10.5, 20 to 60, 0, 10, 20, 30
size Specifies the digital storage size. Primarily used by the memory leak module. FluentSize - 50Mi, 100 to 20K, 10Mi, 100Mi, 1Gi
interval Duration of each sub-plan cycle. Values above one second are recommended. FluentDuration 1s (One second) 1s, 500ms to 2s 1s, 2s500ms, 4s, 1m
duration Duration of the sub-plan. Leaving the last sub-plan's duration empty will make it run indefinitely. FluentDuration Endless (i.e., not set) 1s, 500ms to 2s 1s, 2s500ms, 4s, 1m

Process

The Process struct offers options for controlling the initial behavior of a process, such as introducing a startup delay or simulating a sudden process termination.

Field Description Type Default Examples
delay Specifies the initial startup delay for the process. FluentDuration - 1s, 500ms to 2s 1s, 2s500ms, 4s, 1m
exit Configures the conditions for a simulated sudden process termination. ProcessExit - See ProcessExit

ProcessExit

The ProcessExit struct defines the circumstances and manner of a process's sudden termination.

Field Description Type Default Examples
after Duration after which the process will be terminated. FluentDuration - 1s, 500ms to 2s 1s, 2s500ms, 4s, 1m
code The exit code of the process once the specified time is met. integer - 20, 1

MemoryLeaker

The MemoryLeaker struct is designed to configure the simulation of memory leaks, specifying the size of memory consumption, the interval of leaks, and the overall duration. This struct also provides the option to refer to predefined plans to avoid redundancy in large-scale configurations.

Field Description Type Default Examples
planRefs List of plan names to avoid redundant plan declarations. Overrides Size, Interval, and Duration fields in favor of referenced plans. Array of string -  
size Specifies the size of the memory leak (memory consumption). The actual total memory usage is not guaranteed to be accurate. FluentSize - 50Mi, 100 to 20K, 10Mi, 100Mi, 1Gi
interval Duration of each leak cycle. A value above one second is recommended. FluentDuration 1s (One second) 1s, 500ms to 2s 1s, 2s500ms, 4s, 1m
duration Total duration of the entire memory leak module. If defined, the Duration divided by Interval gives the number of cycles. FluentDuration Endless (i.e., not set) 1s, 500ms to 2s 1s, 2s500ms, 4s, 1m

Note that the memory consumed during the simulation will be in addition to the amount used by the Kermoo application itself.

CpuLoader

The CpuLoader struct is tailored to simulate CPU load, specifying the degree of load as a percentage, the interval of load cycles, and the overall duration of the loading. This structure also supports referencing pre-defined plans to evade redundant configurations in larger setups.

Field Description Type Default Examples
planRefs List of plan names to sidestep repeated plan declarations. Overrides Percentage, Interval, and Duration fields based on the plan. Array of string -  
percentage Indicates CPU load as a percentage. 0 means no added load and 100 implies utilizing all cores to the max. Precision isn't guaranteed. FluentFloat - 10.5, 20 to 60, 0, 10, 20, 30
interval Specifies the duration of each load cycle. It's advised to be over a second, though any duration is acceptable. FluentDuration 1s (One second) 1s, 500ms to 2s 1s, 2s500ms, 4s, 1m
duration Overall duration of the entire CPU load. When defined, Duration divided by Interval gives the number of cycles. FluentDuration Endless (i.e., not set) 1s, 500ms to 2s 1s, 2s500ms, 4s, 1m

It's worth noting that the actual CPU load during the simulation may not be perfectly precise to the specified percentage.

WebServerFault

The WebServerFault struct is designed to dictate how and when a simulated web server should fail. This can range from the web server stopping its listening activity and terminating all connections, to subsequently restarting and listening once again.

Field Description Type Default Examples
planRefs List of plan names to sidestep repeated plan declarations. Overrides Size, Interval, and Duration fields based on the plan. Array of string - -
percentage Specifies the probability of server failure. 0 means no failure and 100 ensures constant failure. FluentFloat - 10.5, 20 to 60, 0, 10, 20, 30
interval Duration each decision (to stay failed or to serve) should persist. Ideally more than a second, but flexible. FluentDuration 1s (One second) 1s, 500ms to 2s 1s, 2s500ms, 4s, 1m
duration Total duration of the web server fault simulation. If set, Duration/Interval determines the number of cycles. FluentDuration Endless (i.e., not set) 1s, 500ms to 2s 1s, 2s500ms, 4s, 1m

Note: Failure means the server stops listening and terminates connections. Resuming indicates the server begins listening again.

WebServer

The WebServer struct describes a simulated web server's behavior, including its routes, listening interface, and port, along with potential fault conditions.

Field Description Type Default Examples
routes List of HTTP routes for the server with individual fault specifications and response types. Default routes: "/", "/livez", "/readyz", "/healthz". Array of Route Default routes listed See Route
interface Network interface for the server to listen on. string 0.0.0.0 127.0.0.1
port Port number for the server to listen on. int32 80 8080
fault Dictates how the web server should experience failures. Default behavior is to not fail. WebServerFault No failure See WebServerFault

By default, the server does not experience any failures unless a WebServerFault condition is specified.

Route

The Route struct is used to define specific HTTP routes for a web server and dictate how each of these routes behaves, the type of content they provide, and the potential failure scenarios they might simulate.

Field Description Type Default Examples
path Specifies the route path string - /, /livez, /api/v1/readyz
methods List of HTTP methods (e.g., "HEAD", "GET", "POST") for the route. Array of string HEAD, GET, POST PUT, PATCH, etc.
content Describes the content returned by the route, either static content or a whoami-style response. RouteContent - See RouteContent
fault Specifies conditions under which the route should experience failure. RouteFault - See RouteFault

RouteContent

The RouteContent struct dictates the type of content that a specific HTTP route will provide in its response. This structure can return either static content, provide information about the server and its environment, or both.

Field Description Type Default Examples
static Specifies static text to be included in the route's response body. string Hello from Kermoo! your static html content
whoami When set to true, the route returns a "whoami" response detailing info about the application, environment, and incoming request. boolean false -
server_info If set to true and whoami is also true, the "whoami" response will include server-specific information, which might be sensitive or undesired in some settings. boolean false -

Note: The default behavior is to simply return the static message "Hello from Kermoo!" unless Whoami is set to true.

RouteFault

RouteFault dictates potential failure conditions for a given route. It can determine how often and in what manner a route fails to respond accurately to incoming requests.

Field Description Type Default Examples
planRefs List of plan names to avoid redundant declarations. Overrides other fields as per the referenced plan. If there are multiple plans, uses AND logic between them. Array of string - -
percentage Chance of the route failing, with 0 meaning no failure and 100 being constant failure. FluentFloat - 10.5, 20 to 60, 0, 10, 20, 30
interval The time duration for each decision to fail or succeed should last. FluentDuration 1s (One second) 1s, 500ms to 2s 1s, 2s500ms, 4s, 1m
duration Total duration for which the fault settings apply to the route. FluentDuration Endless (i.e., not set) 1s, 500ms to 2s 1s, 2s500ms, 4s, 1m
responseDelay Adds a response delay regardless of the route's state (successful or failing). FluentDuration - 1s, 500ms to 2s 1s, 2s500ms, 4s, 1m
clientErrors If set to true and the route is failing, it will return client-side errors (4xx). boolean false -
serverErrors If set to true and the route is failing, it will return server-side errors (5xx). boolean true -

By default, when a route is in a failure state, it will return 5xx errors unless configured otherwise through ClientErrors or ServerErrors.

Made with 💕 by Amirreza Nasiri

🪱 Introduction

Dive into Kermoo's mischievous world!

🧭 Getting Started

Setup and prepare the chaos!

🛠️ Config Examples

Sample setups to stir some trouble!

🛠️ Config Reference

Your detailed map to controlled chaos!

Clone this wiki locally