Enforce top-level group limit against lifetime creations

What does this MR do and why?

This MR closes three ways around the free-tier limit of three top-level groups. The first also affected the identity verification limit on group creation, since both read the same count.

All three changes are behind the top_level_group_creation_tracking feature flag. With the flag off, the limit behaves exactly as it does today and nothing is written to the new table, so deploying this MR changes nothing until the flag is enabled.

Deleting a group freed up a slot. User#created_top_level_group_count counted live rows. namespace_details rows are deleted along with the namespace, so deleting a group erased the record that the user had created it. A user could create, delete and create again, and the limit never applied.

This MR stores a lifetime count in a new abuse_metadata table, which is only ever incremented. That happens inside the group creation transaction and when a subgroup is moved to the top level. The table has one row per user and keeps metrics in a jsonb column, so more abuse-prevention metrics can be added later without schema changes. AntiAbuse::UserMetadata validates the column against a JSON schema and accepts only known metric keys.

There is no backfill. When a user's count isn't stored yet, reading it computes the current number of top-level groups they created and stores that. The write only fills in a missing key, so it never overwrites an increment that happened at the same time. An increment does the same in a single upsert: if nothing is stored, it starts from the current number without the group being created or promoted, then adds one.

Moving a subgroup to the top level was counted against the wrong user. The transfer check looked at the subgroup's creator. When someone else had created the subgroup, for example a service account, the user moving it to the top level was never checked or counted. Moves to the top level are now checked and counted against the user doing the move. The increment runs inside the transfer transaction, so it commits and rolls back with the move.

Service accounts had their own allowance. A group or project service account was checked and counted against its own limit. Each service account had a fresh allowance and could create more service accounts, so a chain of them could create or promote top-level groups without the limit ever reaching a person.

For service accounts provisioned by a group or project, the new Namespaces::TopLevelGroupLimit follows created_by back to the first human account, and checks and counts against that user. This applies to both group creation and promotion. created_by always points at an older account, so the walk can't loop. It's capped at 10 steps anyway.

If the walk ends without a human (the creator was deleted, or the chain is longer than 10 steps) or at a banned user, the action is refused. users.created_by_id has no foreign key, so falling back to the service account would let someone reset the chain by deleting the root account. Instance-level service accounts, which have no provisioning group or project, are unchanged.

Behavior changes

With the flag on:

  • The limit now counts every top-level group a user has ever created. Deleting a top-level group no longer frees a slot.
  • Because there is no backfill, an existing user's count starts the first time it's read or written after the flag is enabled (visiting the new group page, or creating or promoting a group). Groups deleted before that moment aren't counted.
  • Moving a subgroup to the top level uses up the limit of the person moving it, not the creator's. If only the creator is at the limit, the move is allowed.
  • A top-level group created or promoted by a group or project service account uses up the limit of the person who created that service account. If no such person can be found, or they're banned, the action is refused.

Alternatives considered

  • Counting group_created audit events was rejected. Those events survive deletion, but they aren't emitted for subgroup transfers, and they're written after the creation transaction commits, so the count could drift downward.
  • A column on user_details with a batched background migration was the first approach. It was replaced with the abuse_metadata table, so new metrics don't each need a column, and with lazy counting instead of a backfill.

References

Feature flag

  • top_level_group_creation_tracking (gitlab_com_derisk, off by default) controls all three changes. With it off:
    • the limit reads the current number of top-level groups the user created
    • moves to the top level are checked against the subgroup's creator, as before
    • nothing is read from or written to abuse_metadata
  • The flag is checked once, in Namespaces::TopLevelGroupLimit.enabled?, against the :instance actor. One request can read one user's count while charging another, so a per-user actor could apply the old rule to one and the new rule to the other. That means no percentage rollout: the flag is on or off for all of GitLab.com.

Database

  • CreateAbuseMetadata creates abuse_metadata:
    • user_id bigint primary key, with a foreign key to users that deletes the row with the user
    • created_at and updated_at
    • metadata jsonb DEFAULT '{}' NOT NULL
  • The table is in gitlab_main_user, with user_id as the sharding key.
  • There is no data migration.
Query plans

All plans are from gitlab-production-main on Database Lab. abuse_metadata doesn't exist in production yet, so for queries 1, 3 and 5 it was created on the clone as the migration defines it (without the later check_abuse_metadata_metadata_size CHECK constraint, which doesn't change the plans), seeded with 1,000,000 rows (one per user), and analyzed before explaining. All queries run only with top_level_group_creation_tracking enabled.

1. Read a user's stored count

Runs on every top-level group limit check (Namespaces::TopLevelGroupsCreatedCount#value).

SELECT (metadata ->> 'top_level_groups_created_count')::integer FROM "abuse_metadata" WHERE "abuse_metadata"."user_id" = <user_id> LIMIT 1

Plan: https://console.postgres.ai/shared/bad7ef92-4053-4f03-9d99-b5ad5d405aa5 (Index Scan on abuse_metadata_pkey, 1 row, 0.6 ms warm, buffers: 7 hit / 0 read. A user with no row: 0 rows, 2.6 ms cold, buffers: 3 hit / 3 read)

2. Count the top-level groups a user created

Runs only when a user's count isn't stored yet: once on the first read, and on the first increment if nothing was read before. This query isn't new: on master it runs on every limit check.

SELECT COUNT(*) FROM "namespace_details" INNER JOIN "namespaces" ON "namespaces"."id" = "namespace_details"."namespace_id" WHERE "namespace_details"."creator_id" = <user_id> AND "namespaces"."parent_id" IS NULL AND "namespaces"."type" = 'Group'

Same plan as query 4, which adds one filter: Index Scan on index_namespace_details_on_creator_id, then Index Only Scan on index_groups_on_parent_id_id. For a recent account: 1 row, 7.5 ms cold, buffers: 12 hit / 5 read.

The cost grows with the number of namespaces a user created, because project namespaces are included in namespace_details. For an account with about 59,000 namespaces it took 18.6 s cold (buffers: 236,621 hit / 44,884 read) and 99 ms warm (281,506 hit). Counts are only computed and recorded for users the limit applies to (SaaS, enforce_top_level_group_limits on, not exempt). Exempt users include accounts created before the limit's start date, which are the heavy ones, so they never reach this query from the increment path.

3. Store the first count

Runs once per user, right after query 2 on the read path (AntiAbuse::UserMetadata.initialize_metric). It only fills in the key if it's still missing.

INSERT INTO "abuse_metadata" ("user_id","metadata","created_at","updated_at") VALUES (<user_id>, '{"top_level_groups_created_count":<count>}', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP) ON CONFLICT ("user_id") DO UPDATE SET metadata = EXCLUDED.metadata || abuse_metadata.metadata, updated_at = NOW() RETURNING "user_id"

Plan (new row): https://console.postgres.ai/shared/d56d6794-9cdc-4243-9f8b-233ec0491342 (Insert on abuse_metadata, 1 row, 162 ms cold, most of it the first foreign key lookup on users; buffers: 19 hit / 0 read. Warm, the same insert takes about 5.7 ms, of which the foreign key trigger is 5.4 ms)

Plan (row exists): https://console.postgres.ai/shared/ff8ec437-7208-4054-9cb9-21b0c391815a (Insert on abuse_metadata with conflict on abuse_metadata_pkey, 1 row, 2.6 ms cold, buffers: 26 hit / 4 read)

4. Count the top-level groups a user created, excluding one group

Runs when a group is created or moved to the top level, no count is stored yet, and the limit applies to the user (Namespaces::TopLevelGroupsCreatedCount#increment!). Same as query 2, with one extra condition.

SELECT COUNT(*) FROM "namespace_details" INNER JOIN "namespaces" ON "namespaces"."id" = "namespace_details"."namespace_id" WHERE "namespace_details"."creator_id" = <user_id> AND "namespaces"."parent_id" IS NULL AND "namespaces"."type" = 'Group' AND "namespace_details"."namespace_id" != <namespace_id>

Plan: https://console.postgres.ai/shared/8cd8edb4-a956-4943-91fc-9fdbade39bc2 (Same plan as query 2, 1 row, 3.3 ms warm, buffers: 17 hit / 0 read)

5. Increment the count

Runs inside the group creation or transfer transaction (AntiAbuse::UserMetadata.increment_metric).

INSERT INTO "abuse_metadata" ("user_id","metadata","created_at","updated_at") VALUES (<user_id>, '{"top_level_groups_created_count":<initial + 1>}', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP) ON CONFLICT ("user_id") DO UPDATE SET metadata = abuse_metadata.metadata || jsonb_build_object('top_level_groups_created_count', COALESCE((abuse_metadata.metadata ->> 'top_level_groups_created_count')::integer, <initial>) + 1), updated_at = NOW() RETURNING "user_id"

Plan (row exists): https://console.postgres.ai/shared/19cf5f56-7de5-4bbe-b205-3c0ba1449824 (Insert on abuse_metadata with conflict on abuse_metadata_pkey, 1 row, 0.4 ms warm, buffers: 28 hit / 0 read)

Plan (new row): https://console.postgres.ai/shared/43c5b947-8183-406e-9f6a-d875cb07c0a7 (Insert on abuse_metadata, 1 row, 5.7 ms warm, of which the foreign key trigger is 5.4 ms; buffers: 19 hit / 0 read)

How to set up and validate locally

  1. Start GDK with GITLAB_SIMULATE_SAAS=1 and enable the flags in gdk rails console:
    Feature.enable(:enforce_top_level_group_limits)
    Feature.enable(:top_level_group_creation_tracking)
  2. Sign in as a free user who was created after User::FREE_USER_TOP_LEVEL_GROUP_LIMIT_FROM_DATE and doesn't belong to a paid namespace.
  3. Create three top-level groups, then permanently delete one of them.
  4. Try to create another top-level group. It is blocked.
  5. Create a subgroup in one of the remaining groups and move it to the top level. The move is blocked with the top-level group limit message.
  6. As the same user, create a group service account in one of your groups, give it the Owner role, and create a personal access token for it.
  7. Use the token to create a top-level group through the API (POST /api/v4/groups). It is blocked, because the service account's creator is at the limit.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Jay

Merge request reports

Loading
Loading