Advanced installation

Prerequisites

• A StormForge Account
• Kubernetes version 1.24 or later
• helm version 3.14.0 or later
• kubectl configured with access to your cluster
• cluster-admin access (for installation only)
• A Kubernetes cluster and a name to identify it in StormForge.
  The name cannot exceed 63 characters, cannot start or end with a dash (-), and must follow the RFC 1123 DNS label standard.
• Configure a proxy, if needed
• If you use a private container registry, import the required containers
• Configure firewall rules, including granting Kubernetes clusters access to these StormForge service 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)

Set up the StormForge CLI

The StormForge CLI is used to authenticate, retrieve credentials, and register StormForge on your Kubernetes cluster.

Download and install

Download and install the CLI tool:

• Linux
• Windows
• macOS
• Docker

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

sudo mv stormforge /usr/local/bin/

[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" } 

brew install thestormforge/tap/stormforge

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

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

Log in

From the command line, log into your StormForge account:

stormforge login

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

stormforge login --url

To verify communication with the API:

stormforge ping

After logging in, return to your command line session.

Generate an access credential

If you previously installed StormForge on a cluster, you can reuse the credential. Locate the credential file and skip to Install StormForge.

If this is your first install, generate a credential by running the following command:

• Replace CREDENTIAL_NAME with a name for this credential, such as the cluster name.
• Replace CREDENTIAL_FILE with the output filename — no extension needed.

stormforge auth create CREDENTIAL_NAME > CREDENTIAL_FILE

The credentials file resembles the following:

stormforge:
   address: https://api.stormforge.io/
authorization:
   issuer: https://api.stormforge.io/
   clientID: CLIENT_ID
   clientSecret: CLIENT_SECRET

Advanced installation scenarios

If you have a proxy server

Before you install StormForge, create a proxy.yaml file, replacing PROXY_HOST with the appropriate hostname.

When you install StormForge, append the --values proxy.yaml argument to the Helm command.

proxyUrl: https://PROXY_HOST:3128
noProxy: 10.100.0.0/16,kubernetes.default.svc

kubectl get svc kubernetes -n default

The output resembles the following:

NAME        TYPE      CLUSTER-IP    EXTERNAL-IP   PORT(S)   AGE
kubernetes  ClusterIP 10.100.0.0     <none>       443/TCP   6d17h

In this example, you would use 10.100.0.0/16.

If you have a transparent proxy

If your organization uses a transparent proxy, you need to configure StormForge to trust the proxy’s root certificate authority (CA). For details, see the Transparent proxy configuration guide.

If you have a private container registry

StormForge uses two container images: a unified agent image (shared by the Agent and Applier components) and a Prometheus image (used by the Exporter component).

From a terminal with direct internet access, run the following commands to pull and push both images to your private registry:

• Replace $HOSTNAME with the private container registry hostname.
• In the docker tag command, preserve the same name components and tag as the source image.

# Agent / Applier image
$ docker pull registry.stormforge.io/optimize/workload-agent:2.28.2 --platform linux/amd64
$ docker tag registry.stormforge.io/optimize/workload-agent:2.28.2 $HOSTNAME/optimize/workload-agent:2.28.2
$ docker push $HOSTNAME/optimize/workload-agent:2.28.2

# Exporter (Prometheus) image
$ docker pull quay.io/prometheus/prometheus:v3.12.0 --platform linux/amd64
$ docker tag quay.io/prometheus/prometheus:v3.12.0 $HOSTNAME/prometheus/prometheus:v3.12.0
$ docker push $HOSTNAME/prometheus/prometheus:v3.12.0

When you install StormForge, append these arguments to the Helm install command:

--set agent.image.repository=$HOSTNAME/optimize/workload-agent \
--set applier.image.repository=$HOSTNAME/optimize/workload-agent \
--set exporter.image.repository=$HOSTNAME/prometheus/prometheus \

Install StormForge

The oci://registry.stormforge.io/library/stormforge Helm chart creates:

• A ServiceAccount stormforge-agent bound to the Kubernetes view ClusterRole (read-only access)
• A ServiceAccount stormforge-applier bound to the Kubernetes edit ClusterRole (update and patch permissions on workloads)

To install StormForge, 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 on.
• Include any extra arguments from the Agent configuration or Applier configuration topics.

helm install stormforge oci://registry.stormforge.io/library/stormforge \
  --namespace stormforge-system \
  --create-namespace \
  --values CREDENTIAL_FILE \
  --set clusterName=CLUSTER_NAME

For installation issues, see the Installation section in the Troubleshooting topic.

The StormForge Agent is now sending metrics to StormForge. In approximately 10 minutes, a preliminary recommendation for each workload will be available in the StormForge UI.

Validate the installation

To see your cluster and workloads:

1. Log in to app.stormforge.io.
2. In the left navigation, click Workloads.
3. Optional: Refine your search by cluster, namespace, or workload name; press Enter, and review the results.

If you don’t see what you expect, see The installation failed. What can I check? in the Troubleshooting topic.

StormForge Applier

The Applier is installed and enabled by default. By default, recommendations aren’t applied automatically, giving you control over how and when they’re applied. The Applier allows you to:

• Apply recommendations on demand from the StormForge UI.
• Apply them automatically on a schedule. For this method, you must also enable automatic deployment.

For more information about how the Applier works, see StormForge Applier.

Disabling the Applier

If you plan to deploy recommendations as part of a GitOps workflow or export recommendations as patches, you can disable the Applier at install time. Recommendations will continue to be generated; their application is up to you.

To disable the Applier, add --set applier.enabled=false to your Helm install command.

Continuous reconciliation

You can control whether the Applier continuously reconciles workload resource settings to the recommended values by setting applier.reconciliation.mode. For details, see Continuous reconciliation in the Applier configuration topic.

Additional installation considerations

If you cannot run helm install

Some environments don’t support running helm install directly against a cluster. In these cases, you can use Helm to render the templates locally and then apply them using kubectl:

• If you use a proxy server, add the -f proxy.yaml flag before --output-dir ..
• 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 StormForge on.
• Include any extra arguments from the Agent configuration or Applier configuration topics.

helm template stormforge \
  oci://registry.stormforge.io/library/stormforge \
  --namespace stormforge-system \
  --values CREDENTIAL_FILE \
  --set clusterName=CLUSTER_NAME \
  --output-dir .

The helm template command creates manifests in a stormforge subdirectory. To apply the manifests to your cluster, run:

kubectl create ns stormforge-system; kubectl apply -f stormforge --recursive=true

Workload discovery and metrics collection

In a default installation:

• The Agent discovers and gathers metrics for all DaemonSet, HPA, Pod, ReplicaSet, ReplicationController, and StatefulSet types across all namespaces on the cluster.
• Custom resources are ignored by default. If you have other custom resource types you want to optimize, see Custom workload kinds. If you prefer not to have workloads discovered automatically, contact us for guidance.

What happens after you install?

The StormForge Agent starts collecting workload metrics as soon as you install.

First 7 days: Metrics collection and preliminary recommendations

Ten minutes after installation, once initial metrics are collected, StormForge provides its first preliminary recommendation to give you a preview of potential optimization impact.

Preliminary recommendations are then generated:

• Hourly, for the first 24 hours after installing
• Once daily, on days 2 to 7 after installing

These can be viewed as a preview, but we recommend waiting for a complete recommendation before applying.

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.

For this reason, we recommend waiting 7 days before applying recommendations.

After 7 days: View and apply recommendations

After StormForge collects 7 days of metrics, you’ll receive a complete recommendation once daily (the default schedule).

By default, recommendations aren’t applied automatically, giving you control over how and when they’re applied.

When you’re satisfied that the recommendations are safe to apply, you can enable automatic deployment for some or all of your workloads by setting the live.stormforge.io/auto-deploy annotation to "Enabled" as described in the Auto-deploy topic.

You can also change the recommendation schedule based on how closely you want to track CPU and memory utilization and your tolerance for pod churn.

Review the optimization settings

Review the settings StormForge uses to generate recommendations for a workload: In the StormForge UI, click Workloads, then click a workload name and go to the Settings tab.

Change the optimization settings (optional)

If you’ve enabled automatic deployment and are satisfied with the default cluster settings, no further configuration is needed.

If you want to adjust the defaults, we recommend setting them at the cluster level, then defining exceptions at the namespace and workload levels. See Configure optimization settings for details.

Helm chart and troubleshooting

To learn more about the StormForge Helm chart and troubleshooting steps:

helm show readme oci://registry.stormforge.io/library/stormforge

To see all available configuration parameters:

helm show values oci://registry.stormforge.io/library/stormforge