API Reference¶

Packages¶

validation.scale-sentry.ek.co/v1beta1

validation.scale-sentry.ek.co/v1beta1¶

Package v1beta1 contains API Schema definitions for the validation group.

Resource Types¶

ScaleValidation

CABundleSource¶

CABundleSource references a PEM bundle living in a Kubernetes object. Only ConfigMapRef is supported today; Secret backing is a future ticket.

Appears in: - TLSConfig

Field	Description	Default	Validation
`configMapRef` ConfigMapKeyRef	ConfigMapRef selects a key in a ConfigMap in the same namespace as the ScaleValidation.

ConfigMapKeyRef¶

ConfigMapKeyRef identifies a single key in a ConfigMap.

Appears in: - CABundleSource

Field	Description	Default	Validation
`name` string	Name of the ConfigMap.
`key` string	Key within the ConfigMap data block holding the PEM bundle.

CrossVersionObjectReference¶

CrossVersionObjectReference contains enough information to identify the target resource being validated.

Appears in: - ScaleValidationSpec

Field	Description	Default	Validation
`apiVersion` string	API version of the referent.
`kind` string	Kind of the referent (e.g. Deployment).
`name` string	Name of the referent.

DiagnosticAlert¶

DiagnosticAlert represents a single finding from the analysis engine.

Appears in: - ScaleValidationStatus

Field	Description	Validation
`type` string	Type categorises the alert (e.g. "ProbeLeakage", "CPUThrottling").
`severity` Severity	Severity is one of Info, Warning, or Critical.	Enum: [Info Warning Critical]
`message` string	Message is a human-readable description of the finding.
`recommendation` string	Recommendation is the suggested remediation.	Optional: {}

DisruptionConfig¶

DisruptionConfig controls chaos injection during the validation run.

Appears in: - ScaleValidationSpec

Field	Description	Default	Validation
`injectPodDeletion` boolean	InjectPodDeletion enables terminating a healthy replica during peak load.	false
`minReplicasForChaos` integer	MinReplicasForChaos is the minimum replica count before chaos is allowed. Prevents disruption from causing total unavailability.	2	Minimum: 2
`triggerDelay` Duration	TriggerDelay is the duration to wait after load starts before injecting chaos.		Optional: {}

GRPCConfig¶

GRPCConfig carries gRPC-specific knobs for the loadgen Health/Check probe. Scoped intentionally narrow: the goal is to exercise h2 framing, gRPC trailers, and server-side request handling at the rate the load profile dictates, not to drive arbitrary RPC methods. Reflection-based method discovery and unary-RPC invocation against arbitrary user services are deferred to a future ticket.

Appears in: - TargetConfig

Field	Description	Default	Validation
`service` string	Service is the upstream service name passed to the Health/Check probe (grpc.health.v1.HealthCheckRequest.service). Empty probes overall server health. Use a non-empty value when the target publishes multiple per-service health entries.		Optional: {}

LoadConfig¶

LoadConfig defines the synthetic traffic profile.

Appears in: - ScaleValidationSpec

