feat(interceptor): add customizable cold start message

[richard-senior]

Add customizable cold start message for scale-to-zero applications

Problem

Specifically when scaling to zero, which will almost always be on a non-prod environment.
It would be nice to improve the UX for developers who are trying to test their application which has
been scaled to zero, by a mechanism they are unaware of (Keda).
When applications are scaled to zero the addon provides a choice of user experiences:

1. No response until the first pod is ready - Browser shows loading spinner for 30-60 seconds while waiting for pods to start
2. Fallback to a separate service - Using coldStartTimeoutFailoverRef, route to a different service after a timeout (default
   30 seconds), requiring deployment and maintenance of an additional failover service
3. Immediate timeout - If timeouts.conditionWait is set to a very low value, users get an immediate 502 Bad Gateway error with
   no context

Percieved limitations:

• Option 1: Poor UX - users see browser spinner with no feedback, devs worry.
• Option 2: Complex - requires deploying and maintaining a separate failover service
  If we've scaled everything to zero (particularly if Karpenter has scaled the nodes) then where would
  we deploy the failover if we wanted to use it simply as a UX enhancement?
• Option 3: Confusing - users see generic error with no explanation that the service is starting

Solution

Add optional coldStartMessage field to HTTPScaledObject that displays a user-friendly HTML page immediately when no endpoints are available.

Features:

• Immediate response (no waiting)
• Auto-refresh (HTTP Meta Refresh) every 5 (n) seconds
• XSS protection via HTML escaping
• Fully backward compatible (opt-in)
• Per-application (namepsace) customization

Example Configuration

apiVersion: http.keda.sh/v1alpha1
kind: HTTPScaledObject
metadata:
  name: my-app
spec:
  hosts:
    - myapp.example.com
  scaleTargetRef:
    service: my-app-service
  coldStartMessage: "Waking up the application, please wait..."
  replicas:
    min: 0
    max: 10

Implementation

• Added ColdStartMessage field to HTTPScaledObjectSpec CRD
• Modified interceptor to detect zero endpoints and return HTML immediately
• Includes comprehensive unit tests with XSS protection validation
• Default fallback message if not configured

Testing

• ✅ Unit tests pass (HTML generation, XSS protection)
• ✅ Tested locally with docker-desktop cluster
• ✅ Verified backward compatibility (existing HTTPScaledObjects unchanged)
• ✅ Tested with real application cold start scenario

Files Changed

• operator/apis/http/v1alpha1/httpscaledobject_types.go - Add ColdStartMessage field to CRD (+5 lines)
• config/crd/bases/http.keda.sh_httpscaledobjects.yaml - Generated CRD schema with new field (+6 lines)
• interceptor/proxy_handlers.go - Cold start detection and HTML response logic (+25 lines)
• interceptor/warming_page.go - HTML generator with XSS protection (96 lines, new file)
• interceptor/warming_page_test.go - Comprehensive unit tests (99 lines, new file)

Total: 5 files changed, 231 lines added

Benefits

• Improves user experience during cold starts
• Makes scale-to-zero more practical for development/staging environments
• Enables true cost optimization - scale to zero without sacrificing UX
• Provides clear feedback that the system is working
• No breaking changes - fully backward compatible
• Simple implementation with minimal code complexity
• Works seamlessly with node autoscalers like Karpenter (no pods = no nodes = maximum savings)

Please examine this submission and determine if it is a feature you'd like to add.
This would obviously helm me out greatly, since I wouldn't have to maintain my fork :)

---

Richard Senior
Produced with the assistance of Kiro (AWS AI assistant)

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[linkvt]

Hi @richard-senior ,
thanks for your PR!
It really seems to be a highly requested feature, did you also have a look at PR #1303 ? That PR implements the same feature and even a bit more considering templating etc. There are also a few comments at the bottom about whats happening next.

[richard-senior]

Hi.. I didn't actually check if this feature was already in progress.
I submitted the PR because I'd already done this for our own purposes.
#1303 looks good.

[linkvt]

I'll go ahead and close this PR then, the other one should contain the changes proposed here. As commented there I hope that we can merge this feature soon.

Thanks again for the work! 🫶