feat(auto scaling): add StackableScaler CRD, state machine, ReplicasConfig, and scaling hooks

[soenkeliebau]

Summary

Introduces the StackableScaler CRD and supporting framework for HPA-integrated scaling
with operator-controlled lifecycle hooks. The HPA targets the StackableScaler's /scale
subresource instead of the StatefulSet directly, giving product operators the opportunity
to run pre/post-scale hooks (e.g. NiFi node offloading, Trino graceful shutdown) before
replica changes propagate.

fixes stackabletech/issues#667

Key additions:

• StackableScaler CRD (autoscaling.stackable.tech/v1alpha1) with /scale subresource,
  5-stage state machine (Idle -> PreScaling -> Scaling -> PostScaling -> Idle, plus Failed),
  and annotation-based retry recovery
• ReplicasConfig enum -- Fixed(u16), Hpa(HpaConfig), Auto(AutoConfig),
  ExternallyScaled -- with flexible deserialization (bare integer, string, or typed object)
  and validation
• ScalingHooks trait with pre_scale(), post_scale(), and on_failure() lifecycle
  hooks, ScalingContext with direction-aware helpers (removed_ordinals(),
  added_ordinals()), and HookOutcome (Done/InProgress) for async hook execution
• reconcile_scaler() -- state machine reconciler that drives stage transitions, calls
  hooks, handles failures, and returns ScalingResult with requeue action + ScalingCondition
  for cluster CR status propagation
• build_scaler() / build_hpa_from_user_spec() -- builders for StackableScaler and HPA
  objects with deterministic naming, standard app.kubernetes.io labels, and owner references
• initialize_scaler_status() -- seeds scaler status on first reconcile to prevent
  scale-to-zero (status defaults to replicas: 0 before initialization)
• JobTracker -- idempotent Kubernetes Job lifecycle manager for hook execution with
  DNS-safe name generation and automatic cleanup
• ClusterResource / DeepMerge impls for StackableScaler, enabling ClusterResources
  lifecycle management and orphan cleanup
• Versioned macro extension -- #[versioned(k8s(scale(...)))] attribute support for
  generating CRDs with the /scale subresource

Motivation

Kubernetes HPAs can target StatefulSets directly, but this bypasses the operator -- there is
no interception point for product-specific lifecycle tasks before pods are terminated. For
NiFi, this means flowfile data is not offloaded before node removal, causing data loss. For
Trino, active queries are killed mid-execution. The StackableScaler provides that
interception point as a generic, reusable framework.

Notable design choices

• Spec contains only replicas: i32 -- identity is derived from owner references and
  app.kubernetes.io labels. This keeps the CRD minimal and avoids redundant fields that
  could drift from the cluster CR.
• Failed is a terminal trap state -- the state machine cannot leave Failed without an
  explicit autoscaling.stackable.tech/retry annotation. This prevents infinite retry loops
  on persistent hook failures and requires human acknowledgment.
• ReplicasConfig custom deserialization -- accepts replicas: 3 (Fixed), replicas: externallyScaled, or replicas: { hpa: { maxReplicas: 10, ... } } in a single field,
  maintaining backward compatibility with existing integer-based configs.
• HpaConfig wraps HorizontalPodAutoscalerSpec -- users provide standard HPA fields
  (maxReplicas, minReplicas, metrics, behavior); scaleTargetRef is overwritten
  internally to point at the StackableScaler.

Test plan

• cargo test --all-features passes -- unit tests cover state machine transitions,
  ReplicasConfig deserialization/validation, builder output, job naming, hook direction
  derivation, and serialization round-trips
• cargo clippy --all-targets --all-features -- -D warnings clean
• cargo doc --no-deps --all-features produces no warnings
• Verify StackableScaler CRD schema generates correctly with scale subresource paths
• Integration test with commons-operator and nifi-operator PRs: HPA targets
  StackableScaler, state machine drives hooks through full scale-up/scale-down cycle

Author

• Changes are OpenShift compatible
• CRD changes approved
• CRD documentation for all fields, following the style guide.
• Integration tests passed (for non trivial changes)
• Changes need to be "offline" compatible

Reviewer

• Code contains useful comments
• Code contains useful logging statements
• (Integration-)Test cases added
• Documentation added or updated. Follows the style guide.
• Changelog updated
• Cargo.toml only contains references to git tags (not specific commits or branches)

Acceptance

• Feature Tracker has been updated
• Proper release label has been added