Install

Learn how to install and configure StormForge Optimize Pro

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

Linux Binary Download:

Amd64 | Arm64


Linux install command:

# 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/

Windows Binary Download:

Amd64 | Arm64


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.

macOS Binary Download:

Amd64 | Arm64


macOS install command:

# 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/

Homebrew:

brew install thestormforge/tap/stormforge

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

We recommend setting the STORMFORGE_TOKEN environment variable (from auth create -o token) if you want to use the container image directly.

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 June 9, 2023