Install

Learn how to install and configure StormForge Optimize Pro

Optimize Pro has been deprecated.
But you can check out Optimize Live:

StormForge Optimize Pro is composed of three parts:

  • stormforge command line tool
  • StormForge Optimize Pro Controller (which runs in your cluster)
  • StormForge API (operated by StormForge)

Prerequisites

  • Kubernetes version 1.19 or later. Optimize Pro might not work as expected with earlier Kubernetes versions.
  • Helm version 3.8 or later
  • kubectl properly configured for your cluster

Install the StormForge CLI tool

Choose one of the two methods below to install the StormForge CLI.

Copy the following command to a terminal window:

# Automatically selects either AMD64 or ARM64 architecture, downloads
# the appropriate binary, then moves it to a location in PATH
{ [ "$(uname -sm)" = "Linux x86_64"  ] && curl -L https://downloads.stormforge.io/stormforge-cli/latest/stormforge_linux_amd64.tar.gz | tar -xz; } ||
{ [ "$(uname -sm)" = "Linux aarch64" ] && curl -L https://downloads.stormforge.io/stormforge-cli/latest/stormforge_linux_arm64.tar.gz | tar -xz; } &&
sudo mv stormforge /usr/local/bin/

Download the appropriate Linux binary and extract the files.

Amd64 | Arm64

Then, run:

sudo mv stormforge /usr/local/bin/

Choose one of the two methods below to install the StormForge CLI.

Download the appropriate Windows binary and extract the files.

Amd64 | Arm64

Then, move stormforge.exe to a folder defined in your Windows PATH environment variable.


Run the following PowerShell install command:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
If ($env:PROCESSOR_ARCHITECTURE -eq "AMD64") { Invoke-WebRequest -Uri "https://downloads.stormforge.io/stormforge-cli/latest/stormforge_windows_amd64.zip" -Outfile "stormforge.zip" }
If ($env:PROCESSOR_ARCHITECTURE -eq "ARM64") { Invoke-WebRequest -Uri "https://downloads.stormforge.io/stormforge-cli/latest/stormforge_windows_arm64.zip" -Outfile "stormforge.zip" }
Expand-Archive "stormforge.zip" "." -WarningVariable $w; if ($w.Count -eq 0) { Remove-Item "stormforge.zip" } 

Then, move stormforge.exe to a folder defined in your Windows PATH environment variable.

Choose one of the three methods below to install the StormForge CLI.

Homebrew:

brew install thestormforge/tap/stormforge

Copy the following macOS install command to a terminal:

# Automatically selects either AMD64 or ARM64 architecture, downloads
# the appropriate binary, then moves it to a location in PATH
{ [ "$(uname -sm)" = "Darwin x86_64" ] && curl -L https://downloads.stormforge.io/stormforge-cli/latest/stormforge_darwin_amd64.tar.gz | tar -xz; } ||
{ [ "$(uname -sm)" = "Darwin arm64"  ] && curl -L https://downloads.stormforge.io/stormforge-cli/latest/stormforge_darwin_arm64.tar.gz | tar -xz; } &&
sudo mv stormforge /usr/local/bin/

Download the appropriate macOS binary and install it using your preferred binary installer.

Amd64 | Arm64

We provide a container image at registry.stormforge.io/library/stormforge-cli (for linux/amd64 and linux/arm64):

docker pull registry.stormforge.io/library/stormforge-cli

If you prefer to use the container image directly, set the STORMFORGE_TOKEN environment variable (from auth create -o token).

To authorize the Optimize Pro Controller running in your cluster, you must first prepare the necessary credentials on your workstation (i.e. where you run the stormforge program from).

Log in

First, you must authenticate your local machine. You can do this via a web-based form:

stormforge login

Alternatively, you can get a one-time use code to enter into a browser from another device:

stormforge login --url

At any time, you can check to see that you can communicate with the API:

stormforge ping

Creating Cluster Credentials

Use the StormForge CLI to register the new access credentials, and direct the output to credential-values.yaml:

stormforge auth create CLUSTER_NAME > credential-values.yaml

You’ll use this credentials file in the next step when you install the Controller using Helm.

Install the StormForge Optimize Pro Controller

The Controller runs within your Kubernetes cluster and communicates with the StormForge API to automatically tune your application parameters.

The Helm chart deploys the Controller, custom resource definitions (CRDs), and sets up necessary role-based access control (RBAC) permissions.

  • 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
helm install optimize-pro oci://registry.stormforge.io/library/optimize-pro \
  --namespace stormforge-system \
  --create-namespace \
  --atomic \
  --values credential-values.yaml

Customizing Installation

When you need to generate and manually apply the manifests, you can generate them and output them to a ./optimize-pro/ directory using helm template:

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

Upgrading, Uninstalling, and other Advanced Topics

Upgrading the StormForge Optimize Pro Controller

Be sure to check our dedicated upgrade page for Optimize Pro Controller updates.

Uninstalling the StormForge Optimize Pro Controller

You can uninstall the Optimize Pro Controller via helm uninstall.

Note that Helm does not delete the CRDs and thus all experiments and trials are left as well. Make sure to delete your experiments and trials first, before uninstall the controller, otherwise the deleting the kubernetes resources may block since the finalizers cannot be run. The following steps take this into account.

Be sure to back up any information in the cluster before uninstalling the StormForge Optimize Pro Controller.

  1. To remove all kubernetes experiments and trials:

    kubectl delete experiments --all-namespaces --all
    kubectl delete trials --all-namespaces --all
    
  2. To remove the Controller from your cluster, run:

    helm uninstall --namespace stormforge-system optimize-pro
    
  3. Delete the CRDs: kubectl delete crd experiments.optimize.stormforge.io trials.optimize.stormforge.io

RBAC Requirements

The StormForge Optimize Pro Controller uses Kubernetes jobs to implement trial runs along with custom resources to describe experiment and trial. The StormForge Optimize Pro Controller needs permission to manipulate these resources in the experiment namespaces. Additionally, the StormForge Optimize Pro Controller must be able to list core pods, services, and namespaces.

You can find the exact permissions required for a particular version of the Optimize Pro Controller by inspecting the Helm chart and output of stormforge rbac FILE.

Last modified February 12, 2024