diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index 0a8b2c07793c3..3c638524ee38a 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -5140,7 +5140,7 @@ const docTemplate = `{ "tags": [ "Templates" ], - "summary": "Get template metadata by ID", + "summary": "Get template settings by ID", "operationId": "get-template-metadata-by-id", "parameters": [ { @@ -5206,7 +5206,7 @@ const docTemplate = `{ "tags": [ "Templates" ], - "summary": "Update template metadata by ID", + "summary": "Update template settings by ID", "operationId": "update-template-metadata-by-id", "parameters": [ { @@ -5216,6 +5216,15 @@ const docTemplate = `{ "name": "template", "in": "path", "required": true + }, + { + "description": "Patch template settings request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.UpdateTemplateMeta" + } } ], "responses": { @@ -17213,6 +17222,89 @@ const docTemplate = `{ } } }, + "codersdk.UpdateTemplateMeta": { + "type": "object", + "properties": { + "activity_bump_ms": { + "description": "ActivityBumpMillis allows optionally specifying the activity bump\nduration for all workspaces created from this template. Defaults to 1h\nbut can be set to 0 to disable activity bumping.", + "type": "integer" + }, + "allow_user_autostart": { + "type": "boolean" + }, + "allow_user_autostop": { + "type": "boolean" + }, + "allow_user_cancel_workspace_jobs": { + "type": "boolean" + }, + "autostart_requirement": { + "$ref": "#/definitions/codersdk.TemplateAutostartRequirement" + }, + "autostop_requirement": { + "description": "AutostopRequirement and AutostartRequirement can only be set if your license\nincludes the advanced template scheduling feature. If you attempt to set this\nvalue while unlicensed, it will be ignored.", + "allOf": [ + { + "$ref": "#/definitions/codersdk.TemplateAutostopRequirement" + } + ] + }, + "cors_behavior": { + "$ref": "#/definitions/codersdk.CORSBehavior" + }, + "default_ttl_ms": { + "type": "integer" + }, + "deprecation_message": { + "description": "DeprecationMessage if set, will mark the template as deprecated and block\nany new workspaces from using this template.\nIf passed an empty string, will remove the deprecated message, making\nthe template usable for new workspaces again.", + "type": "string" + }, + "description": { + "type": "string" + }, + "disable_everyone_group_access": { + "description": "DisableEveryoneGroupAccess allows optionally disabling the default\nbehavior of granting the 'everyone' group access to use the template.\nIf this is set to true, the template will not be available to all users,\nand must be explicitly granted to users or groups in the permissions settings\nof the template.", + "type": "boolean" + }, + "display_name": { + "type": "string" + }, + "failure_ttl_ms": { + "type": "integer" + }, + "icon": { + "type": "string" + }, + "max_port_share_level": { + "$ref": "#/definitions/codersdk.WorkspaceAgentPortShareLevel" + }, + "name": { + "type": "string" + }, + "require_active_version": { + "description": "RequireActiveVersion mandates workspaces built using this template\nuse the active version of the template. This option has no\neffect on template admins.", + "type": "boolean" + }, + "time_til_dormant_autodelete_ms": { + "type": "integer" + }, + "time_til_dormant_ms": { + "type": "integer" + }, + "update_workspace_dormant_at": { + "description": "UpdateWorkspaceDormant updates the dormant_at field of workspaces spawned\nfrom the template. This is useful for preventing dormant workspaces being immediately\ndeleted when updating the dormant_ttl field to a new, shorter value.", + "type": "boolean" + }, + "update_workspace_last_used_at": { + "description": "UpdateWorkspaceLastUsedAt updates the last_used_at field of workspaces\nspawned from the template. This is useful for preventing workspaces being\nimmediately locked when updating the inactivity_ttl field to a new, shorter\nvalue.", + "type": "boolean" + }, + "use_classic_parameter_flow": { + "description": "UseClassicParameterFlow is a flag that switches the default behavior to use the classic\nparameter flow when creating a workspace. This only affects deployments with the experiment\n\"dynamic-parameters\" enabled. This setting will live for a period after the experiment is\nmade the default.\nAn \"opt-out\" is present in case the new feature breaks some existing templates.", + "type": "boolean" + } + } + }, "codersdk.UpdateUserAppearanceSettingsRequest": { "type": "object", "required": [ diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index cd6537de0e210..32bfb37caee3b 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -4527,7 +4527,7 @@ ], "produces": ["application/json"], "tags": ["Templates"], - "summary": "Get template metadata by ID", + "summary": "Get template settings by ID", "operationId": "get-template-metadata-by-id", "parameters": [ { @@ -4585,7 +4585,7 @@ ], "produces": ["application/json"], "tags": ["Templates"], - "summary": "Update template metadata by ID", + "summary": "Update template settings by ID", "operationId": "update-template-metadata-by-id", "parameters": [ { @@ -4595,6 +4595,15 @@ "name": "template", "in": "path", "required": true + }, + { + "description": "Patch template settings request", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/codersdk.UpdateTemplateMeta" + } } ], "responses": { @@ -15714,6 +15723,89 @@ } } }, + "codersdk.UpdateTemplateMeta": { + "type": "object", + "properties": { + "activity_bump_ms": { + "description": "ActivityBumpMillis allows optionally specifying the activity bump\nduration for all workspaces created from this template. Defaults to 1h\nbut can be set to 0 to disable activity bumping.", + "type": "integer" + }, + "allow_user_autostart": { + "type": "boolean" + }, + "allow_user_autostop": { + "type": "boolean" + }, + "allow_user_cancel_workspace_jobs": { + "type": "boolean" + }, + "autostart_requirement": { + "$ref": "#/definitions/codersdk.TemplateAutostartRequirement" + }, + "autostop_requirement": { + "description": "AutostopRequirement and AutostartRequirement can only be set if your license\nincludes the advanced template scheduling feature. If you attempt to set this\nvalue while unlicensed, it will be ignored.", + "allOf": [ + { + "$ref": "#/definitions/codersdk.TemplateAutostopRequirement" + } + ] + }, + "cors_behavior": { + "$ref": "#/definitions/codersdk.CORSBehavior" + }, + "default_ttl_ms": { + "type": "integer" + }, + "deprecation_message": { + "description": "DeprecationMessage if set, will mark the template as deprecated and block\nany new workspaces from using this template.\nIf passed an empty string, will remove the deprecated message, making\nthe template usable for new workspaces again.", + "type": "string" + }, + "description": { + "type": "string" + }, + "disable_everyone_group_access": { + "description": "DisableEveryoneGroupAccess allows optionally disabling the default\nbehavior of granting the 'everyone' group access to use the template.\nIf this is set to true, the template will not be available to all users,\nand must be explicitly granted to users or groups in the permissions settings\nof the template.", + "type": "boolean" + }, + "display_name": { + "type": "string" + }, + "failure_ttl_ms": { + "type": "integer" + }, + "icon": { + "type": "string" + }, + "max_port_share_level": { + "$ref": "#/definitions/codersdk.WorkspaceAgentPortShareLevel" + }, + "name": { + "type": "string" + }, + "require_active_version": { + "description": "RequireActiveVersion mandates workspaces built using this template\nuse the active version of the template. This option has no\neffect on template admins.", + "type": "boolean" + }, + "time_til_dormant_autodelete_ms": { + "type": "integer" + }, + "time_til_dormant_ms": { + "type": "integer" + }, + "update_workspace_dormant_at": { + "description": "UpdateWorkspaceDormant updates the dormant_at field of workspaces spawned\nfrom the template. This is useful for preventing dormant workspaces being immediately\ndeleted when updating the dormant_ttl field to a new, shorter value.", + "type": "boolean" + }, + "update_workspace_last_used_at": { + "description": "UpdateWorkspaceLastUsedAt updates the last_used_at field of workspaces\nspawned from the template. This is useful for preventing workspaces being\nimmediately locked when updating the inactivity_ttl field to a new, shorter\nvalue.", + "type": "boolean" + }, + "use_classic_parameter_flow": { + "description": "UseClassicParameterFlow is a flag that switches the default behavior to use the classic\nparameter flow when creating a workspace. This only affects deployments with the experiment\n\"dynamic-parameters\" enabled. This setting will live for a period after the experiment is\nmade the default.\nAn \"opt-out\" is present in case the new feature breaks some existing templates.", + "type": "boolean" + } + } + }, "codersdk.UpdateUserAppearanceSettingsRequest": { "type": "object", "required": ["terminal_font", "theme_preference"], diff --git a/coderd/templates.go b/coderd/templates.go index f9c5d8271a1e6..6b8fcd6f07981 100644 --- a/coderd/templates.go +++ b/coderd/templates.go @@ -38,7 +38,7 @@ import ( // Returns a single template. // -// @Summary Get template metadata by ID +// @Summary Get template settings by ID // @ID get-template-metadata-by-id // @Security CoderSessionToken // @Produce json @@ -629,12 +629,13 @@ func (api *API) templateByOrganizationAndName(rw http.ResponseWriter, r *http.Re httpapi.Write(ctx, rw, http.StatusOK, api.convertTemplate(template)) } -// @Summary Update template metadata by ID +// @Summary Update template settings by ID // @ID update-template-metadata-by-id // @Security CoderSessionToken // @Produce json // @Tags Templates // @Param template path string true "Template ID" format(uuid) +// @Param request body codersdk.UpdateTemplateMeta true "Patch template settings request" // @Success 200 {object} codersdk.Template // @Router /templates/{template} [patch] func (api *API) patchTemplateMeta(rw http.ResponseWriter, r *http.Request) { diff --git a/docs/reference/api/schemas.md b/docs/reference/api/schemas.md index b3824d0c9b9b8..92486afa359f3 100644 --- a/docs/reference/api/schemas.md +++ b/docs/reference/api/schemas.md @@ -8068,6 +8068,71 @@ Restarts will only happen on weekdays in this list on weeks which line up with W | `user_perms` | object | false | | User perms should be a mapping of user ID to role. The user ID must be the uuid of the user, not a username or email address. | | ยป `[any property]` | [codersdk.TemplateRole](#codersdktemplaterole) | false | | | +## codersdk.UpdateTemplateMeta + +```json +{ + "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 + }, + "cors_behavior": "simple", + "default_ttl_ms": 0, + "deprecation_message": "string", + "description": "string", + "disable_everyone_group_access": true, + "display_name": "string", + "failure_ttl_ms": 0, + "icon": "string", + "max_port_share_level": "owner", + "name": "string", + "require_active_version": true, + "time_til_dormant_autodelete_ms": 0, + "time_til_dormant_ms": 0, + "update_workspace_dormant_at": true, + "update_workspace_last_used_at": true, + "use_classic_parameter_flow": true +} +``` + +### Properties + +| Name | Type | Required | Restrictions | Description | +|------------------------------------|--------------------------------------------------------------------------------|----------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `activity_bump_ms` | integer | false | | Activity bump ms allows optionally specifying the activity bump duration for all workspaces created from this template. Defaults to 1h but can be set to 0 to disable activity bumping. | +| `allow_user_autostart` | boolean | false | | | +| `allow_user_autostop` | boolean | false | | | +| `allow_user_cancel_workspace_jobs` | boolean | false | | | +| `autostart_requirement` | [codersdk.TemplateAutostartRequirement](#codersdktemplateautostartrequirement) | false | | | +| `autostop_requirement` | [codersdk.TemplateAutostopRequirement](#codersdktemplateautostoprequirement) | false | | Autostop requirement and AutostartRequirement can only be set if your license includes the advanced template scheduling feature. If you attempt to set this value while unlicensed, it will be ignored. | +| `cors_behavior` | [codersdk.CORSBehavior](#codersdkcorsbehavior) | false | | | +| `default_ttl_ms` | integer | false | | | +| `deprecation_message` | string | false | | Deprecation message if set, will mark the template as deprecated and block any new workspaces from using this template. If passed an empty string, will remove the deprecated message, making the template usable for new workspaces again. | +| `description` | string | false | | | +| `disable_everyone_group_access` | boolean | false | | Disable everyone group access allows optionally disabling the default behavior of granting the 'everyone' group access to use the template. If this is set to true, the template will not be available to all users, and must be explicitly granted to users or groups in the permissions settings of the template. | +| `display_name` | string | false | | | +| `failure_ttl_ms` | integer | false | | | +| `icon` | string | false | | | +| `max_port_share_level` | [codersdk.WorkspaceAgentPortShareLevel](#codersdkworkspaceagentportsharelevel) | false | | | +| `name` | string | false | | | +| `require_active_version` | boolean | false | | Require active version mandates workspaces built using this template use the active version of the template. This option has no effect on template admins. | +| `time_til_dormant_autodelete_ms` | integer | false | | | +| `time_til_dormant_ms` | integer | false | | | +| `update_workspace_dormant_at` | boolean | false | | Update workspace dormant at updates the dormant_at field of workspaces spawned from the template. This is useful for preventing dormant workspaces being immediately deleted when updating the dormant_ttl field to a new, shorter value. | +| `update_workspace_last_used_at` | boolean | false | | Update workspace last used at updates the last_used_at field of workspaces spawned from the template. This is useful for preventing workspaces being immediately locked when updating the inactivity_ttl field to a new, shorter value. | +| `use_classic_parameter_flow` | boolean | false | | Use classic parameter flow is a flag that switches the default behavior to use the classic parameter flow when creating a workspace. This only affects deployments with the experiment "dynamic-parameters" enabled. This setting will live for a period after the experiment is made the default. An "opt-out" is present in case the new feature breaks some existing templates. | + ## codersdk.UpdateUserAppearanceSettingsRequest ```json diff --git a/docs/reference/api/templates.md b/docs/reference/api/templates.md index ea2e2c50cca7f..4f29fbdcdb5e1 100644 --- a/docs/reference/api/templates.md +++ b/docs/reference/api/templates.md @@ -952,7 +952,7 @@ Status Code **200** To perform this operation, you must be authenticated. [Learn more](authentication.md). -## Get template metadata by ID +## Get template settings by ID ### Code samples @@ -1083,24 +1083,64 @@ curl -X DELETE http://coder-server:8080/api/v2/templates/{template} \ To perform this operation, you must be authenticated. [Learn more](authentication.md). -## Update template metadata by ID +## Update template settings by ID ### Code samples ```shell # Example request using curl curl -X PATCH http://coder-server:8080/api/v2/templates/{template} \ + -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Coder-Session-Token: API_KEY' ``` `PATCH /templates/{template}` +> Body parameter + +```json +{ + "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 + }, + "cors_behavior": "simple", + "default_ttl_ms": 0, + "deprecation_message": "string", + "description": "string", + "disable_everyone_group_access": true, + "display_name": "string", + "failure_ttl_ms": 0, + "icon": "string", + "max_port_share_level": "owner", + "name": "string", + "require_active_version": true, + "time_til_dormant_autodelete_ms": 0, + "time_til_dormant_ms": 0, + "update_workspace_dormant_at": true, + "update_workspace_last_used_at": true, + "use_classic_parameter_flow": true +} +``` + ### Parameters -| Name | In | Type | Required | Description | -|------------|------|--------------|----------|-------------| -| `template` | path | string(uuid) | true | Template ID | +| Name | In | Type | Required | Description | +|------------|------|----------------------------------------------------------------------|----------|---------------------------------| +| `template` | path | string(uuid) | true | Template ID | +| `body` | body | [codersdk.UpdateTemplateMeta](schemas.md#codersdkupdatetemplatemeta) | true | Patch template settings request | ### Example responses