Quick Start

Get up and running with your first experiment

  4 minute read  

The purpose of this guide is to get you started with StormForge Optimize Pro. In this example, you will use StormForge Optimize Pro to tune the memory and CPU requirements for Postgres. You’ll learn how to:

  • Initialize StormForge Optimize Pro Controller in your cluster.
  • Deploy the Postgres experiment to your cluster.
  • Run trials using machine learning (ML) to determine the best configuration.
  • Compare StormForge Optimize Pro results to a baseline configuration.

If you encounter any issues or require assistance, reach out to us via Slack, or contact us.

Prerequisites

Initialize the StormForge Optimize Pro Controller

After installing stormforge and creating an account, log into your StormForge Optimize account:

stormforge login

When you initialize StormForge Optimize in your cluster, the following resources are created:

  • stormforge-system namespace
  • experiment and trial custom resource definitions
  • ClusterRole and ClusterRoleBinding for the controller service account
  • optimize-controller-manager deployment
  • an authorization secret for the controller

To install the Optimize Pro controller, run:

helm template optimize-pro oci://registry.stormforge.io/library/optimize-pro \
  --namespace stormforge-system \
  --include-crds \
  --values credential-values.yaml \
  --output-dir .

Verify the controller is running:

stormforge check optimize-pro

Create the Experiment

For this experiment, you’ll use the Postgres example, which deploys the Postgres application, creates Roles and RoleBindings (if required for the experiment), and configures an experiment to tune the memory and CPU limits for Postgres. The controller will schedule trials (Kubernetes jobs) using pgbench to generate load against the Postgres instance. Each trial will test a different set of parameters provided by the API. The effectiveness of each trial is gauged by the metrics — in this case, you’ll contrast cost versus duration.

Typically, before you apply an experiment, you generate the RBAC policies that define the users’ permissions for the experiment by running stormforge rbac <EXPERIMENT_FILE>.yaml > <EXPERIMENT_FILE>-rbac.yaml and then apply that file before you deploy the experiment. For this example, an experiment-rbac.yaml file has been generated for you — simply include it in the command, as shown below.

Deploy the Postgres application, RBAC policies, and the experiment by running:

kubectl apply \
  -f https://raw.githubusercontent.com/thestormforge/examples/main/postgres/postgres.yaml \
  -f https://raw.githubusercontent.com/thestormforge/examples/main/postgres/experiment-rbac.yaml \
  -f https://raw.githubusercontent.com/thestormforge/examples/main/postgres/experiment.yaml

You can monitor the progress using kubectl:

kubectl get trials -o wide -w

You should see output similar to this:

NAME                        STATUS      ASSIGNMENTS             VALUES
postgres-example-000   Completed   cpu=1319, memory=1457   duration=7, cost=33
postgres-example-001   Completed   cpu=963, memory=2647    duration=5, cost=29
postgres-example-002   Completed   cpu=2394, memory=1934   duration=5, cost=58
postgres-example-003   Completed   cpu=3508, memory=2654   duration=6, cost=85
postgres-example-004   Completed   cpu=3410, memory=1019   duration=5, cost=78
postgres-example-005   Completed   cpu=2757, memory=2538   duration=4, cost=68
postgres-example-006   Completed   cpu=983, memory=3057    duration=6, cost=30
postgres-example-007   Completed   cpu=373, memory=3065    duration=15, cost=17
postgres-example-008   Waiting     cpu=1198, memory=2701

The trials will run until the experimentBudget is satisfied. This example runs 40 trials. While the trial is running, there may be assignment combinations that are unstable and result in a failure. After the trial is complete, you can view the parameters and the metrics generated from the trial.

View the Results

You can view the results as a visualization in the StormForge app. You can also review the trials that have taken place and decide which parameter makes the most appropriate trade-off, or you can use our recommended configuration. The baseline trial (which is typically used to compare your current configuration to the optimized configurations) will be displayed as a triangle on the results page along with your experiment results. This was set using the baseline field for each parameter in the experiment. You can narrow your results to show only the best trials by using the filter at the upper-right side of the page. These are the trials with the best possible combination of cost and duration, meaning if you hold cost fixed at a given value, we have found the best possible duration. You can choose any best configuration that works for your cost and duration preferences. You might often find that because the metrics are not linearly related, some points give a bigger boost in duration at a similar cost. In this scenario, you might explore all of the options to find the best one for you. After you have choose an optimized configuration, click the point to display the parameters to use in the application manifests.

Congratulations! You just ran your first experiment. Now that you understand the basics, check out the experiment lifecycle or experiment concepts.

Remove the Experiment

To clean up the data from your experiment, simply delete the experiment. The deletion will cascade to the associated trials and other Kubernetes objects:

kubectl delete experiment pg
Last modified May 1, 2023