Install
10 minute read
30-day Free Trial
If you haven’t tried StormForge Optimize Live yet, start your 30-day free trial now at app.stormforge.io/signup!
Also, check out this Getting Started video (3min), which walks you through sign-up and installation, and gives you a quick overview of the insights you’ll get in just 1 hour after installation.
Prerequisites
You’ll need:
- A StormForge Account
- Kubernetes version 1.24 or later
- Helm version 3.14.0 or later
- kubectl properly configured for your cluster
- Cluster-Admin access (for installation only)
- A Kubernetes cluster and the cluster name to install the Agent into
Grant Kubernetes clusters access to these StormForge services endpoints on port 443:
- api.stormforge.io
- in.stormforge.io
- registry.stormforge.io*
(*If you configure the Agent to use an internal registry, you don’t need to grant cluster access to this endpoint).
Are you using minikube or Rancher Desktop?
If so, use containerd
as your container-runtime instead of docker
.
-
minikube: Since the removal of dockershim in Kubernetes release 1.24, minikube’s default docker container-runtime no longer supplies the properly labeled resource usage metrics required for automatic optimization.
To start minikube using containerd, run:
minikube start --container-runtime=containerd
-
Rancher Desktop: Go to Rancher Desktop > Preferences > Container Engine, and select containerd; then, click Apply.
Need an application to run on your cluster? Check out our Showcase application, a sample application which generates load and enables you to explore and experiment with Optimize Live on your own cluster.
Prepare to install
Install the StormForge CLI tool
The StormForge CLI is used to authenticate, retrieve credentials, and register the StormForge Agent on your Kubernetes cluster.
Download and install the 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.
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.
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.
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
).
Log in
From the command line, log into your StormForge account:
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
After you log in, go back to your command line session.
Generate an access credential
An access credential contains a clientID and a clientSecret. You can skip this step and go to install the StormForge Agent if you are either:
- Installing the Agent via the Get Started/Add Cluster wizard. This wizard generates the credentials.
- Reusing an existing StormForge credentials file. You need to locate the file that contains these credentials.
Otherwise, if the Agent doesn’t exist on your estate or if you want to create unique credentials for a cluster (instead of reusing existing credentials), generate the credentials file by running the following command.
- Replace CREDENTIAL_NAME with a name that will help you identify the credential (such as the name of the cluster you’re installing on).
- Replace CREDENTIAL_FILE with a filename that will help you to identify the file that contans the credential (no filename extension is needed).
stormforge auth create CREDENTIAL_NAME > CREDENTIAL_FILE
The credentials file should look something like this:
stormforge:
address: https://api.stormforge.io/
authorization:
issuer: https://api.stormforge.io/
clientID: CLIENT_ID
clientSecret: CLIENT_SECRET
Install the StormForge Agent
Note: Some installations require additional steps. If any of the following items are true, go to Install the StormForge Agent - advanced scenarios:
- You installed an earlier 2.0.x version of the stormforge-agent Helm chart
- You use a proxy server or a private container registry
- You cannot run
helm install
The oci://registry.stormforge.io/library/stormforge-agent
Helm chart creates and uses a ServiceAccount called stormforge-agent
and binds it to the Kubernetes view
ClusterRole, granting read-only permissions to all resources in the cluster.
-
Log in at https://app.stormforge.io.
-
Complete one of the following steps:
- If this is the first cluster you’re installing the Agent on, the Get Started page is shown. Enter your cluster name, and follow the steps on the page.
- If the Agent is installed on at least one other cluster, go to the Cluster Management page: In the left navigation, click Settings > Cluster Management. Then, click Add Cluster on the Cluster Management page, and complete the steps on the Add Cluster page.
The Agent is now sending metrics to the cloud service. In approximately one hour, a preliminary recommendation for each workload will be available for you to view in the Optimize Live UI.
To install the Agent, run the following command:
- Replace CREDENTIAL_FILE with the name of the file that contains your access credential.
- Replace CLUSTER_NAME with the name of the cluster (lowercase, no underscore) you’re installing the Agent on.
- Include any extra arguments from the Additional agent installation options table below.
helm install stormforge-agent oci://registry.stormforge.io/library/stormforge-agent \
--namespace stormforge-system \
--create-namespace \
--values CREDENTIAL_FILE \
--set clusterName=CLUSTER_NAME
Additional Agent installation options
Option | Description |
---|---|
--set manageAuthSecret=false |
Set to false to manage the StormForge Agent secret with a third-party credential manager. For details and the Agent secret format, see this guide. |
--set openshift=true |
Install on Red Hat OpenShift Container Platform version 4.x and later. See this guide for details. |
--set 'workload.allowNamespaces={namespace1,namespace2}' |
Set an allow list to collect metrics only on workloads in specific namespaces. Overrides a denyNamespaces list. Regex permitted, such as .*-system . |
--set 'workload.denyNamespaces={namespace1,namespace2}' |
Set a deny list so that no metrics are collected on workloads in these namespaces. Ignored if allowNamespaces is provided. Regex permitted, such as .*-system . |
The Agent is now sending metrics to the cloud service. In approximately one hour, a preliminary recommendation for each workload will be available for you to view in the Optimize Live UI.
Validate the installation
To see your cluster and workloads:
- Log into https://app.stormforge.io with your StormForge account.
- In the left navigation, click Workloads.
- Optional: Refine your search by cluster, namespace, or workload name; press Enter, and review the results.
If you don’t see what you expect, try troubleshooting the Agent.
Should you install the StormForge Applier?
The StormForge Applier, an optional component of Optimize Live, applies the recommended CPU and memory settings to objects, mostly commonly workloads and HPAs, in the cluster.
Install the StormForge Applier if you plan to:
- Deploy recommendations on demand. You can apply a single recommendation in any environment as you experiment with recommendations or if you need to quickly deploy a recommendation outside of a schedule.
- Deploy recommendations automatically. Define a schedule to receive recommendations, and Optimize Live will generate and deploy them. This option enables you to immediately realize the benefits of right-sizing your workloads without manual intervention.
You do not need to install the StormForge Applier if you plan to:
- Deploy recommendations as part of a GitOps workflow (for example, in a staging or production environment)
- Export the patches manually from the Optimize Live web application.
Install the Applier
The oci://registry.stormforge.io/library/stormforge-applier
Helm chart creates and uses a ServiceAccount called stormforge-applier
and binds it to the Kubernetes edit
ClusterRole, granting update and patch permissions to all optimizable workloads (and HPA, if enabled). You can grant additional permissions by specifying additional RBAC in the Helm install command.
First, make sure that the Agent is installed:
kubectl get pods -A | grep 'stormforge-agent'
Next, install the Applier:
- If you cannot run
helm install
, go to this section in the Install the StormForge Agent - advanced scenarios topic.
helm install stormforge-applier \
oci://registry.stormforge.io/library/stormforge-applier \
-n stormforge-system
Additional Applier installation options
Option | Description |
---|---|
--set enforce=true |
Set to true to continuously reinforce the latest recommendation after a field manager changes workload requests or limits. Default is false . The auto-deploy field must also be true . |
--set exemptManagers={value1,value2} |
Can be set only when enforce=true . If a field manager (for example, a CD tool) in this list changes workload requests or limits, Optimize Live does not reaply the latest recommendation. |
--set openshift=true |
Install on Red Hat OpenShift Container Platform version 4.x and later. See this guide for details. |
--values applier-rbac.yaml |
To apply patches to a KEDA-owned HPA, you must grant additional RBAC permission to the Applier. See this guide for details. |
Then, to validate the installation, run:
kubectl get pods -A | grep 'stormforge-applier'
The output should look something like this:
stormforge-system stormforge-applier-8554758f5b-whbc4 1/1 Running 0 20s
Additional Agent installation considerations
Workload discovery and metrics collection
In a default Agent installation:
- The Agent discovers and gathers metrics for all DaemonSet, HPA, Pod, ReplicaSet, ReplicationController, and StatefulSet types across all the namespaces on the cluster on which it’s installed.
- Custom resources are ignored and no metrics are collected on them. If you have custom resources in your environment or if you prefer not to have workloads discovered automatically, contact support@stormforge.io for guidance on how to modify the Helm chart.
What happens after you install?
First 7 days: metrics collection and preliminary recommendations
It typically takes about 7 days to collect enough metrics to generate an optimal recommendation (referred to as a complete recommendation) for you to apply.
Metrics collection on workloads begins as soon as the Agent is installed.
For the first 7 days after installation, Optimize Live generates preliminary recommendations to give you an evolving preview of potential optimization impact. They can be viewed, but should not be applied because they’re not based on a complete set of metrics. They’re generated:
- Hourly, for the first 24 hours after installing the Agent
- Once daily, on days 2 to 7 after installing the Agent
After 7 days: viewing and applying recommendations
After we collect 7 days of metrics, you’ll receive a complete recommendation once daily (the default schedule).
You can change this schedule at any time: On a workload’s details page, click Config, and set the Recommendation Schedule.
-
View and configure recommendations: You can view the recommendations on the Workloads page or on a workload’s details page.
-
Apply recommendations: By default, recommendations are not applied automatically, giving you control over how they’re applied.
When you are satisfied that the recommendations are safe to apply, you can enable automatic deployment on the Config page for some or all of your workloads.
Helm charts and troubleshooting
To learn more about the Agent and Applier Helm charts and steps to troubleshoot, you can run the following commands:
helm show readme oci://registry.stormforge.io/library/stormforge-agent
helm show readme oci://registry.stormforge.io/library/stormforge-applier
To learn about other parameters that you can configure, run the following commands:
helm show values oci://registry.stormforge.io/library/stormforge-agent
helm show values oci://registry.stormforge.io/library/stormforge-applier