Parameters

A parameter is an input to an experiment which can be adjusted from trial to trial. Every parameter has a name and a range of acceptable values. The value given to a parameter in a specific trial is sometimes called the parameter assignment.

An experiment must define one or more parameters. Together, the parameters in an experiment define the search space.

Parameter Spec

The parameter spec must contain a name and a value range. Optionally, a baseline value may be specified. If a baseline value is specified, it will be used for the first trial and be tagged with the label baseline=true. This value will be used in the UI to provide a comparison between the metrics measured in subsequent trials.

Additional details for the parameter spec can be found in the parameter API reference.

Concepts

Parameter Types

Parameters can be one of two types: Integer or String.

Integer Parameters

Integer parameters specify a minimum bound, a maximum bound, or both. Both bounds are inclusive, and when either bound is unspecified, it defaults to 0. A parameter for tuning CPU on a container might be defined with both bounds:

spec:
  parameters:
  - name: cpu
    min: 100
    max: 4000

While a parameter for tuning the concurrent garbage collection threads on a Java application might be defined with only a max bound:

spec:
  parameters:
  - name: con_gc_threads
    max: 8

Note: Some fields in Kubernetes objects, such as CPU Request, allow their value to be specified using decimal numbers, such as 0.1, or as an integer with an attached unit, such as 100m (“one hundred millicpus”). Because StormForge Optimize only tunes integer numbers, you must use the latter format.

String Parameters

String parameters specify a finite list of acceptable values, where each value is a string. For example, a parameter for tuning the garbage collection algorithm on a Java application might be defined like:

spec:
  parameters:
  - name: gc_collector
    values:
    - "G1"
    - "ConcMarkSweep"
    - "Serial"
    - "Parallel"

Parameter Constraints

Constraints restrict the assignments that parameters may take relative to one another. Constraints are optional and used in addition to the bounds on individual parameters, such as min or max.

StormForge Optimize supports two types of constraints: Order and Sum.

Order Constraint

The order constraint requires that one integer parameter be strictly larger than another. For example, you can use an order constraint to ensure that a container’s maximum replicas value is always greater than it’s minimum replicas:

spec:
  constraints:
    - order:
        lowerParameter: min_replicas
        upperParameter: max_replicas

Sum Constraint

The sum constraint requires that the sum of two or more parameters not exceed an upper or lower bound. For example, in an experiment tuning CPU on multiple deployments, a sum constraint could enforce an overall cap of 4000 millicpus between both deployments:

spec:
  constraints:
    - sum:
        bound: 4000
        isUpperBound: true
        parameters:
          - name: first_cpu
          - name: second_cpu

Each parameter in the sum constraint may have an associated weight. When a weight is specified for a parameter, the parameter’s value is multiplied by that weight before being summed.

Example

Now that you understand what parameters are and how they can be used, let’s see what they look like in an example .yaml file.

In this example, suppose you’ve decided to tune the frontend and product catalog services CPU and memory resources. These values will become our parameters. You’ll use the existing resource requests as your baseline. This should give you an idea of what the current site can handle. You’ll set the search space as 50-1000 (millicores) for your services CPU. You’ll set the search space as 16-512 (MB) for your services memory.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

apiVersion: optimize.stormforge.io/v1beta2
kind: Experiment
metadata:
  name: shopping
spec:
  parameters:
  - name: frontendCpu
    min: 50
    max: 1000
    baseline: 100
  - name: frontendMemory
    min: 16
    max: 512
    baseline: 64
  - name: catalogCpu
    min: 50
    max: 1000
    baseline: 100
  - name: catalogMemory
    min: 16
    max: 512
    baseline: 64