docs: clarify that scheduled scaling can exceed spec max processing units (#250)

* chore: regenerate SpannerManualScaling CRD manifest

The go-deps bump (#248) updated controller-tools to v0.21.0, and the
SpannerManualScalingSpec godoc was revised in #242 after the manifest
was last generated, but config/crd/bases was not regenerated. Run
'make manifests' so the checked-in YAML matches the current toolchain
and godoc.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: clarify that scheduled scaling can exceed spec max processing units

The scheduled scaling section explained that additionalProcessingUnits
"bumps up the scaling range", but never stated the key operational fact:
while a SpannerAutoscaleSchedule is active, the value is added to both
ends of the autoscaling range, so the instance can be scaled beyond
spec.scaleConfig.processingUnits.max by that amount. This has caused
operators to read PU values above spec max as a controller bug.

Spell the behavior out in the README (effective range, exceeding max,
the raised lower bound, and reverting when the window ends) and in the
AdditionalProcessingUnits godoc so the generated CRD description and
docs/crd-reference.md carry the same explanation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: tkuchiki

README.md

@@ -45,6 +45,8 @@ spec:
 
 The `cron` field supports extended syntax (`L`, `L-n`, `nW`, `LW`, `DAY#n`, `DAY#L`) in addition to the standard 5-field format, powered by [go-cron](https://github.com/netresearch/go-cron). See the [Extended Syntax documentation](https://pkg.go.dev/github.com/netresearch/go-cron#hdr-Extended_Syntax__Optional_) for details and examples.
 
+> **Note:** While a schedule is active, `additionalProcessingUnits` is added to **both ends** of the autoscaling range: the effective range becomes `[spec.processingUnits.min + additionalProcessingUnits, spec.processingUnits.max + additionalProcessingUnits]` (exposed as `status.desiredMinPUs` / `status.desiredMaxPUs`). This means the instance can be scaled **beyond `spec.processingUnits.max`** — with `max: 1000` and the schedule above, the instance may reach 1,600 PU while the schedule is active. Because the lower bound is raised as well, the instance is scaled up to at least `min + additionalProcessingUnits` even when CPU utilization is low. Once the schedule's window (`duration`) ends, the range reverts to the values in `spec`, and the instance scales back down after the configured scale-down interval.
+
 > **Note:** When multiple schedules are active simultaneously (i.e. their windows overlap), the `additionalProcessingUnits` from all active schedules are **summed** and added to both `desiredMinPUs` and `desiredMaxPUs`. For example, if schedule A adds +1,000 PU and schedule B adds +5,000 PU and both are active at the same time, `desiredMinPUs = spec.processingUnits.min + 6,000`.
 
 ### Scale down time restrictions

api/v1beta1/spannerautoscaleschedule_types.go

@@ -38,6 +38,9 @@ type SpannerAutoscaleScheduleSpec struct {
 	TargetResource string `json:"targetResource"`
 
 	// The extra compute capacity which will be added when this schedule is active.
+	// While active, this value is added to both the minimum and maximum of the target
+	// SpannerAutoscaler's autoscaling range, so the instance can be scaled beyond
+	// `spec.scaleConfig.processingUnits.max` by this amount.
 	AdditionalProcessingUnits int `json:"additionalProcessingUnits"`
 
 	// The details of when and for how long this schedule will be active.

config/crd/bases/spanner.mercari.com_spannerautoscaleschedules.yaml

@@ -52,8 +52,11 @@ spec:
               SpannerAutoscaleSchedule
             properties:
               additionalProcessingUnits:
-                description: The extra compute capacity which will be added when this
-                  schedule is active.
+                description: |-
+                  The extra compute capacity which will be added when this schedule is active.
+                  While active, this value is added to both the minimum and maximum of the target
+                  SpannerAutoscaler's autoscaling range, so the instance can be scaled beyond
+                  `spec.scaleConfig.processingUnits.max` by this amount.
                 type: integer
               schedule:
                 description: The details of when and for how long this schedule will

config/crd/bases/spanner.mercari.com_spannermanualscalings.yaml

@@ -3,7 +3,7 @@ apiVersion: apiextensions.k8s.io/v1
 kind: CustomResourceDefinition
 metadata:
   annotations:
-    controller-gen.kubebuilder.io/version: v0.20.1
+    controller-gen.kubebuilder.io/version: v0.21.0
   name: spannermanualscalings.spanner.mercari.com
 spec:
   group: spanner.mercari.com
@@ -64,14 +64,25 @@ spec:
               scaledownAllowedTimes / scaledownNotAllowedTimes windows for as long as it
               is active.
 
-              Pacing is inferred from the presence of the step-size field for the required
-              direction:
+              The target may be above or below the current processing units. The
+              controller picks the direction from the sign of
+              (ProcessingUnits - CurrentProcessingUnits) and reads only the step-size /
+              interval fields for that direction. Pacing is inferred from the presence
+              of the step-size field:
 
-                - ScaleupStepSize unset (when target > current)  → single-jump scale-up.
-                - ScaleupStepSize set    (when target > current) → stepped ramp; the
-                  cadence comes from ScaleupInterval when set, otherwise from the
+                - target > current, ScaleupStepSize unset      → single-jump scale-up.
+                - target > current, ScaleupStepSize set        → stepped scale-up ramp;
+                  the cadence comes from ScaleupInterval when set, otherwise from the
                   controller's --scale-up-interval flag default.
-                - ScaledownStepSize / ScaledownInterval behave symmetrically.
+                - target < current, ScaledownStepSize unset    → single-jump scale-down.
+                - target < current, ScaledownStepSize set      → stepped scale-down ramp;
+                  the cadence comes from ScaledownInterval when set, otherwise from the
+                  controller's --scale-down-interval flag default.
+
+              Manual scale-down is accepted by default. Cluster operators who want to
+              forbid it can run the controller with --reject-manual-scaledown=true; in
+              that mode an override whose target is below the current PU lands in the
+              Invalid phase rather than scaling the instance down.
 
               Interval-only specification (e.g. ScaleupInterval set but ScaleupStepSize
               unset) has no effect; the validating webhook emits an admission warning to
@@ -106,8 +117,11 @@ spec:
               processingUnits:
                 description: |-
                   ProcessingUnits is the target value that this override drives toward
-                  while active. Must be a multiple of 100 (for values < 1000) or a
-                  multiple of 1000.
+                  while active. May be above or below the autoscaler's current PU; the
+                  controller derives the scaling direction from the sign of
+                  (ProcessingUnits - CurrentProcessingUnits) and consults the matching
+                  step-size / interval fields below. Must be a multiple of 100 (for
+                  values < 1000) or a multiple of 1000.
                 minimum: 100
                 type: integer
               scaledownInterval:

docs/crd-reference.md

@@ -297,7 +297,7 @@ _Appears in:_
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
 | `targetResource` _string_ | The `SpannerAutoscaler` resource name with which this schedule will be registered.<br />Immutable after creation. |  |  |
-| `additionalProcessingUnits` _integer_ | The extra compute capacity which will be added when this schedule is active. |  |  |
+| `additionalProcessingUnits` _integer_ | The extra compute capacity which will be added when this schedule is active.<br />While active, this value is added to both the minimum and maximum of the target<br />SpannerAutoscaler's autoscaling range, so the instance can be scaled beyond<br />`spec.scaleConfig.processingUnits.max` by this amount. |  |  |
 | `schedule` _[Schedule](#schedule)_ | The details of when and for how long this schedule will be active. |  |  |