Migrate from v2 to v3

With v3, the separate stormforge-agent and stormforge-applier Helm charts are combined into a single stormforge chart.

Prerequisites

Before you begin, ensure you have:

• The StormForge CLI installed
• Your current v2 values (see Convert your values)
• clusterName and your API credentials (authorization.clientID and authorization.clientSecret)

Webhook considerations

The v3 chart’s MutatingWebhookConfiguration reuses the name of the v2 Applier webhook. This means:

• Helm-managed installs: If a v2 Applier is still installed when you run helm install stormforge, Helm’s release-ownership check will refuse to install.
• GitOps users (ArgoCD, Flux, kubectl apply): There is no automatic conflict detection. You must fully remove the v2 Applier before applying the v3 manifests. Failing to do so will result in two conflicting MutatingWebhookConfiguration resources.

CRD considerations

When you uninstall the v2 Agent, the optimize.stormforge.io CustomResourceDefinitions (CRDs) — and all associated custom resources, such as optimization configurations — remain on your cluster. This is expected, as helm uninstall doesn’t remove CRDs. Don’t delete them manually. Deleting a CRD removes every associated custom resource from the cluster.

In step 4 of the migration, you’ll use Helm to transfer ownership of the CRDs to the v3 release.

GitOps users (ArgoCD, Flux, kubectl apply): No action is needed. There is no release-ownership check when applying rendered manifests; the existing CRDs are updated in place.

Migration steps

1. Convert your values

Convert your v2 values into a single v3 values.yaml. At least one of --agent-values and --applier-values is required — omit --applier-values if the Applier isn’t installed.

stormforge migrate helm-values \
  --agent-values ./agent-values.yaml \
  --applier-values ./applier-values.yaml \
  --output ./values.yaml

The command writes the converted values to the output file and reports any keys that require manual attention.

Review the output file and address any warnings before proceeding.

helm get values stormforge-agent -n stormforge-system -o yaml > agent-values.yaml
helm get values stormforge-applier -n stormforge-system -o yaml > applier-values.yaml

2. Confirm required values

Your values.yaml must include clusterName and your API credentials. Values exported with helm get values already contain them. Add them if you started from a fresh file. At minimum:

clusterName: my-cluster
authorization:
  clientID: CLIENT_ID
  clientSecret: CLIENT_SECRET

3. Uninstall the Applier and Agent

Remove the Applier (if it’s installed), then the Agent:

helm uninstall stormforge-applier -n stormforge-system
helm uninstall stormforge-agent -n stormforge-system

4. Install the v3 unified chart

The --take-ownership flag (Helm 3.17 or later) lets Helm take ownership of the CRDs left in place by the v2 Agent:

helm install stormforge oci://registry.stormforge.io/library/stormforge \
  --namespace stormforge-system \
  --create-namespace \
  --take-ownership \
  --values values.yaml

This installs the Agent, Forwarder, and Applier in a single chart, replacing the separate v2 installations.

If your Helm version doesn’t support --take-ownership, label and annotate the existing CRDs to match the v3 release before installing:

for crd in workloadoptimizers optimizationconfigurations clusteroptimizationconfigurations; do
  kubectl label crd ${crd}.optimize.stormforge.io \
    app.kubernetes.io/managed-by=Helm --overwrite
  kubectl annotate crd ${crd}.optimize.stormforge.io \
    meta.helm.sh/release-name=stormforge \
    meta.helm.sh/release-namespace=stormforge-system --overwrite
done

If migration fails

Migration issues are typically environment-specific and may require manual intervention. If you run into problems, contact StormForge support.

Values reference

The stormforge migrate helm-values command handles these conversions automatically. These tables are a reference for what changed between v2 and v3.

Renamed values

Removed values

Resource name changes

The following Kubernetes resource names changed in v3. Update any references to these names in monitoring, alerts, or scripts.

Deployments

CI/CD automation updates

Update any CI/CD pipelines that reference the old chart URLs or release name: