opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-21 20:51:01 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
bca0ce04ca8a6b9929d1191aa838377ee7716e4e
coder/docs/reference/api/templatebuilder.md
T
Jeremy Ruppel de31c7c18e feat: add TemplateBuilderCreateTemplate SDK types and client method (#26360) 
Adds `POST /api/v2/templatebuilder/compose/template`, a synchronous
endpoint that composes a template from a base and modules, validates it
via a provisioner import job, and creates the template in a single
request.

The handler composes terraform files, bundles them as a tar, inserts the
file with hash-based dedup, creates a template version with an import
job, waits up to 2 minutes for the job to complete, classifies errors
for known failure modes (network-unreachable registry, DNS failures),
then creates the template on success. Canceled and failed jobs return
appropriate error responses.

Also adds `hclwrite.Format` to composed terraform output for canonical
HCL formatting.

Closes https://linear.app/codercom/issue/DEVEX-279

<details>
<summary>Implementation notes</summary>

- SDK types and client method in `codersdk/templatebuilder.go` with
validation tags matching the standard template creation path
(`template_display_name`, `lt=128`)
- `ClassifyProvisionerError` in `coderd/templatebuilder/errors.go`
detects DNS, connection refused, i/o timeout, and TLS handshake failures
and returns actionable messages
- `waitForProvisionerJob` polls with a ramp-up interval schedule (100ms,
200ms, 500ms, then 1s steady) and accepts an `onUpdate` callback for
future SSE streaming
- Audit logging for both template and template version creation
- TOCTOU name uniqueness: early check for fast feedback, DB unique
constraint catch for the race window (returns 409, not 500)
- Swagger annotations for all error responses (400, 404, 409, 504)

</details>

> 🤖 Generated by Coder Agents
2026-06-15 18:12:55 -04:00

8.5 KiB
Generated
Raw Blame History

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"
    }
  ]
}

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",
  "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",
  "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.

Reference in New Issue View Git Blame Copy Permalink