Installation

The operator is distributed as a cosign-signed container image and a Helm chart, both published as OCI artifacts to GitHub Container Registry (GHCR):

Artifact	Reference
Image	ghcr.io/stepscale/stepscale-autoscaler
Helm chart	oci://ghcr.io/stepscale/charts/stepscale-autoscaler

Throughout, substitute <version> with the release you are installing (for example 0.1.0), <release> with your Helm release name, and <namespace> with the target namespace.

Note

Pull access to the image and chart is tied to an active subscription. Verify the image signature (3.1) before installing in any environment.

3.1 Verify the image signature

The image is signed with cosign keyless signing (Sigstore / GitHub OIDC - no long-lived keys). Verify that the image was produced by the stepscale release workflow before pulling it into your cluster:

cosign verify \
  --certificate-identity-regexp '^https://github\.com/stepscale/stepscale-autoscaler/\.github/workflows/release\.yml@refs/tags/v.*$' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  ghcr.io/stepscale/stepscale-autoscaler:<version>

A successful verification prints the certificate subject and the matched identity. The two flags assert who signed it (the release workflow on a version tag) and which OIDC issuer vouched for that identity (GitHub Actions); both must match or the command fails.

To pin to an immutable digest, resolve and verify by digest:

DIGEST=$(crane digest ghcr.io/stepscale/stepscale-autoscaler:<version>)
cosign verify \
  --certificate-identity-regexp '^https://github\.com/stepscale/stepscale-autoscaler/\.github/workflows/release\.yml@refs/tags/v.*$' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  ghcr.io/stepscale/stepscale-autoscaler@${DIGEST}

3.2 Install with Helm (connected cluster)

The chart bundles the ScalingRecommendation CRD and installs it automatically.

Minimal install (rules-only, analysis-only)

Runs the operator as a read-only advisor with the deterministic rule engine and no LLM. No license or LLM key is required to produce recommendations:

helm install <release> oci://ghcr.io/stepscale/charts/stepscale-autoscaler \
  --version <version> \
  --namespace <namespace> --create-namespace \
  --set llm.provider=none

Typical install (LLM analysis + apply enabled)

Enables LLM-assisted analysis with your own key and supplies the offline license so approved recommendations can be applied:

helm install <release> oci://ghcr.io/stepscale/charts/stepscale-autoscaler \
  --version <version> \
  --namespace <namespace> --create-namespace \
  --set llm.provider=openai \
  --set llm.model=gpt-4o-mini \
  --set llm.apiKey=<your-llm-api-key> \
  --set license.publicKey=<stepscale-public-key> \
  --set license.payload="$(cat license.json)" \
  --set license.signature="$(cat license.sig)"

Notes:

• llm.apiKey makes the chart create a Secret for you. To reference an existing Secret instead, set llm.existingSecret=<secret-name> (the Secret must hold the key under apiKey). Set llm.provider=anthropic to use Anthropic instead of OpenAI.
• license.publicKey is the base64-encoded ed25519 public key stepscale provides with your license; it is required to apply changes. license.payload / license.signature are the license file and its detached signature. Alternatively point license.existingSecret at a Secret holding license and signature keys.
• See Licensing for the full licensing model and Configuration reference for every value.

Recommended add-ons

Point the operator at Prometheus for real metric history (strongly recommended):

  --set metrics.prometheusUrl=http://prometheus.monitoring.svc:9090

Run two replicas for availability (leader election is on by default, so only the leader ever mutates):

  --set replicaCount=2

3.3 Air-gapped install

In an air-gapped environment, mirror the verified image and chart into your internal registry, then install from there.

1. On a connected host, verify (3.1) and copy the image into your registry. With crane:

crane copy \
  ghcr.io/stepscale/stepscale-autoscaler:<version> \
  registry.internal.example.com/stepscale/stepscale-autoscaler:<version>

(Equivalent with skopeo copy docker://… docker://….) To carry the signature across, also copy the cosign artifacts, or re-verify against GHCR before the copy and rely on your internal registry’s controls thereafter.

2. Pull and re-host the chart:

helm pull oci://ghcr.io/stepscale/charts/stepscale-autoscaler --version <version>
helm push stepscale-autoscaler-<version>.tgz \
  oci://registry.internal.example.com/stepscale/charts

3. Install from the internal registry, overriding the image repository:

helm install <release> \
  oci://registry.internal.example.com/stepscale/charts/stepscale-autoscaler \
  --version <version> \
  --namespace <namespace> --create-namespace \
  --set image.repository=registry.internal.example.com/stepscale/stepscale-autoscaler \
  --set llm.provider=none \
  --set license.publicKey=<stepscale-public-key> \
  --set license.existingSecret=<your-license-secret>

With llm.provider=none and an offline license, the operator makes no outbound calls.

3.4 Verify the install

# The operator pod is Running:
kubectl get pods -n <namespace> -l app.kubernetes.io/name=stepscale-autoscaler

# The CRD is registered:
kubectl get crd scalingrecommendations.stepscale.io

# The operator started cleanly (look for "operator starting" and the license line):
kubectl logs -n <namespace> deploy/<release>-stepscale-autoscaler

On a healthy start the logs report the configured provider, watched namespaces, whether Prometheus history is in use, and the license state. Recommendations begin to appear once the operator has accumulated enough metric history - see Usage and workflow and, if none appear, Troubleshooting.