# Hangar: fleet governance control plane ## Why [&450](https://gitlab.com/groups/gitlab-org/quality/-/work_items/450) delivers a host an engineer can self-serve into: their own namespace, their own vcluster, a 24-hour TTL. Enough for the people building it. Not enough for a modular service team, where the environment has to belong to the team rather than to whoever ran `caproni up` first, and where nobody can see what the fleet is running or costing. It is also where the admission guardrails left open by the threat model and the [#4627](https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/work_items/4627) reach decision are tracked, because each is a property of the fleet rather than of one environment. ## What Ownership moves from a person to a team group, a namespace becomes one environment capped per team, and the fleet becomes visible: quotas, a registry, an orphan report, cost per team. Alongside it, the guardrails that make one host safe to share between tenants who have no reason to trust each other. ## Plan Ownership and visibility: | Issue | Delivers | Waits on | |--|--|--| | [#4621](https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/work_items/4621) | Group-owned namespaces | nothing. Google Groups for RBAC is a cluster update, not a rebuild | | [#4635](https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/work_items/4635) | Per-group operator mapping: TTL cap and namespace prefix | nothing to land; [caproni#252](https://gitlab.com/gitlab-org/caproni/-/work_items/252) before a prefixed namespace is reachable | | [#4622](https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/work_items/4622) | Cap the number of namespaces a team can hold | gitlab-org/quality/quality-engineering/team-tasks#4621, gitlab-org/quality/quality-engineering/team-tasks#4635 | | [#4624](https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/work_items/4624) | Per-group TTL caps | gitlab-org/quality/quality-engineering/team-tasks#4621, gitlab-org/quality/quality-engineering/team-tasks#4635 | | [#4623](https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/work_items/4623) | Report orphaned namespaces when a team disbands | gitlab-org/quality/quality-engineering/team-tasks#4621 | | [#4625](https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/work_items/4625) | Environment registry | nothing. Carries the &319 boundary conversation | | [#4637](https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/work_items/4637) | Per-team cost reporting | [&457](https://gitlab.com/groups/gitlab-org/quality/-/work_items/457) for the permanent home and billing | | [#4648](https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/work_items/4648) | Hangar adoption and usage dashboard | nothing; per-team view after gitlab-org/quality/quality-engineering/team-tasks#4621 | | [#4649](https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/work_items/4649) | Hangar component page in the Theseus docs | nothing | **One dependency outside our control.** A group-owned namespace carries its team's prefix ([#4635](https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/work_items/4635)), so names are chosen, like `delivery-main`. The generated route resolves only when the vcluster's name equals its namespace, and caproni derives that name from the profile: `static` is always the literal `caproni`, and `directory-hash` gives `caproni-<dir>-<hash>`. Neither produces a chosen name, so the `directory-hash` workaround the host uses today disappears the moment ownership moves to a group. [caproni#252](https://gitlab.com/gitlab-org/caproni/-/work_items/252) closes it: [caproni!882](https://gitlab.com/gitlab-org/caproni/-/merge_requests/882) publishes the synced backend name and port as annotations on the host namespace, and the host policy reads them instead of rebuilding the name. It does not block #4621 or #4635 from landing; it blocks anyone from reaching what they produce until it is released and the host policy switches over. Guardrails: | Issue | Delivers | Waits on | |--|--|--| | [#4641](https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/work_items/4641) | Deny `LoadBalancer` and `NodePort` Services in tenant namespaces | nothing | | [#4642](https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/work_items/4642) | Pod security baseline for tenant namespaces | nothing | | [#4636](https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/work_items/4636) | `ResourceQuota` and `LimitRange` per namespace | nothing | | [#4640](https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/work_items/4640) | Alerting on compute consumption | nothing | | [#4626](https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/work_items/4626) | Close the Kyverno default-exclusion escape hatch | nothing | | [#4634](https://gitlab.com/gitlab-org/quality/quality-engineering/team-tasks/-/work_items/4634) | Threat model follow-ups conditional on the gitlab-org/quality/quality-engineering/team-tasks#4627 ruling | nothing. The ruling landed 2026-09-08 | Design target: [`docs/tenancy-model.md`](https://gitlab.com/gitlab-org/quality/hangar-poc/-/blob/main/docs/tenancy-model.md). The ownership policy is hangar's side of the boundary agreed with the caproni team, forked into [hangar-poc](https://gitlab.com/gitlab-org/quality/hangar-poc) and maintained there, so nothing here waits on caproni. ## Picking this up Eleven of the fifteen have no sibling dependency. Three wait on a sibling, and one waits outside the epic. **Independent leaves, nothing in the epic waits on them.** gitlab-org/quality/quality-engineering/team-tasks#4625, gitlab-org/quality/quality-engineering/team-tasks#4626, gitlab-org/quality/quality-engineering/team-tasks#4636, gitlab-org/quality/quality-engineering/team-tasks#4640, gitlab-org/quality/quality-engineering/team-tasks#4641, gitlab-org/quality/quality-engineering/team-tasks#4642, gitlab-org/quality/quality-engineering/team-tasks#4648, gitlab-org/quality/quality-engineering/team-tasks#4649. The most useful of these to take now are gitlab-org/quality/quality-engineering/team-tasks#4636, gitlab-org/quality/quality-engineering/team-tasks#4640 and gitlab-org/quality/quality-engineering/team-tasks#4641, for the reason in Sequencing below. gitlab-org/quality/quality-engineering/team-tasks#4641 and gitlab-org/quality/quality-engineering/team-tasks#4642 both have to be verified as a real non-Owner tenant, which is what [hangar-poc#1](https://gitlab.com/gitlab-org/quality/hangar-poc/-/work_items/1) provides. **Independent, but the roots.** gitlab-org/quality/quality-engineering/team-tasks#4621 and gitlab-org/quality/quality-engineering/team-tasks#4635 are startable today, and gitlab-org/quality/quality-engineering/team-tasks#4622, gitlab-org/quality/quality-engineering/team-tasks#4623 and gitlab-org/quality/quality-engineering/team-tasks#4624 all wait on them. They need a committed owner rather than spare capacity, or the chain behind them stalls. **Waits on a sibling.** gitlab-org/quality/quality-engineering/team-tasks#4622 and gitlab-org/quality/quality-engineering/team-tasks#4624 on gitlab-org/quality/quality-engineering/team-tasks#4621 and gitlab-org/quality/quality-engineering/team-tasks#4635; gitlab-org/quality/quality-engineering/team-tasks#4623 on gitlab-org/quality/quality-engineering/team-tasks#4621. **Waits outside the epic.** gitlab-org/quality/quality-engineering/team-tasks#4637, on &457. gitlab-org/quality/quality-engineering/team-tasks#4634 is independent too, but it is already assigned and dated. ## Executive summary _Filled in when this epic closes._ - Teams holding environments: **TBD** - Environments per team, and the cap in force: **TBD** - Cost per team per month: **TBD** ## Sequencing Group ownership is a breaking change to how namespaces are stamped. Existing namespaces carry a username annotation and `kind: User` RoleBindings, and migration is delete-and-recreate. Cheap, but it means **the first modular team should onboard after gitlab-org/quality/quality-engineering/team-tasks#4621 lands**, not before. That is a dependency on [&449](https://gitlab.com/groups/gitlab-org/quality/-/work_items/449). **Three guardrails should not wait for this epic to start.** gitlab-org/quality/quality-engineering/team-tasks#4636 and gitlab-org/quality/quality-engineering/team-tasks#4640 are the conditions AppSec attached to its no-blocker position on gitlab-org/quality/quality-engineering/team-tasks#4627, and gitlab-org/quality/quality-engineering/team-tasks#4641 is a precondition of the decision rather than a follow-up to it: the allowlist on the shared front is a boundary only while a tenant cannot open their own ingress beside it. &450 is what ships that front, so leaving these until this epic starts means &450 closes describing a reach control that nothing yet enforces. ## Relationship to &458 &458's derived cutoff and `vcluster delete` stay. What changes is what happens next: the namespace is the environment, so the reaper deletes it too. Still the graceful path, so the teardown already verified clean on `hangar-host` still holds. The `caproni.gitlab.io/ttl` annotation becomes per environment, which is what the delivery team needs: `delivery-main` at a quarter alongside `delivery-mr-2821` at the default. ## Related, not the same [&319](https://gitlab.com/groups/gitlab-org/quality/-/work_items/319) (Test Environments) proposes team-owned environments with TTL, cost tracking and a catalog. Same shape, different substrate (GET/Terraform reference architectures) and different audience (PREP teams validating staging-like environments, not modular components against GitLab). Worth stating the boundary with that team deliberately rather than having it raised at planning. ## Exit criteria - [ ] A namespace is owned by a team group; every member reaches it, non-members do not - [ ] Someone changing team gains and loses access with no manual step - [ ] A team cannot exceed its namespace cap, and a namespace must carry its group's prefix - [ ] A disbanded team's namespace is reported, not silently deleted - [ ] Cost is attributable per team - [ ] A tenant cannot open an ingress beside the shared front, nor run a privileged pod on a shared node <!-- STATUS NOTE START --> <!-- STATUS NOTE END -->