feat: allow users to pause prebuilt workspace reconciliation (#18700)

This PR provides two commands:
* `coder prebuilds pause`
* `coder prebuilds resume`

These allow the suspension of all prebuilds activity, intended for use
if prebuilds are misbehaving.

docs/reference/api/prebuilds.md

@@ -0,0 +1,79 @@
+# Prebuilds
+
+## Get prebuilds settings
+
+### Code samples
+
+```shell
+# Example request using curl
+curl -X GET http://coder-server:8080/api/v2/prebuilds/settings \
+  -H 'Accept: application/json' \
+  -H 'Coder-Session-Token: API_KEY'
+```
+
+`GET /prebuilds/settings`
+
+### Example responses
+
+> 200 Response
+
+```json
+{
+  "reconciliation_paused": true
+}
+```
+
+### Responses
+
+| Status | Meaning                                                 | Description | Schema                                                             |
+|--------|---------------------------------------------------------|-------------|--------------------------------------------------------------------|
+| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK          | [codersdk.PrebuildsSettings](schemas.md#codersdkprebuildssettings) |
+
+To perform this operation, you must be authenticated. [Learn more](authentication.md).
+
+## Update prebuilds settings
+
+### Code samples
+
+```shell
+# Example request using curl
+curl -X PUT http://coder-server:8080/api/v2/prebuilds/settings \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json' \
+  -H 'Coder-Session-Token: API_KEY'
+```
+
+`PUT /prebuilds/settings`
+
+> Body parameter
+
+```json
+{
+  "reconciliation_paused": true
+}
+```
+
+### Parameters
+
+| Name   | In   | Type                                                               | Required | Description                |
+|--------|------|--------------------------------------------------------------------|----------|----------------------------|
+| `body` | body | [codersdk.PrebuildsSettings](schemas.md#codersdkprebuildssettings) | true     | Prebuilds settings request |
+
+### Example responses
+
+> 200 Response
+
+```json
+{
+  "reconciliation_paused": true
+}
+```
+
+### Responses
+
+| Status | Meaning                                                         | Description  | Schema                                                             |
+|--------|-----------------------------------------------------------------|--------------|--------------------------------------------------------------------|
+| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)         | OK           | [codersdk.PrebuildsSettings](schemas.md#codersdkprebuildssettings) |
+| 304    | [Not Modified](https://tools.ietf.org/html/rfc7232#section-4.1) | Not Modified |                                                                    |
+
+To perform this operation, you must be authenticated. [Learn more](authentication.md).

docs/reference/api/schemas.md

@@ -4980,6 +4980,20 @@ Git clone makes use of this by parsing the URL from: 'Username for "https://gith
 | `reconciliation_backoff_lookback` | integer | false    |              | Reconciliation backoff lookback determines the time window to look back when calculating the number of failed prebuilds, which influences the backoff strategy.                                                                                                                                   |
 | `reconciliation_interval`         | integer | false    |              | Reconciliation interval defines how often the workspace prebuilds state should be reconciled.                                                                                                                                                                                                     |
 
+## codersdk.PrebuildsSettings
+
+```json
+{
+  "reconciliation_paused": true
+}
+```
+
+### Properties
+
+| Name                    | Type    | Required | Restrictions | Description |
+|-------------------------|---------|----------|--------------|-------------|
+| `reconciliation_paused` | boolean | false    |              |             |
+
 ## codersdk.Preset
 
 ```json
@@ -6058,6 +6072,7 @@ Git clone makes use of this by parsing the URL from: 'Username for "https://gith
 | `convert_login`                  |
 | `health_settings`                |
 | `notifications_settings`         |
+| `prebuilds_settings`             |
 | `workspace_proxy`                |
 | `organization`                   |
 | `oauth2_provider_app`            |

docs/reference/cli/index.md

@@ -65,6 +65,7 @@ Coder — A tool for provisioning self-hosted development environments with Terr
 | [<code>features</code>](./features.md)             | List Enterprise features                                                                                                     |
 | [<code>licenses</code>](./licenses.md)             | Add, delete, and list licenses                                                                                               |
 | [<code>groups</code>](./groups.md)                 | Manage groups                                                                                                                |
+| [<code>prebuilds</code>](./prebuilds.md)           | Manage Coder prebuilds                                                                                                       |
 | [<code>provisioner</code>](./provisioner.md)       | View and manage provisioner daemons and jobs                                                                                 |
 
 ## Options

docs/reference/cli/prebuilds.md

@@ -0,0 +1,34 @@
+<!-- DO NOT EDIT | GENERATED CONTENT -->
+# prebuilds
+
+Manage Coder prebuilds
+
+Aliases:
+
+* prebuild
+
+## Usage
+
+```console
+coder prebuilds
+```
+
+## Description
+
+```console
+Administrators can use these commands to manage prebuilt workspace settings.
+  - Pause Coder prebuilt workspace reconciliation.:
+
+     $ coder prebuilds pause
+
+  - Resume Coder prebuilt workspace reconciliation if it has been paused.:
+
+     $ coder prebuilds resume
+```
+
+## Subcommands
+
+| Name                                         | Purpose          |
+|----------------------------------------------|------------------|
+| [<code>pause</code>](./prebuilds_pause.md)   | Pause prebuilds  |
+| [<code>resume</code>](./prebuilds_resume.md) | Resume prebuilds |

docs/reference/cli/prebuilds_pause.md

@@ -0,0 +1,10 @@
+<!-- DO NOT EDIT | GENERATED CONTENT -->
+# prebuilds pause
+
+Pause prebuilds
+
+## Usage
+
+```console
+coder prebuilds pause
+```

docs/reference/cli/prebuilds_resume.md

@@ -0,0 +1,10 @@
+<!-- DO NOT EDIT | GENERATED CONTENT -->
+# prebuilds resume
+
+Resume prebuilds
+
+## Usage
+
+```console
+coder prebuilds resume
+```