Aug 27, 2025 · Jun 12, 2025 · Jun 12, 2025 · Jul 14, 2025 · Jul 15, 2025 · Jul 29, 2025
diff --git a/coderd/database/dbauthz/dbauthz.go b/coderd/database/dbauthz/dbauthz.go
 rbac.ResourceFile.Type: {
 policy.ActionRead,
 },
 // Needs to be able to add the prebuilds system user to the "prebuilds" group in each organization that needs prebuilt workspaces
 // so that prebuilt workspaces can be scheduled and owned in those organizations.
 rbac.ResourceGroup.Type: {
 policy.ActionRead,
 policy.ActionCreate,
 policy.ActionUpdate,
 },
 rbac.ResourceGroupMember.Type: {
 policy.ActionRead,
 },
 }),
 },
 }),
diff --git a/coderd/database/queries.sql.go b/coderd/database/queries.sql.go
diff --git a/coderd/database/queries/organizationmembers.sql b/coderd/database/queries/organizationmembers.sql
 organization_id = @organization_id
 ELSE true
 END
  -- Filter by system type
 AND CASE WHEN @include_system::bool THEN TRUE ELSE is_system = false END
 ORDER BY
 -- Deterministic and consistent ordering of all users. This is to ensure consistent pagination.
 LOWER(username) ASC OFFSET @offset_opt
diff --git a/coderd/members.go b/coderd/members.go

 paginatedMemberRows, err := api.Database.PaginatedOrganizationMembers(ctx, database.PaginatedOrganizationMembersParams{
 OrganizationID: organization.ID,
 IncludeSystem:  false,
 // #nosec G115 - Pagination limits are small and fit in int32
 LimitOpt: int32(paginationParams.Limit),
 // #nosec G115 - Pagination offsets are small and fit in int32
diff --git a/docs/admin/templates/extending-templates/prebuilt-workspaces.md b/docs/admin/templates/extending-templates/prebuilt-workspaces.md

 ### 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
 "github.com/coder/quartz"
 )

 const (
 PrebuiltWorkspacesGroupName        = "coderprebuiltworkspaces"
 PrebuiltWorkspacesGroupDisplayName = "Prebuilt Workspaces"
 )

 // StoreMembershipReconciler encapsulates the responsibility of ensuring that the prebuilds system user is a member of all
 // organizations for which prebuilt workspaces are requested. This is necessary because our data model requires that such
 // prebuilt workspaces belong to a member of the organization of their eventual claimant.
 }
 }

 // ReconcileAll compares the current membership of a user to the membership required in order to create prebuilt workspaces.
 // If the user in question is not yet a member of an organization that needs prebuilt workspaces, ReconcileAll will create
 // the membership required.
 // ReconcileAll compares the current organization and group memberships of a user to the memberships required
 // in order to create prebuilt workspaces. If the user in question is not yet a member of an organization that
 // needs prebuilt workspaces, ReconcileAll will create the membership required.
 //
 // To facilitate quota management, ReconcileAll will ensure:
 // * the existence of a group (defined by PrebuiltWorkspacesGroupName) in each organization that needs prebuilt workspaces
 // * that the prebuilds system user belongs to the group in each organization that needs prebuilt workspaces
 // * that the group has a quota of 0 by default, which users can adjust based on their needs.
 //
 //This method does not have an opinion on transaction or lock management. These responsibilities are left to the caller.
 //ReconcileAll does not have an opinion on transaction or lock management. These responsibilities are left to the caller.
 func (s StoreMembershipReconciler) ReconcileAll(ctx context.Context, userID uuid.UUID, presets []database.GetTemplatePresetsWithPrebuildsRow) error {
 organizationMemberships, err := s.store.GetOrganizationsByUserID(ctx, database.GetOrganizationsByUserIDParams{
 UserID: userID,
 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{
 // determine whether the org already has a prebuilds group
 prebuildsGroupExists := true
 prebuildsGroup, err := s.store.GetGroupByOrgAndName(ctx, database.GetGroupByOrgAndNameParams{
 OrganizationID: preset.OrganizationID,
 UserID:         userID,
 CreatedAt:      s.clock.Now(),
 UpdatedAt:      s.clock.Now(),
 Roles:          []string{},
 Name:           PrebuiltWorkspacesGroupName,
 })
 if err != nil {
 if !xerrors.Is(err, sql.ErrNoRows) {
 membershipInsertionErrors = errors.Join(membershipInsertionErrors, xerrors.Errorf("get prebuilds group: %w", err))
 continue
 }
 prebuildsGroupExists = false
 }

 // if the prebuilds group does not exist, create it
 if !prebuildsGroupExists {
 // 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:           PrebuiltWorkspacesGroupName,
 DisplayName:    PrebuiltWorkspacesGroupDisplayName,
 OrganizationID: preset.OrganizationID,
 AvatarURL:      "",
 QuotaAllowance: 0, // Default quota of 0, users should set this based on their needs
 })
 if err != nil {
 membershipInsertionErrors = errors.Join(membershipInsertionErrors, xerrors.Errorf("create 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
Original file line number	Diff line number	Diff line change
Expand Up		@@ -487,6 +487,16 @@ var (
		rbac.ResourceFile.Type: {
		policy.ActionRead,
		},
		// Needs to be able to add the prebuilds system user to the "prebuilds" group in each organization that needs prebuilt workspaces
		// so that prebuilt workspaces can be scheduled and owned in those organizations.
		rbac.ResourceGroup.Type: {
		policy.ActionRead,
		policy.ActionCreate,
		policy.ActionUpdate,
		},
		rbac.ResourceGroupMember.Type: {
		policy.ActionRead,
		},
		}),
		},
		}),
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -89,6 +89,8 @@ WHERE
		organization_id = @organization_id
		ELSE true
		END
		-- Filter by system type
		AND CASE WHEN @include_system::bool THEN TRUE ELSE is_system = false END
		ORDER BY
		-- Deterministic and consistent ordering of all users. This is to ensure consistent pagination.
		LOWER(username) ASC OFFSET @offset_opt
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -203,6 +203,7 @@ func (api API) paginatedMembers(rw http.ResponseWriter, r http.Request) {

		paginatedMemberRows, err := api.Database.PaginatedOrganizationMembers(ctx, database.PaginatedOrganizationMembersParams{
		OrganizationID: organization.ID,
		IncludeSystem: false,
		// #nosec G115 - Pagination limits are small and fit in int32
		LimitOpt: int32(paginationParams.Limit),
		// #nosec G115 - Pagination offsets are small and fit in int32
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -233,12 +233,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
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -12,6 +12,11 @@ import (
		"github.com/coder/quartz"
		)

		const (
		PrebuiltWorkspacesGroupName = "coderprebuiltworkspaces"
ssncferreira marked this conversation as resolved. Show resolvedHide resolved
		PrebuiltWorkspacesGroupDisplayName = "Prebuilt Workspaces"
		)

		// StoreMembershipReconciler encapsulates the responsibility of ensuring that the prebuilds system user is a member of all
		// organizations for which prebuilt workspaces are requested. This is necessary because our data model requires that such
		// prebuilt workspaces belong to a member of the organization of their eventual claimant.
Expand All		@@ -27,11 +32,16 @@ func NewStoreMembershipReconciler(store database.Store, clock quartz.Clock) Stor
		}
		}

		// ReconcileAll compares the current membership of a user to the membership required in order to create prebuilt workspaces.
		// If the user in question is not yet a member of an organization that needs prebuilt workspaces, ReconcileAll will create
		// the membership required.
		// ReconcileAll compares the current organization and group memberships of a user to the memberships required
		// in order to create prebuilt workspaces. If the user in question is not yet a member of an organization that
		// needs prebuilt workspaces, ReconcileAll will create the membership required.
		//
		// To facilitate quota management, ReconcileAll will ensure:
		// * the existence of a group (defined by PrebuiltWorkspacesGroupName) in each organization that needs prebuilt workspaces
		// * that the prebuilds system user belongs to the group in each organization that needs prebuilt workspaces
		// * that the group has a quota of 0 by default, which users can adjust based on their needs.
		//
		//This method does not have an opinion on transaction or lock management. These responsibilities are left to the caller.
		//ReconcileAll does not have an opinion on transaction or lock management. These responsibilities are left to the caller.
		func (s StoreMembershipReconciler) ReconcileAll(ctx context.Context, userID uuid.UUID, presets []database.GetTemplatePresetsWithPrebuildsRow) error {
		organizationMemberships, err := s.store.GetOrganizationsByUserID(ctx, database.GetOrganizationsByUserIDParams{
		UserID: userID,
Expand All		@@ -44,37 +54,80 @@ 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{
		// determine whether the org already has a prebuilds group
		prebuildsGroupExists := true
		prebuildsGroup, err := s.store.GetGroupByOrgAndName(ctx, database.GetGroupByOrgAndNameParams{
		OrganizationID: preset.OrganizationID,
		UserID: userID,
		CreatedAt: s.clock.Now(),
		UpdatedAt: s.clock.Now(),
		Roles: []string{},
		Name: PrebuiltWorkspacesGroupName,
		})
		if err != nil {
		if !xerrors.Is(err, sql.ErrNoRows) {
		membershipInsertionErrors = errors.Join(membershipInsertionErrors, xerrors.Errorf("get prebuilds group: %w", err))
		continue
		}
		prebuildsGroupExists = false
		}

		// if the prebuilds group does not exist, create it
		if !prebuildsGroupExists {
		// 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: PrebuiltWorkspacesGroupName,
		DisplayName: PrebuiltWorkspacesGroupDisplayName,
		OrganizationID: preset.OrganizationID,
		AvatarURL: "",
		QuotaAllowance: 0, // Default quota of 0, users should set this based on their needs
Copy link Contributor ssncferreiraAug 25, 2025 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Correct me if I'm wrong, but does this mean that once this change is rolled out, no more prebuilt workspaces will be able to be provisioneduntil the Quota Allowance is changed? Or is the prebuilds user still part of the`Everyone` group? Just asking because, in case there is a need for user action, we might need to consider this a breaking change and explicitly document the steps to set this allowance. Copy link ContributorAuthor SasSwartAug 27, 2025 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. the prebuilds user is still a member of the everyone group, so this shouldn't be too much of a breaking change. ssncferreira reacted with thumbs up emoji Copy link Contributor ssncferreiraAug 27, 2025• edited Loading Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Ok, thanks for the clarification! nit(non-blocking): It might be helpful to also add this info to the documentation, that the prebuilds user is a member of the`Everyone` group (which also has a quota allowance). Maybe also include a section explaining that if the quota is exceeded, the workspace build will fail and the prebuilds group quota allowance should be increased.
		})
		if err != nil {
		membershipInsertionErrors = errors.Join(membershipInsertionErrors, xerrors.Errorf("create 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
Expand Down