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

Both are public - no registry login or pull Secret is needed to install. Throughout, substitute <version> with the release you are installing (the latest is 0.4.0), <release> with your Helm release name, and <namespace> with the target namespace.

3.1 Quickstart

Three commands take you from nothing to recommendations. The Community tier includes the full analysis - the deterministic rule engine and the LLM judgement (with your own LLM key). No license is required to see recommendations; only applying them automatically needs one (see Licensing and §3.3).

# 1. Install, pointing the analysis at your own LLM key:
helm install <release> oci://ghcr.io/stepscale/charts/stepscale-autoscaler \
  --version <version> \
  --namespace <namespace> --create-namespace \
  --set llm.provider=openai \
  --set llm.apiKey=<your-llm-api-key>

# 2. Wait a few minutes while the operator collects metric history and analyzes.

# 3. Read the recommendations:
kubectl get scalerec -A

Then kubectl describe scalerec <name> -n <namespace> shows the reasoning, the proposed diff, and the estimated saving. See Usage and workflow to read, approve, and (with a license) apply them.

No LLM key?

Drop the llm.provider / llm.apiKey flags and pass --set llm.provider=none instead. The operator still produces recommendations from the deterministic rule engine - it just skips the LLM judgement. Set llm.provider=anthropic to use Anthropic instead of OpenAI; llm.apiKey makes the chart create a Secret, or point llm.existingSecret at one holding the key under apiKey.

3.2 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.3 Enable apply (license)

To let the operator apply approved changes (and drive predictive schedules), supply the offline license stepscale sent and switch the operating mode to apply:

kubectl apply -f license-secret.yaml   # the Secret stepscale sent (creates it in <namespace>)

helm upgrade <release> oci://ghcr.io/stepscale/charts/stepscale-autoscaler \
  --version <version> --namespace <namespace> --reuse-values \
  --set mode=apply \
  --set license.existingSecret=stepscale-autoscaler-license

Notes:

• The license public key is baked into the chart - you do not pass it. The example applies the license-secret.yaml stepscale sent and points license.existingSecret at it; to let the chart create the Secret instead, drop that line and pass the base64 --set license.payload=<…> --set license.signature=<…> values from licensegen issue. Both are base64, not the raw license.json.
• mode=apply patches approved recommendations only; nothing is mutated until you patch a recommendation approved: true. Leave mode at its recommend default to keep the operator advisory-only even with a license installed.
• 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.4 Air-gapped / private registry

In an air-gapped environment (or when you mirror the artifacts into your own registry), pull access may be gated and the cluster needs credentials. Authenticate, mirror the verified image and chart into your internal registry, then install from there.

Authenticate to a gated registry. Log your install host in to the registry before pulling the chart or running cosign verify / crane:

echo <token> | docker login ghcr.io -u <github-username> --password-stdin
echo <token> | helm registry login ghcr.io -u <github-username> --password-stdin

If the cluster also needs credentials to pull the image, create a pull Secret in the install namespace and reference it via imagePullSecrets:

kubectl create secret docker-registry stepscale-ghcr \
  --namespace <namespace> \
  --docker-server=ghcr.io \
  --docker-username=<github-username> \
  --docker-password=<token>

Then add --set imagePullSecrets[0].name=stepscale-ghcr to the helm install command. (Pulling the public image needs none of this.)

1. On a connected host, verify (§3.2) 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.existingSecret=<your-license-secret>

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

3.5 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/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.