create a prebuilds group in every org that needs it

coder · SasSwart · Aug 27, 2025 · Jun 12, 2025 · Jun 12, 2025 · Jul 14, 2025
commit 1cd68e3df3411cf7fe241e8d2618b53973b556b5
diff --git a/coderd/database/dbauthz/dbauthz.go b/coderd/database/dbauthz/dbauthz.go
@@ -467,6 +467,14 @@ var (
 					rbac.ResourceFile.Type: {
 						policy.ActionRead,
 					},
+					rbac.ResourceGroup.Type: {
+						policy.ActionRead,
+						policy.ActionCreate,
+						policy.ActionUpdate,
+					},
+					rbac.ResourceGroupMember.Type: {
+						policy.ActionRead,
+					},
 				}),
 			},
 		}),

diff --git a/docs/admin/templates/extending-templates/prebuilt-workspaces.md b/docs/admin/templates/extending-templates/prebuilt-workspaces.md
@@ -235,12 +235,18 @@ The system always maintains the desired number of prebuilt workspaces for the ac
 
 ### Managing resource quotas
 
-Prebuilt workspaces can be used in conjunction with [resource quotas](../../users/quotas.md).
+To help prevent unexpected infrastructure costs, prebuilt workspaces can be used in conjunction with [resource quotas](../../users/quotas.md).
 Because unclaimed prebuilt workspaces are owned by the `prebuilds` user, you can:
 
 1. Configure quotas for any group that includes this user.
 1. Set appropriate limits to balance prebuilt workspace availability with resource constraints.
 
+When prebuilt workspaces are configured for an organization, Coder creates a "prebuilds" group in that organization and adds the prebuilds user to it. This group has a default quota allowance of 0, which you should adjust based on your needs:
+
+- **Set a quota allowance** on the "prebuilds" group to control how many prebuilt workspaces can be provisioned
+- **Monitor usage** to ensure the quota is appropriate for your desired number of prebuilt instances
+- **Adjust as needed** based on your template costs and desired prebuilt workspace pool size
+
 If a quota is exceeded, the prebuilt workspace will fail provisioning the same way other workspaces do.
 
 ### Template configuration best practices

diff --git a/enterprise/coderd/prebuilds/membership.go b/enterprise/coderd/prebuilds/membership.go
@@ -44,37 +44,74 @@ func (s StoreMembershipReconciler) ReconcileAll(ctx context.Context, userID uuid
 		return xerrors.Errorf("determine prebuild organization membership: %w", err)
 	}
 
-	systemUserMemberships := make(map[uuid.UUID]struct{}, 0)
+	orgMemberShips := make(map[uuid.UUID]struct{}, 0)
 	defaultOrg, err := s.store.GetDefaultOrganization(ctx)
 	if err != nil {
 		return xerrors.Errorf("get default organization: %w", err)
 	}
-	systemUserMemberships[defaultOrg.ID] = struct{}{}
+	orgMemberShips[defaultOrg.ID] = struct{}{}
 	for _, o := range organizationMemberships {
-		systemUserMemberships[o.ID] = struct{}{}
+		orgMemberShips[o.ID] = struct{}{}
 	}
 
 	var membershipInsertionErrors error
 	for _, preset := range presets {
-		_, alreadyMember := systemUserMemberships[preset.OrganizationID]
-		if alreadyMember {
-			continue
+		_, alreadyOrgMember := orgMemberShips[preset.OrganizationID]
+		if !alreadyOrgMember {
+			// Add the organization to our list of memberships regardless of potential failure below
+			// to avoid a retry that will probably be doomed anyway.
+			orgMemberShips[preset.OrganizationID] = struct{}{}
+
+			// Insert the missing membership
+			_, err = s.store.InsertOrganizationMember(ctx, database.InsertOrganizationMemberParams{
+				OrganizationID: preset.OrganizationID,
+				UserID:         userID,
+				CreatedAt:      s.clock.Now(),
+				UpdatedAt:      s.clock.Now(),
+				Roles:          []string{},
+			})
+			if err != nil {
+				membershipInsertionErrors = errors.Join(membershipInsertionErrors, xerrors.Errorf("insert membership for prebuilt workspaces: %w", err))
+				continue
+			}
 		}
-		// Add the organization to our list of memberships regardless of potential failure below
-		// to avoid a retry that will probably be doomed anyway.
-		systemUserMemberships[preset.OrganizationID] = struct{}{}
 
-		// Insert the missing membership
-		_, err = s.store.InsertOrganizationMember(ctx, database.InsertOrganizationMemberParams{
+		// Create a "prebuilds" group in the organization and add the system user to it
+		// This group will have a quota of 0 by default, which users can adjust based on their needs
+		prebuildsGroup, err := s.store.InsertGroup(ctx, database.InsertGroupParams{
+			ID:             uuid.New(),
+			Name:           "prebuilds",
+			DisplayName:    "Prebuilds",
 			OrganizationID: preset.OrganizationID,
-			UserID:         userID,
-			CreatedAt:      s.clock.Now(),
-			UpdatedAt:      s.clock.Now(),
-			Roles:          []string{},
+			AvatarURL:      "",
+			QuotaAllowance: 0, // Default quota of 0, users should set this based on their needs
+		})
+		if err != nil {
+			// If the group already exists, try to get it
+			if !database.IsUniqueViolation(err) {
+				membershipInsertionErrors = errors.Join(membershipInsertionErrors, xerrors.Errorf("create prebuilds group: %w", err))
+				continue
+			}
+			prebuildsGroup, err = s.store.GetGroupByOrgAndName(ctx, database.GetGroupByOrgAndNameParams{
+				OrganizationID: preset.OrganizationID,
+				Name:           "prebuilds",
+			})
+			if err != nil {
+				membershipInsertionErrors = errors.Join(membershipInsertionErrors, xerrors.Errorf("get existing prebuilds group: %w", err))
+				continue
+			}
+		}
+
+		// Add the system user to the prebuilds group
+		err = s.store.InsertGroupMember(ctx, database.InsertGroupMemberParams{
+			GroupID: prebuildsGroup.ID,
+			UserID:  userID,
 		})
 		if err != nil {
-			membershipInsertionErrors = errors.Join(membershipInsertionErrors, xerrors.Errorf("insert membership for prebuilt workspaces: %w", err))
-			continue
+			// Ignore unique violation errors as the user might already be in the group
+			if !database.IsUniqueViolation(err) {
+				membershipInsertionErrors = errors.Join(membershipInsertionErrors, xerrors.Errorf("add system user to prebuilds group: %w", err))
+			}
 		}
 	}
 	return membershipInsertionErrors