* spec(#749): scaling playbook + phase-1 AppRouter auto-scaling Two deliverables in one PR: 1. New architecture doc docs/developers/architecture/scaling-playbook.md enumerating 12 scaling constraints (rate limiters, cron separation, WebSocket sticky, BLOB LRU, content publish race, HANA pool, sequence generators, fetchers, Hugo, CDN, read replicas, AppRouter). For each: current pin, what breaks, fix path, effort, dependencies. Recommended sequence: #1 → #3 → #2 → #4 → others as needed. 2. Phase-1 implementation: AppRouter auto-scaling via CF Autoscaler service binding. mta.yaml + .deploy/mta.yaml + new deploy/autoscaler-policy.json. Zero code change — AppRouter is already stateless (XSUAA cookies). Tom's note on row #3 (cron): SAME-BINARY env-flag-gated separation ('tutorials-cron' MTA module reuses path: gen/srv with ENABLE_CRON=true), NOT a codebase split. JobLocks already covers correctness. * spec(#749): apply spec-reviewer feedback (iteration 1) Blocking fixes: - §2.1: Autoscaler policy now inlined under requires[*].parameters.config (standard SAP BTP pattern), NOT on the resource via path:. The resource block declares only service/plan; the binding-level config is what the autoscaler actually consumes. Pre-this fix, deploy would have silently bound the autoscaler with no policy → no scaling rules fire, invisible until §5.4 synthetic-load test surfaces it. - §2.1: add 'Service-name regional drift' note — confirm marketplace name (autoscaler vs application-autoscaler) before merge. - §2.3: removed deploy/autoscaler-policy.json file from scope; policy is now inline in the two mta.yaml files (small duplication, intentional). Playbook completeness: - Row #5 expanded from 'content-store LRU' to 'per-instance in-memory caches' with the full set: content-store BLOBs, advocate-photo-store, alerts-cache (60s TTL — CLAUDE.md callout), admin-docs-index, ttl-cache, khoros-cache. Same fix category, more accurate scope. - New rows #13 (audit-log throughput), #14 (AI Core quota cluster- aware retry), #15 (credstore cold-start). 12 → 15 rows. Hidden-assumption fix: - Row #3 (cron separation) now flags 'audit all 16 jobs for acquire- before-side-effect ordering before splitting' as a pre-flight step. JobLocks covers the lock primitive; caller code must order acquireLock() before the side effect. instances:1 masks this today. Doc-quality fix: - §7 sidebar guidance now shows the exact entry shape so the implementer can't get the predocs:build guard wrong. * spec(#749): apply spec-reviewer feedback (iteration 2) Cleanup pass on stale references to the removed deploy/autoscaler-policy.json: - §Approach: '12 playbook constraints' -> '15 playbook constraints' (count was updated everywhere else in iter 1, missed this line). - §3 data-flow diagram: rewrite to reflect inline-policy reality. Removed 'mbt build packages deploy/autoscaler-policy.json into the MTAR slice' step (no separate file exists); added 'mbt build embeds both into the MTA descriptor' instead. - §4.2: 'Policy JSON malformed' -> 'Policy YAML malformed'. Drop the node -e JSON.parse() guard against the removed file; rely on mbt build's YAML validation of the descriptor. - §5.3 pre-deploy validation: drop the JSON.parse() guard; update cf marketplace command to grep -iE so either service-name variant matches; rely on mbt build for YAML validation. Doc-consistency cleanup only; no architectural changes. * plan(#749): implementation plan — scaling playbook + AppRouter autoscaling 7 tasks: 1. Write docs/developers/architecture/scaling-playbook.md (15-row table + per-row prose + recommended sequence). 2. Register playbook in VitePress sidebar. 3. Cross-link mta-deployment.md to the playbook. 4. Add tutorials-autoscaler binding + inline policy to mta.yaml. 5. Symmetric change in .deploy/mta.yaml. 6. PR (with full body file written via heredoc). 7. Post-merge deploy with cf marketplace pre-flight + envsubst. * plan(#749): apply plan-reviewer feedback (iter 1) Three minor polish fixes (none blocking): 1. Task 7 Step 5 — replace fragile 'grep && fail || ok' idiom with proper if/then/else. The old form misreports OK if grep exits with code 2 (regex error) instead of 1 (no match). 2. Task 2 Step 2 — replace the alphabetical-slot guess with a verifier command ('grep -n developers/architecture …') so the implementer picks the correct neighbor instead of guessing. 3. Task 6 title — 'Verify CI green' -> 'Push, create PR, verify CI green' (the task does all three, the title underdescribed). * docs(#749): add scaling playbook Forward-looking architecture doc enumerating 15 known scaling constraints. For each: current pin, what breaks at N>1 or under load, fix path, rough effort, dependencies on other rows. Recommended sequence: #1 AppRouter auto-scaling (this PR) -> #3 cron separation -> #2 rate limiters -> #4 WebSocket sticky -> others as traffic forces. Covers ~5x current traffic without bigger Redis or read-replica work. This doc is the long-lived reference; subsequent scaling PRs each crack off one row and update the table's status. * docs(#749): register scaling-playbook in VitePress sidebar The predocs:build sidebar guard (scripts/check-docs-sidebar.cjs) fails the build if a docs/developers/architecture/*.md file isn't registered. Adding the entry at the end of the architecture section. * docs(#749): cross-link mta-deployment to scaling-playbook The narrow rate-limiter section already lives here; the broader playbook now exists at architecture/scaling-playbook.md. Anyone arriving at the rate-limiter doc finds the broader context. * feat(#749): add CF Autoscaler binding to tutorials-approuter (mta.yaml) Phase-1 of the scaling playbook (row #1). Approuter is already stateless (XSUAA cookie-based), so this is a deploy-config-only change. Range 1..4, CPU 70% / 30% thresholds. The autoscaler policy is INLINED under requires[*].parameters.config on the tutorials-approuter module — the SAP BTP convention. Putting the policy on the resource block via path: would be silently ignored and result in a binding with no scaling rules (verified during spec review). Zero code change anywhere. AppRouter scales horizontally on its own under sustained CPU load. * feat(#749): add CF Autoscaler binding to tutorials-approuter (.deploy/mta.yaml) Symmetric change to the standalone-approuter MTA variant. Same inline policy as mta.yaml — the ~20-line duplication is intentional (MTA spec doesn't support yaml-anchor sharing across files cleanly). A future refactor could extract via mtaext; out of scope here. --------- Co-authored-by: Thomas Jung <12159356+jung-thomas@users.noreply.github.com>

Scaling Ideas #749

Description

Activity

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions