mirror of
https://github.com/coder/coder.git
synced 2026-09-23 05:43:53 +08:00
Jeremy Ruppel
10717572ac
Surface base template prerequisites to admins before they create a
template in the Template Builder wizard.
Today, template prerequisites (Docker socket setup, Kubernetes auth, AWS
IAM policies) are only visible in the registry README after import.
Admins hit opaque provisioner errors and have to hunt for docs. This
change extracts the prerequisites from the README and serves them via
the API so the frontend can display them inline.
## How it works
Each base template README uses HTML comment markers (`<!--
prerequisites:start -->` / `<!-- prerequisites:end -->`) to delimit the
prerequisites section. At boot time, the base catalog loader reads the
README, extracts the content between markers via `strings.Index`, and
caches both the full README and the prerequisites string.
The prerequisites are served via a new `prerequisites` field on `GET
/api/v2/templatebuilder/bases`. The full README is included in the
composed template tar bundle and stored as the template version readme.
## Changes
- Add `README.md` with prerequisite markers to
`coderd/templatebuilder/bases/{docker,kubernetes,aws-linux}/`
- New `ExtractPrerequisites()` in `prerequisites.go` using literal
string matching
- `bases.go`: load README at boot, fail loudly if missing, extract
prerequisites
- `compose.go`: include README in `ComposeResult` and tar bundle
- `codersdk`: add `Prerequisites` field to `TemplateBuilderBase`
- Handler: populate prerequisites in bases response, set readme on
template version
<details>
<summary>Implementation notes</summary>
- Prerequisites extraction uses `strings.Index` for exact literal marker
matching; no regex or AST parser needed since we control the markers.
- YAML frontmatter is deliberately retained in the stored README. The
frontend `TemplateDocsPage` already strips it at render time via
`front-matter`.
- The prerequisite markers are HTML comments, invisible in rendered
markdown.
- The `RejectsMissingReadme` test enforces that every base template must
include a README.
- AWS Linux prerequisites span two H2 sections (`## Prerequisites` and
`## Required permissions / policy`), which is why heading-based parsing
was rejected in favor of explicit markers.
*Generated with the assistance of an AI coding agent. Reviewed by
@jeremyruppel.*
</details>
Relates to https://linear.app/codercom/issue/DEVEX-446
9.0 KiB
Generated
9.0 KiB
Generated
TemplateBuilder
List template builder base templates
Code samples
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templatebuilder/bases \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
GET /api/v2/templatebuilder/bases
Example responses
200 Response
{
"bases": [
{
"description": "string",
"icon": "string",
"id": "string",
"name": "string",
"os": "string",
"prerequisites": "string",
"variables": [
{
"default": [
0
],
"description": "string",
"name": "string",
"required": true,
"sensitive": true,
"type": "string"
}
]
}
]
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.TemplateBuilderBasesResponse |
To perform this operation, you must be authenticated. Learn more.
Compose template from base and modules
Code samples
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/templatebuilder/compose \
-H 'Content-Type: application/json' \
-H 'Coder-Session-Token: API_KEY'
POST /api/v2/templatebuilder/compose
Body parameter
{
"base_template_id": "string",
"base_variable_values": {
"property1": "string",
"property2": "string"
},
"modules": [
{
"id": "string",
"variables": {
"property1": "string",
"property2": "string"
}
}
]
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
body |
body | codersdk.TemplateBuilderComposeRequest | true | Compose request |
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK |
To perform this operation, you must be authenticated. Learn more.
Compose and create a template
Code samples
# Example request using curl
curl -X POST http://coder-server:8080/api/v2/templatebuilder/compose/template \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
POST /api/v2/templatebuilder/compose/template
Body parameter
{
"base_template_id": "string",
"base_variable_values": {
"property1": "string",
"property2": "string"
},
"description": "string",
"display_name": "string",
"icon": "string",
"modules": [
{
"id": "string",
"variables": {
"property1": "string",
"property2": "string"
}
}
],
"name": "string",
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"provisioner_tags": {
"property1": "string",
"property2": "string"
}
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
body |
body | codersdk.TemplateBuilderCreateTemplateRequest | true | Create template request |
Example responses
201 Response
{
"template": {
"active_user_count": 0,
"active_version_id": "eae64611-bd53-4a80-bb77-df1e432c0fbc",
"activity_bump_ms": 0,
"allow_user_autostart": true,
"allow_user_autostop": true,
"allow_user_cancel_workspace_jobs": true,
"autostart_requirement": {
"days_of_week": [
"monday"
]
},
"autostop_requirement": {
"days_of_week": [
"monday"
],
"weeks": 0
},
"build_time_stats": {
"property1": {
"p50": 123,
"p95": 146
},
"property2": {
"p50": 123,
"p95": 146
}
},
"cors_behavior": "simple",
"created_at": "2019-08-24T14:15:22Z",
"created_by_id": "9377d689-01fb-4abf-8450-3368d2c1924f",
"created_by_name": "string",
"default_ttl_ms": 0,
"deleted": true,
"deprecated": true,
"deprecation_message": "string",
"description": "string",
"disable_module_cache": true,
"display_name": "string",
"failure_ttl_ms": 0,
"icon": "string",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"max_port_share_level": "owner",
"name": "string",
"organization_display_name": "string",
"organization_icon": "string",
"organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
"organization_name": "string",
"provisioner": "terraform",
"require_active_version": true,
"time_til_dormant_autodelete_ms": 0,
"time_til_dormant_ms": 0,
"updated_at": "2019-08-24T14:15:22Z",
"use_classic_parameter_flow": true
}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | Created | codersdk.TemplateBuilderCreateTemplateResponse |
| 400 | Bad Request | Bad Request | codersdk.Response |
| 404 | Not Found | Not Found | codersdk.Response |
| 409 | Conflict | Conflict | codersdk.Response |
| 504 | Gateway Time-out | Gateway Timeout | codersdk.Response |
To perform this operation, you must be authenticated. Learn more.
List template builder modules
Code samples
# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templatebuilder/modules \
-H 'Accept: application/json' \
-H 'Coder-Session-Token: API_KEY'
GET /api/v2/templatebuilder/modules
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
base |
query | string | false | Base template example ID for OS-compatibility filtering |
Example responses
200 Response
{
"modules": [
{
"category": "string",
"compatible_os": [
"string"
],
"conflicts_with": [
"string"
],
"description": "string",
"display_name": "string",
"icon": "string",
"id": "string",
"variables": [
{
"default": [
0
],
"description": "string",
"name": "string",
"required": true,
"sensitive": true,
"type": "string"
}
],
"version": "string"
}
]
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | codersdk.TemplateBuilderModulesResponse |
To perform this operation, you must be authenticated. Learn more.