Field	Description	Validation
`baseRps` integer	BaseRPS is the starting requests-per-second before dynamic scaling.
`concurrencyFactor` integer	ConcurrencyFactor does nothing. It was specified as a per-core multiplier folded into the target rate, but no release ever implemented it: the controller has always passed BaseRPS to the load generator unchanged. It stays served, and optional, so manifests written against the old required field keep validating. Deprecated: use Concurrency to size the in-flight worker pool. Scheduled for removal in v0.7.0.	Optional: {}
`concurrency` integer	Concurrency fixes the load generator's worker-pool size, the ceiling on requests in flight at once. Unset (or 0) derives it from the peak arrival rate, capped at 256, which is correct for targets that answer quickly. Raise it when the target is slow enough that the derived pool cannot keep the schedule: a backend answering in 500ms at 1000 RPS needs ~500 requests in flight, and a 256-worker pool would throttle arrivals into a closed loop, understating the latency a real open-loop client would see.	Minimum: 0 Optional: {}
`warmupDuration` Duration	WarmupDuration runs traffic against the target before the measurement window opens. Requests are sent (so TCP/TLS handshakes settle, JIT runs, caches warm) but their latencies and counters are excluded from the SLA verdict. Default 0 (no warmup).	Optional: {}
`profile` LoadProfile	Profile selects the arrival-rate shape for the measurement window. Default Constant (today's behaviour). Poisson is the recommended choice for SLA-accurate verdicts because user traffic is open-loop.	Optional: {}

LoadPattern¶

Underlying type: string

LoadPattern is the shape of the generated request rate over time.

Validation: - Enum: [Constant Poisson Ramp Step Spike]

Appears in: - LoadProfile

Field	Description
`Constant`
`Poisson`
`Ramp`
`Step`
`Spike`

LoadProfile¶

LoadProfile selects the arrival shape for the measurement window. Pattern-specific knobs apply only to their named pattern.

Appears in: - LoadConfig

Field	Description	Default	Validation
`pattern` LoadPattern	Pattern is the arrival shape.	Constant	Enum: [Constant Poisson Ramp Step Spike]
`endRps` integer	EndRPS is the terminal rate for Ramp. Required when Pattern=Ramp.		Optional: {}
`rampDuration` Duration	RampDuration is the wall-clock window over which Ramp interpolates from BaseRPS to EndRPS. Required when Pattern=Ramp.		Optional: {}
`stepRps` integer	StepRPS is the rate increment per StepDuration interval. Required when Pattern=Step.		Optional: {}
`stepDuration` Duration	StepDuration is the wall-clock interval between Step climbs. Required when Pattern=Step.		Optional: {}
`spikes` SpikeWindow array	Spikes is the ordered list of spike windows to stitch into the measurement phase. Required when Pattern=Spike.		Optional: {}

NetworkPath¶

Underlying type: string

NetworkPath selects where traffic enters, which is what isolates an in-cluster scaling problem from an edge one.

Validation: - Enum: [ClusterIP Ingress Gateway]

Appears in: - TargetConfig

Field	Description
`ClusterIP`
`Ingress`
`Gateway`

Phase¶

Underlying type: string

Phase is the lifecycle state of a validation run. Pending and Running are transient; Succeeded, Failed and Error are terminal; Terminating is the deletion path.

Validation: - Enum: [Pending Running Succeeded Failed Error Terminating]

Appears in: - RunSummary - ScaleValidationStatus

Field	Description
`Pending`
`Running`
`Succeeded`
`Failed`
`Error`
`Terminating`

Protocol¶

Underlying type: string

Protocol is the wire protocol the load generator speaks.

Validation: - Enum: [HTTP1 HTTP2 GRPC]

Appears in: - TargetConfig

Field	Description
`HTTP1`
`HTTP2`
`GRPC`

RunSummary¶

RunSummary is a compact record of one terminal run, kept in ScaleValidationStatus.History so trend ("did this get worse over the last N releases") is visible from kubectl get -o json alone, without requiring a Prometheus scrape of scale_sentry_runs_total. Deliberately excludes Diagnostics: that field can grow arbitrarily large per run, which is fine for a single current-status snapshot but would make a History slice's size unbounded.

Appears in: - ScaleValidationStatus

Field	Description	Validation
`finishedAt` Time	FinishedAt is when this run reached a terminal phase.
`phase` Phase	Phase is the terminal phase this run reached (Succeeded or Failed).	Enum: [Pending Running Succeeded Failed Error Terminating]
`slaStatus` Verdict	SLAStatus mirrors the top-level status.slaStatus at run completion.	Enum: [Pass Fail Unknown]
`trafficIntegrity` Verdict	TrafficIntegrity mirrors the top-level status.trafficIntegrity at run completion.	Enum: [Pass Fail Unknown]
`failureRateBasisPoints` integer	FailureRateBasisPoints mirrors the top-level status.failureRateBasisPoints at run completion.

ScaleValidation¶

ScaleValidation is the Schema for the scalevalidations API.

Field	Description	Default	Validation
`apiVersion` string	`validation.scale-sentry.ek.co/v1beta1`
`kind` string	`ScaleValidation`
`spec` ScaleValidationSpec
`status` ScaleValidationStatus

ScaleValidationSpec¶

ScaleValidationSpec defines the desired state of a ScaleValidation run.

Appears in: - ScaleValidation

Field	Description	Default	Validation
`targetRef` CrossVersionObjectReference	TargetRef points to the workload to validate (e.g. a Deployment).
`sla` Duration	SLA is the maximum allowed duration for HPA scale-up and pod readiness.
`target` TargetConfig	Target configures the HTTP endpoint and network routing for load traffic.
`load` LoadConfig	Load defines the synthetic traffic profile parameters.
`disruption` DisruptionConfig	Disruption configures optional chaos injection during the validation.		Optional: {}
`schedule` string	Schedule is an optional cron expression. When set, the validation re-runs on that schedule instead of running exactly once, and each verdict is appended to status.history so a trend is visible from `kubectl get -o json` alone. Standard five-field cron syntax plus the usual descriptors (@hourly, @daily, @every 1h30m). Runs never overlap: the schedule is evaluated only once a run has reached a terminal phase, so a run that overruns its interval delays the next one rather than racing it.		Optional: {}
`suspend` boolean	Suspend stops future runs, both scheduled ones and the run a spec edit would otherwise trigger. Setting it is itself a spec edit, so it has to outrank that, or suspending would start the very run it is meant to prevent. A run already in flight is left alone to finish, and the last verdict stays on status, so suspending is safe mid-run and reversible.	false	Optional: {}

ScaleValidationStatus¶

ScaleValidationStatus defines the observed state of a ScaleValidation run.

Appears in: - ScaleValidation

Field	Description	Validation
`phase` Phase	Phase represents the current lifecycle state.	Enum: [Pending Running Succeeded Failed Error Terminating]
`scaleUpDuration` Duration	ScaleUpDuration is the measured time from HPA trigger to all replicas ready.	Optional: {}
`slaStatus` Verdict	SLAStatus indicates whether the scaling met the configured SLA.	Enum: [Pass Fail Unknown]
`trafficIntegrity` Verdict	TrafficIntegrity indicates whether any requests were dropped.	Enum: [Pass Fail Unknown]
`totalRequests` integer	TotalRequests is the total number of HTTP requests sent during the run.
`failedRequests` integer	FailedRequests is the number of HTTP requests that returned errors.
`failureRateBasisPoints` integer	FailureRateBasisPoints is the ratio of failed to total requests in basis points: 1 bp is 0.01%, so 66 is 0.66% and the 1% traffic threshold is 100. An integer because the Kubernetes API convention rejects floats, which do not round-trip reliably across clients.
`diagnostics` DiagnosticAlert array	Diagnostics contains the list of analysis findings.	Optional: {}
`lastRunTime` Time	LastRunTime is the timestamp of the most recent validation execution.	Optional: {}
`history` RunSummary array	History holds the most recent terminal runs, newest first, bounded to RunHistoryLimit entries. Lets a single `kubectl get -o json` answer "did this get worse over the last N releases" without a metrics stack.	MaxItems: 10 Optional: {}
`nextRunTime` Time	NextRunTime is when the next scheduled run is due. Empty for a one-shot validation, and cleared while spec.suspend is true so `kubectl get` never advertises a run that will not happen.	Optional: {}
`observedGeneration` integer	ObservedGeneration is the metadata.generation the last terminal result was produced from. When it lags metadata.generation the spec has been edited since, and the controller starts a fresh run rather than leaving a result that describes a spec the object no longer carries.	Optional: {}
`conditions` Condition array	Conditions follow the standard Kubernetes conditions pattern.	Optional: {}

Severity¶

Underlying type: string

Severity bands a DiagnosticAlert. Critical means the run could not produce a trustworthy verdict; Warning means it did, with a caveat.

Validation: - Enum: [Info Warning Critical]

Appears in: - DiagnosticAlert

Field	Description
`Info`
`Warning`
`Critical`

SpikeWindow¶

SpikeWindow describes a single rate-elevated slice inside a Spike measurement phase. At is measured from the start of the measurement phase (post-warmup). Spikes are inserted between Constant base slices at BaseRPS, so the resulting phase list is constant-spike-constant-...

Appears in: - LoadProfile

Field	Description	Default	Validation
`at` Duration	At is the offset from measurement-phase start at which the spike begins.
`duration` Duration	Duration is the wall-clock length of the spike.
`rps` integer	RPS is the rate held during the spike. Must be > BaseRPS or the "spike" would actually be a dip.

TLSConfig¶

TLSConfig configures TLS verification for the loadgen client. InsecureSkipVerify and CABundle are mutually exclusive; setting both is rejected by CRD validation.

Appears in: - TargetConfig

Field	Description	Default	Validation
`insecureSkipVerify` boolean	InsecureSkipVerify disables certificate verification entirely. Use only for dev / CI clusters; production runs should pin a CA.	false	Optional: {}
`caBundle` CABundleSource	CABundle points to a ConfigMap key containing one or more PEM-encoded certificates trusted by the loadgen client.		Optional: {}

TargetConfig¶

TargetConfig describes the HTTP endpoint and network path to test.

Appears in: - ScaleValidationSpec

Field	Description	Default	Validation
`mode` TargetMode	Mode determines how the load test target is resolved.		Enum: [ServiceDefault AutoDiscoverProbe CustomPath]
`customPath` string	CustomPath is the explicit HTTP path to target. Used when mode is CustomPath.		Optional: {}
`port` integer	Port is the target port number.
`networkPath` NetworkPath	NetworkPath determines the routing pathway for load traffic. ClusterIP sends traffic directly to the Service inside the cluster. Ingress sends traffic through a classic Ingress controller (legacy path, prefer Gateway for new deployments). Gateway sends traffic through a Gateway API edge (Envoy Gateway and friends). Only one pathway runs per validation to isolate variables.	ClusterIP	Enum: [ClusterIP Ingress Gateway]
`host` string	Host overrides the URL host the loadgen Job hits. Empty (default) resolves to "..svc.cluster.local", which is correct for ClusterIP runs against a Service that shares the workload name. Set this to point load through an edge: e.g. the Envoy Gateway address for a Gateway run, or the Ingress LB hostname for the legacy Ingress path.		Optional: {}
`protocol` Protocol	Protocol selects the wire protocol the loadgen speaks to the target. HTTP1 uses fasthttp (default, backwards-compatible). HTTP2 uses net/http + http2.Transport: ALPN-negotiated h2 for https URLs, prior-knowledge h2c for http URLs. GRPC uses grpc-go to invoke the standard grpc.health.v1.Health/Check probe; combine with the optional GRPC block to scope the probe to a specific upstream service.	HTTP1	Enum: [HTTP1 HTTP2 GRPC] Optional: {}
`grpc` GRPCConfig	GRPC carries gRPC-specific knobs. Only consulted when Protocol=GRPC; ignored otherwise. Empty (or unset) means probe overall server health on the resolved Service host:port.		Optional: {}
`tls` TLSConfig	TLS configures HTTPS verification for the loadgen client. Only applies when the resolved target URL uses the https scheme.		Optional: {}

TargetMode¶

Underlying type: string

TargetMode selects how the load generator resolves an endpoint.

Validation: - Enum: [ServiceDefault AutoDiscoverProbe CustomPath]

Appears in: - TargetConfig

Field	Description
`ServiceDefault`
`AutoDiscoverProbe`
`CustomPath`

Verdict¶

Underlying type: string

Verdict is a pass/fail judgement. Unknown means the run could not measure the thing, which is deliberately not the same as failing it.

Validation: - Enum: [Pass Fail Unknown]

Appears in: - RunSummary - ScaleValidationStatus

Field	Description
`Pass`
`Fail`
`Unknown`