feat: allow an external autoscaler to own proxy Deployment replicas

[guanchzhou]

What this PR does

Adds replicasManagedByExternalAutoscaler to the Envoy proxy KubernetesDeploymentSpec. When set to true, Envoy Gateway omits the replicas field from the generated proxy Deployment, so an external autoscaler — a user-managed HorizontalPodAutoscaler, a KEDA ScaledObject, etc. — can own the replica count without Envoy Gateway reverting it on the next reconcile.

Why

Envoy Gateway applies the proxy Deployment with server-side apply + ForceOwnership, so it owns spec.replicas and reverts any externally computed value unless the built-in envoyHpa is configured. But envoyHpa only supports what a native HPA metrics spec can express — it can't drive Prometheus-query / event-driven scaling that KEDA provides.

Today the only workaround is to template-unset envoyDeployment.replicas so Envoy Gateway doesn't own the field — brittle, and it has to be repeated per gateway. This is the same class of problem as the stale #5751; the recent fix that omits spec.replicas under an HPA only covers the built-in envoyHpa, not external autoscalers.

Fixes #9627.

Implementation

• API (api/v1alpha1/shared_types.go): new optional ReplicasManagedByExternalAutoscaler *bool on KubernetesDeploymentSpec.
• Controller (internal/infrastructure/kubernetes/proxy/resource_provider.go): replicas is left nil when the flag is set or EnvoyHpa != nil. Semantics mirror the existing envoyHpa path — when set, Replicas is ignored (precedence, no hard rejection, which is friendlier for GitOps migrations). Deployment only (DaemonSet has no replicas).
• Regenerated deepcopy, both envoyproxies CRDs, and the API reference.
• Docs: a new "Scale EnvoyProxy with an External Autoscaler" section in customize-envoyproxy.md, including how to target the Deployment via a pinned envoyDeployment.name or the stable gateway.envoyproxy.io/owning-gateway-* labels, with a KEDA ScaledObject example.
• Release note fragment added.

Testing

New golden test case with-external-autoscaler asserts spec.replicas is absent when the flag is set and no envoyHpa is configured (the exact fingerprint of the bug), and unchanged otherwise.

go build ./...                                            # ok
go test ./internal/infrastructure/kubernetes/proxy/...    # ok
go test ./api/...                                         # ok
gofmt -l / go vet                                         # clean

Open question for maintainers

Boolean (replicasManagedByExternalAutoscaler, as here) vs. an enum (replicaManagement: EnvoyGateway | External). Happy to switch to whichever you prefer. A follow-up PR can mirror the field on the rate limit deployment for symmetry.

[netlify]

✅ Deploy Preview for cerulean-figolla-1f9435 ready!

Name	Link
🔨 Latest commit	d2496f9
🔍 Latest deploy log	https://app.netlify.com/projects/cerulean-figolla-1f9435/deploys/6a6c8e40b313060008decbef
😎 Deploy Preview	https://deploy-preview-9628--cerulean-figolla-1f9435.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9d0fadb8a4

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.04%. Comparing base (b710dd4) to head (d2496f9).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #9628   +/-   ##
=======================================
  Coverage   76.04%   76.04%           
=======================================
  Files         259      259           
  Lines       43275    43277    +2     
=======================================
+ Hits        32907    32912    +5     
+ Misses       8178     8176    -2     
+ Partials     2190     2189    -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[arkodg]

does #9594 fix this issue ?

[guanchzhou]

@arkodg Not quite — #9594 and this PR are complementary:

• fix: don't set Deployment replicas when an HPA is configured #9594 (merged) omits spec.replicas when the built-in envoyHpa / rateLimitHpa is configured.
• This PR handles the case where an external autoscaler owns replicas and EG's built-in HPA is not used — via an opt-in replicasManagedByExternalAutoscaler field. It extends the exact same condition fix: don't set Deployment replicas when an HPA is configured #9594 added:

if provider.GetEnvoyProxyKubeProvider().EnvoyHpa != nil ||
    ptr.Deref(deploymentConfig.ReplicasManagedByExternalAutoscaler, false) {
    replicas = nil
}

The motivating case is a KEDA ScaledObject (or a user-managed HPA) scaling the proxy fleet on a Prometheus/event-driven trigger — something the built-in envoyHpa can't express, since it only takes a native HPA metrics spec. With #9594 alone, those users still have to template-unset envoyDeployment.replicas to stop the controller reverting the externally-computed count (the exact workaround this PR removes). The ratelimit Deployment path is covered symmetrically.

Happy to rebase or adjust naming (boolean vs an enum like replicaManagement: External) if you'd prefer.

[zirain]

replicaManagement: External looks better from my POV.