<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Close this issue](https://contributors.gitlab.com/manage-issue?action=close&projectId=278964&issueIid=627488) </details> <!--IssueSummary end--> ## Problem to solve GitLab's documented recommendation for scaling the Feature Flags API is [Unleash Proxy](https://docs.gitlab.com/operations/feature_flags/#unleash-proxy-example), which Unleash has deprecated and whose reference documentation now redirects to [*"Migrate from Unleash Proxy to Enterprise Edge"*](https://docs.getunleash.io/unleash-edge/migrate-from-proxy) We need a recommendation that does not depend on a withdrawn, commercially-redirected upstream component. This is the anchor item for the epic: its output is a **decision and a documented recommendation**, not an implementation. ## Current state | Fact | Value | Source | | --- | --- | --- | | FF API rate limit classification | Unauthenticated traffic, per source IP | [Feature flags docs](https://docs.gitlab.com/operations/feature_flags/#maximum-supported-clients-in-application-nodes) | | GitLab.com limit for that class | 500 requests / minute | [GitLab.com rate limits](https://docs.gitlab.com/user/gitlab_com/#rate-limits-on-gitlabcom) | | Shared ceiling, all traffic per IP | 2,000 requests / minute | same | | Documented client capacity | ~500 clients @ 1 req/min; ~125 @ 1 req/15s | Feature flags docs | | Documented scaling mitigation | Unleash Proxy, tune `UNLEASH_FETCH_INTERVAL` | Feature flags docs | | Unleash Proxy status | Deprecated; reference docs withdrawn, now redirecting to a commercial migration page. A 2026-11-26 EOL date is reported on #426415 but **unconfirmed against any Unleash source** | [Migration guide](https://docs.getunleash.io/unleash-edge/migrate-from-proxy) | | Unleash Edge OSS | LTS 2025-12-12, **EOL 2026-12-31**; maintained build is Enterprise-licensed | [Unleash docs](https://docs.getunleash.io/unleash-edge#unleash-edge-oss) | | Why Edge fails against GitLab | GitLab implements a pre-v4 Unleash environment model; from v4 Unleash encodes the environment in the API key. Edge also requires *valid* Unleash tokens rather than arbitrary secrets, and does not support the custom activation strategies GitLab environment segregation needs | [Unleash maintainer, #5515](https://github.com/orgs/Unleash/discussions/5515), [migration guide](https://docs.getunleash.io/unleash-edge/migrate-from-proxy) | ## Options considered - **Option A: Raise the API's own capacity.** Reclassify FF traffic as authenticated in `Rack::Attack`, per [#295472](https://gitlab.com/gitlab-org/gitlab/-/issues/295472). Takes the ceiling from 500 to 2,000 req/min per IP — a 4× increase, and enough that mid-sized deployments need no proxy at all. Throttle classification change, not new product surface; Free tier; community-contribution eligible. - **Option B: Document a GitLab-owned caching reference pattern. Any cache that speaks the Unleash client API and polls GitLab on a controlled schedule achieves what the Proxy achieves, with no expiring upstream dependency. Customer reports indicate that deployments have built layers of this shape, but GitLab has not seen or validated one. The work is therefore to derive the requirements from the API's own behavior — cache key, revalidation, staleness, and failure modes — and publish them with a worked example. This needs observation of the endpoint, not feature development. - **Option C: Issue Unleash-format client tokens.** Would unlock Edge and other ecosystem tooling. Largest change of the three, requires engineering investment this category does not currently have, and points at a component whose OSS build is itself EOL on 2026-12-31. Recorded as a decision (work item 4 in the epic), not scheduled here. - **Option D: Do nothing.** Explicitly rejected. It means that from December 2026 our published guidance points at two dead components, which is not a defensible position on an in product feature. ## Proposal Pursue **A + B**. A raises the floor so that most deployments never need a proxy; B gives the deployments that still do a pattern that does not expire. Neither requires feature development. C is documented as a decision with a stated rationale so it stops being an implicit open question. ## Acceptance criteria - [ ] A scoping decision is recorded on #295472 - [ ] The Feature Flags docs carry an explicit rate limit figure, state that the limit is **per source IP**, and name distributing clients across egress addresses as a supported mitigation. - [ ] The Feature Flags docs carry honest deprecation guidance: Proxy's EOL date, the fact that deprecated is not non-functional, and that Unleash Edge is not compatible — with the reason and a link. - [ ] A caching reference pattern is documented, with the requirements a cache must meet to sit in front of the FF API. - [ ] A recorded decision exists on the client token model, so #426415's question is answered rather than dormant. - [ ] #426415 and the `unleash-edge` docs issue are closed, each pointing at this work item ## Out of scope - Per-environment flag permissions (#8239 Phase 3); - multivariate flag values; - an OpenFeature-compatible API; - any change to flag-count limits per project. ## Success measures - lower 429 rate on /api/v4/feature_flags/unleash/* after any reclassification lands. - Support tickets and public issues whose root cause is Proxy/Edge deprecation confusion trend downards - The question "what is the FF API rate limit?" is answerable from a single documentation page.