Getting Started¶

Install¶

Install via the OCI Helm chart from GHCR:

helm install scale-sentry \
  oci://ghcr.io/ethan-kane-ops/charts/scale-sentry \
  --namespace scale-sentry --create-namespace

Without --version this resolves the latest released chart; add --version X.Y.Z (matching a release) to pin for reproducible installs.

Verify before you install

Every released image and the chart are cosign-signed. See Security for the verification command.

Upgrading¶

Helm installs the CRD from the chart's crds/ directory on first install and never touches it again, so helm upgrade on its own leaves the old CRD in place. Apply the chart's CRD yourself, then upgrade:

helm show crds oci://ghcr.io/ethan-kane-ops/charts/scale-sentry | kubectl apply -f -
helm upgrade scale-sentry oci://ghcr.io/ethan-kane-ops/charts/scale-sentry \
  --namespace scale-sentry

Reading the CRD out of the chart keeps the two in lockstep. Add --version X.Y.Z to both commands to move to a specific release.

The observer needs a new RBAC rule

The DNS and PodDisruptionBudget audits read poddisruptionbudgets in each validating namespace. helm upgrade renders the rule into the observer Role for every namespace in observer.namespaces; a namespace whose RBAC was applied by hand from config/rbac/observer_role.yaml needs it reapplied. Without the grant the run still completes, it just carries no PDB verdict.

v0.5.0 removes v1alpha1

ScaleValidation is served at v1beta1 only. There is no conversion webhook, so existing v1alpha1 objects are not converted and the apiserver will reject them. Delete them before upgrading, then recreate them with apiVersion: validation.scale-sentry.ek.co/v1beta1.

Container images¶

Image	Role
`ghcr.io/ethan-kane-ops/scale-sentry`	controller
`ghcr.io/ethan-kane-ops/scale-sentry-loadgen`	load generator job
`ghcr.io/ethan-kane-ops/scale-sentry-observer`	observer job

All images are multi-arch (linux/amd64, linux/arm64).

Quickstart: first verdict in five minutes¶

You need a target Deployment with an HPA, and the cluster needs metrics-server (HPAs cannot act without it; just dev-up installs it on the local kind cluster, and Troubleshooting covers clusters that lack it). The repo ships podinfo (Deployment + Service + HPA) as the canonical demo target:

kubectl apply -f https://raw.githubusercontent.com/ethan-kane-ops/scale-sentry/main/config/samples/targets/podinfo.yaml
kubectl apply -f https://raw.githubusercontent.com/ethan-kane-ops/scale-sentry/main/config/samples/scalevalidation-servicedefault.yaml

Watch the run move through its phases:

kubectl get scalevalidation podinfo-default -w

NAME              PHASE       SLA    TRAFFIC   AGE
podinfo-default   Pending                      2s
podinfo-default   Running                      8s
podinfo-default   Succeeded   Pass   Pass      3m41s

The controller narrates the lifecycle through Events, so a failing run explains itself:

kubectl describe scalevalidation podinfo-default

Read the full verdict off the status subresource:

kubectl get scalevalidation podinfo-default -o yaml

Key status fields: phase (Pending / Running / Succeeded / Failed / Error / Terminating), slaStatus and trafficIntegrity (Pass / Fail / Unknown), scaleUpDuration (measured HPA reaction), totalRequests / failedRequests / failureRateBasisPoints (1 bp = 0.01%, so 100 is 1%), diagnostics (the analyzer findings, each with an alert name and severity), and history (the last ten terminal verdicts, newest first, so trend is visible without a metrics stack). conditions carries Finished, set True the moment a run reaches any terminal phase, which is what makes kubectl wait --for=condition=Finished a usable CI gate (see Gate a Pipeline on a Verdict). The Events page maps every lifecycle transition; Observability covers the matching Prometheus metrics.

Sample library¶

Every spec shape ships as a runnable manifest in config/samples/:

Sample	Demonstrates
`scalevalidation-servicedefault.yaml`	Minimal run: Service endpoint, constant load
`scalevalidation-autodiscover.yaml`	`AutoDiscoverProbe` readiness-path targeting
`scalevalidation-custompath.yaml`	`CustomPath` explicit endpoint
`scalevalidation-rampload.yaml`	`Ramp` open-loop profile with warmup
`scalevalidation-poissonload.yaml`	`Poisson` arrivals for SLA-accurate p99
`scalevalidation-http2.yaml`	HTTP/2 (h2c prior-knowledge) target
`scalevalidation-grpc.yaml`	gRPC Health/Check load
`scalevalidation-tls.yaml`	Private CA bundle via ConfigMap
`scalevalidation-with-disruption.yaml`	Chaos pod-kill at peak load
`targets/podinfo.yaml`	Demo target: Deployment + Service + HPA

Annotation bridge¶

Skip the manifest entirely: annotate any Deployment to opt into shadow validation. The controller provisions a ScaleValidation for you.

kubectl annotate deployment/payment-service \
  validation.scale-sentry.ek.co/enabled=true \
  validation.scale-sentry.ek.co/sla=90s \
  validation.scale-sentry.ek.co/base-rps=150 \
  validation.scale-sentry.ek.co/port=8080

See Configuration for every spec field and targeting mode.