Advanced installation
9 minute read
Prerequisites
- A StormForge Account
- Kubernetes, version 1.16 or later
- Helm version 3.8 or later
- kubectl properly configured for your cluster
- The cluster name to install the Agent into
- Cluster-Admin access (for installation only)
Be sure to add the following StormForge services URLs to your organization’s allowList:
- in.stormforge.io
- api.stormforge.io
- app.stormforge.io
- auth.stormforge.io
- docs.stormforge.io
- downloads.stormforge.io
- registry.stormforge.io
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:
Linux Binary Download:
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:
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:
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.
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 authorization token
If the Agent is already installed on a cluster, you can reuse the existing token: locate the file name of the token, and skip to this section later in this topic.
If the Agent doesn’t exist on your estate, generate a token by running the following command, replacing TOKEN_NAME with a name that will help you identify the file later:
stormforge auth create TOKEN_NAME > TOKEN_NAME-token.yaml
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 - advanced scenarios
If you installed an earlier 2.0.x version of the stormforge-agent Helm chart
You must delete the current Agent.
kubectl delete deploy stormforge-agent -n stormforge-system
If you have a proxy server
Before you install the Agent, create a proxy.yaml
server file (shown below) for the Prometheus container, which is installed with the Agent.
Replace PROXY_HOST with the appropriate hostname.
When you install the Agent (or the Applier), append this argument to the Helm command: --values proxy.yaml
---
proxyUrl: https://PROXY_HOST:3128
noProxy: 10.100.0.0/16,kubernetes.default.svc
Note: The no_proxy
parameter should include the network range that enables direct communication with the cluster and nodes. For example, to get this cluster value, run the following command and append a subnet mask sized appropriately for your environment to the CLUSTER-IP value.
kubectl get svc kubernetes -n default
The output will look something like this:
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
kubernetes ClusterIP 10.100.0.0 <none> 443/TCP 6d17h
Using this example, you could use a value of 10.100.0.0/16
.
If you have a private container registry
From a terminal that has direct internet access, run the following commands to import the Agent and Prometheus containers and push them to your repository.
Important:
- In the
docker tag
command, make sure that the TARGET_IMAGE path uses the same slash-separated name components and tag as the SOURCE_IMAGE path (/optimize/workload-agent:2.0.2
,/prom/prometheus:v2.44.0
). - Replace $HOSTNAME with the private container registry location.
$ docker pull registry.stormforge.io/optimize/workload-agent:2.0.3
$ docker tag registry.stormforge.io/optimize/workload-agent:2.0.3 $HOSTNAME/optimize/workload-agent:2.0.3
$ docker push $HOSTNAME/optimize/workload-agent:2.0.3
$ docker pull prom/prometheus:v2.44.0
$ docker tag prom/prometheus:v2.44.0 $HOSTNAME/prom/prometheus:v2.44.0
$ docker push $HOSTNAME/prom/prometheus:v2.44.0
When you install the Agent, append these arguments to the Helm install command:
--set workload.image.repository=$HOSTNAME/optimize/workload-agent \
--set prom.image.repository=$HOSTNAME/prom/prometheus \
Install the Agent
To install the Agent, run the following command:
- Replace TOKEN_NAME-token.yaml with the file name that contains your authorization token.
- Replace CLUSTER_NAME with the name of the cluster you’re installing the Agent on.
- Include any extra arguments defined in other sections of this topic.
- You can constrain metrics collection to specific namespaces by specifying allow and deny lists - see this section below.
- Note: If you cannot run
helm install
, skip to this section later in this topic.
helm install stormforge-agent oci://registry.stormforge.io/library/stormforge-agent \
--namespace stormforge-system \
--create-namespace \
--values TOKEN_NAME-token.yaml \
--set stormforge.clusterName=CLUSTER_NAME
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.
Should you install the StormForge Applier?
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.
If you use a private container registry, import and tag the Applier container and push it to your repository (and don’t change the name component and tag):
- Replace $HOSTNAME with the private container registry location.
$ docker pull registry.stormforge.io/optimize/applier:2.0.0
$ docker tag registry.stormforge.io/optimize/applier:2.0.0 $HOSTNAME/optimize/applier:2.0.0
$ docker push $HOSTNAME/optimize/applier:2.0.0
To install the Applier, run the following command:
- If you use a proxy server, add the
-f proxy.yaml
flag after the repository name. - Replace $HOSTNAME with the private container registry location.
- If you cannot run
helm install
, skip to this section.
$ helm install stormforge-applier \
oci://registry.stormforge.io/library/stormforge-applier \
-n stormforge-system --version 2.0.0 \
--set image.repository=$HOSTNAME/optimize/applier
To validate the installation, run:
kubectl get pods -A | grep 'applier'
The output should look something like this:
stormforge-system stormforge-applier-8554758f5b-whbc4 1/1 Running 0 20s
Additional installation considerations
If you cannot run helm install
Some environments cannot run Helm installations. StormForge relies on Helm to generate the templates required for installation; therefore, Helm is a strict requirement. However, you can run Helm to generate the template files to be applied to your cluster using standard kubectl commands:
- If you use a proxy server, add the
-f proxy.yaml
flag before--output-dir .
. - Replace TOKEN_NAME-token.yaml with the file name that contains your authorization token.
- Replace CLUSTER_NAME with the name of the cluster you’re installing the Agent on.
helm template stormforge-agent \
oci://registry.stormforge.io/library/stormforge-agent \
--namespace stormforge-system \
--values TOKEN_NAME-token.yaml \
--set stormforge.clusterName=CLUSTER_NAME \
--output-dir .
The Helm command above creates manifests in a stormforge-agent
subdirectory. To apply the manifests to your cluster, run:
kubectl create ns stormforge-system; kubectl apply -f stormforge-agent -–recursive=true
Restrict metrics collection with allow and deny lists
To constrain metrics collection to specific namespaces, include one of the following arguments in the Helm install command:
-
--set 'workload.allowNamespaces={namespace1,namespace2}'
Metrics are collected on workloads in these namespaces only.
-
--set 'workload.denyNamespaces={namespace1,namespace2}'
No metrics are collected on workloads in these namespaces.
These parameters are mutually exclusive. If you specify both, workload.allowNamespaces
has precedence.
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.
Role-based access control
By default:
- The Agent applies the Kubernetes view role and creates a ClusterRoleBinding, granting read-only permissions to all resources in the cluster.
- The optional Applier component uses the edit role, enabling it to patch all optimizable workloads.
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 --version 2.0.0
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 --version 2.0.0